@superblocksteam/vite-plugin-file-sync 2.0.151 → 2.0.152-next.0

package/dist/ai-service/agent/tools/databases/dev-database-tasks.js

@@ -7,7 +7,7 @@ import { PermissionLevel, ToolCategory } from "../../tools2/types.js";
 export {};
 // Master parity: the only user-controlled requirement fields are
 // `logicalName` and (optionally) `migrationDirectory`. Engine, extensions,
-// sizing, replicaCount, version, and the dev environment name are
+// sizing, replicaCount, version, and the editor-mode profile are
 // platform-controlled — the server resolves them from the org's
 // lifecycle policy, so exposing them on the LLM surface would let Clark
 // invent values the platform later overrides.
@@ -19,7 +19,7 @@ const databaseRequirementSchema = z.object({
     migrationDirectory: z
         .string()
         .optional()
-        .describe("Repo-relative path to the directory holding the app's SQL migrations. Set this explicitly when provisionDatabase should enable startApplyDevDatabaseMigrations; `db/migrations/` is the recommended convention. Files inside must match `<digits>_<description>.sql` (e.g. `0001_init.sql`, `0002_add_users.sql`); the leading digits are the sort key and the runner applies them in lexicographic order against the in-DB ledger. Migrations run in edit and deployed — put seed/INSERT rows here only when deployed apps will always need that data; for edit-only test/demo data insert at runtime against the integration instead of a .sql seed migration."),
+        .describe("Repo-relative path to the directory holding the app's SQL migrations. Set this explicitly when provisionDatabase should enable startApplyDevDatabaseMigrations; `db/migrations/` is the recommended convention. Files inside must match `<digits>_<description>.sql` (e.g. `0001_init.sql`, `0002_add_users.sql`); the leading digits are the sort key and the runner applies them in lexicographic order against the in-DB ledger. Migrations run in authoring and on production deploys — put seed/INSERT rows here only when deployed apps will always need that data; for authoring-only test/demo data insert at runtime against the integration instead of a .sql seed migration."),
 });
 const provisionInputSchema = z.object({
     requirement: databaseRequirementSchema,
@@ -71,12 +71,20 @@ export const watchDevDatabaseProvisionTaskMetadata = {
     name: "watchDevDatabaseProvision",
     pollSchedule: { factor: 1.5, initialMs: 2_000, maxMs: 30_000 },
 };
-// Empty LLM input: Clark must not pin migrate to a provision-primary
-// bindingKey. The server fans out migrate_schema across every eligible
-// editor Environments datatag (ENG-3469).
-const applyMigrationsInputSchema = z.object({});
+// Clark must not pin migrate to a provision-primary bindingKey. The server
+// fans out migrate_schema across every eligible editor Environments datatag
+// (ENG-3469). The only LLM-facing field is acknowledgeDestructive.
+const applyMigrationsInputSchema = z.object({
+    acknowledgeDestructive: z
+        .boolean()
+        .optional()
+        .describe("Set true to re-request a destructive apply after a prior call failed with DESTRUCTIVE_MIGRATION_ACK_REQUIRED (DROP TABLE/DATABASE/SCHEMA, TRUNCATE, DROP COLUMN). This raises a permission request the user must approve before the destructive change runs; you do not need a separate chat confirmation first."),
+});
 const applyMigrationsHandleSchema = z.object({
     bindingKey: z.string().min(1).optional(),
+    // Captured at start() so entityTag can still be built if a later
+    // poll/migrated envelope omits logicalName (optional on the response).
+    logicalName: z.string().optional(),
     requestId: z.string().min(1),
     siblingTaskIds: z.array(z.string().min(1)).optional(),
 });
@@ -92,18 +100,20 @@ const applyMigrationsHandleSchema = z.object({
  */
 export const provisionDevDatabaseTaskMetadata = {
     category: ToolCategory.DATA,
-    // ALLOW: createDevDb is idempotent (returns the existing dev binding
-    // if one exists for this app+env) and scoped to a lifecycle-managed
-    // dev database invisible to anything but Clark.
+    // ALLOW: createDevDb is idempotent when the requested logical database
+    // matches the existing app+profile binding. A differently named database
+    // is rejected because an application supports only one App Database.
     defaultPermission: PermissionLevel.ALLOW,
-    // Substance mirrors master's `createDevDb`: lifecycle-managed binding
-    // on Amazon RDS, returns lifecycle progress. Engine/extensions and the
-    // dev environment name are platform-controlled, so they're not in the
-    // input. BG wrapping (taskId, don't waitForTask, check first) is the
-    // only behavioral delta from master.
-    description: "Create or reuse a dev App Database binding for this application on Amazon RDS as a BACKGROUND TASK. Clark provisions the database and returns lifecycle progress. Returns a taskId IMMEDIATELY while RDS provisioning runs in the background; the user already sees live progress in the chat's background-tasks indicator. " +
-        "DO NOT call waitForTask right after this — that defeats the whole point of a background task and blocks your turn for minutes while RDS spins up. Instead: keep working on whatever does NOT depend on the database (scaffold the UI, draft API code that will use the binding, write SQL migration files, plan next steps). When you reach a step that genuinely cannot proceed without the connection details, FIRST call checkTask({ taskId }) — it returns instantly. Only fall back to waitForTask if checkTask still reports state='running' AND you literally have no other useful work to do. " +
-        'On completion the result includes bindingKey, integrationId, lifecycleState, and connectionMetadata. App Database bindings use IAM authentication. Use integrationId only for tool inputs or generated source code such as postgres(...); do not repeat internal UUIDs in user-facing chat. When declaring the integration in an SDK API, derive a valid lowercase snake_case integrations map key from requirement.logicalName (normalize non-alphanumeric to _, prefix db_ if needed, disambiguate collisions; e.g. pokemon_tracker → pokemon_tracker: postgres(POKEMON_TRACKER), Orders DB → orders_db) so code and TraceView match the database name — never a generic key like db. This task ONLY creates the database server + an integration; it does NOT apply SQL migrations — query attempts will fail with `relation "X" does not exist` until you call startApplyDevDatabaseMigrations. Cancellation only stops local polling; the underlying RDS provisioning continues on the server.',
+    // Substance mirrors master's `createDevDb`: App Database binding
+    // (Aurora or RDS depending on the Superblocks environment — never
+    // hard-code either product; APPS-5377), returns lifecycle progress.
+    // Engine/extensions and the editor-mode profile are
+    // platform-controlled, so they're not in the input. BG wrapping
+    // (taskId, don't waitForTask, check first) is the only behavioral
+    // delta from master.
+    description: "Create the application's dev App Database binding, or reuse it when the same logical database was already provisioned, as a BACKGROUND TASK. Only one App Database per application is supported; never reinterpret a request for another database as a request to add tables or migrations to the existing database. Clark provisions a cloud Postgres database (Amazon Aurora or Amazon RDS depending on the Superblocks environment — do NOT assume either product) and returns lifecycle progress. Returns a taskId IMMEDIATELY while provisioning runs in the background; the user already sees live progress in the chat's background-tasks indicator. " +
+        "DO NOT call waitForTask right after this — that defeats the whole point of a background task and blocks your turn for minutes while the database spins up. Instead: keep working on whatever does NOT depend on the database (scaffold the UI, draft API code that will use the binding, write SQL migration files, plan next steps). When you reach a step that genuinely cannot proceed without the connection details, FIRST call checkTask({ taskId }) — it returns instantly. Only fall back to waitForTask if checkTask still reports state='running' AND you literally have no other useful work to do. " +
+        'On completion the result includes bindingKey, integrationId, entityTag, lifecycleState, connectionMetadata, and providerLabel. App Database bindings use IAM authentication. Use providerLabel when naming the cloud product in user-facing chat (e.g. "Amazon Aurora" or "App Database"); NEVER invent "RDS" or "Aurora" when providerLabel is absent or says "App Database" — Aurora still uses the AWS RDS API and *.rds.amazonaws.com hostnames. Use integrationId only for tool inputs or generated source code such as postgres(...). MUST NEVER paste bare integrationId UUIDs or phrases like "Integration ID is …" in user-facing chat — when referring to this managed database for the user, paste entityTag (e.g. @OrdersDB[id=…]) so the UI shows a name sticker. When declaring the integration in an SDK API, derive a valid lowercase snake_case integrations map key from requirement.logicalName (normalize non-alphanumeric to _, prefix db_ if needed, disambiguate collisions; e.g. pokemon_tracker → pokemon_tracker: postgres(POKEMON_TRACKER), Orders DB → orders_db) so code and TraceView match the database name — never a generic key like db. This task ONLY creates the database server + an integration; it does NOT apply SQL migrations — query attempts will fail with `relation "X" does not exist` until you call startApplyDevDatabaseMigrations. Cancellation only stops local polling; the underlying cloud provisioning continues on the server.',
     externalHandleSchema: provisionHandleSchema,
     inputSchema: provisionInputSchema,
     name: "provisionDatabase",
@@ -115,10 +125,8 @@ export const provisionDevDatabaseTaskMetadata = {
  */
 export const applyDevDatabaseMigrationsTaskMetadata = {
     category: ToolCategory.DATA,
-    // ALLOW: applies idempotent working-state SQL migrations. The runner
-    // skips versions already in the ledger; re-firing is safe. Filename
-    // validation + destructive-op detection on the server side are the
-    // safety net.
+    // ALLOW for additive migrations. Schema-destroying SQL is blocked by the
+    // server until acknowledgeDestructive is set after an explicit user confirm.
     defaultPermission: PermissionLevel.ALLOW,
     // Substance mirrors master's `applyMigrations`: SQL files come from the
     // binding's `migrationDirectory` set on provisionDatabase (no implicit
@@ -126,9 +134,10 @@ export const applyDevDatabaseMigrationsTaskMetadata = {
     // automatically, which is a lie when provisionDatabase didn't set
     // one). BG wrapping (taskId, don't waitForTask, check first) is the
     // only behavioral delta from master.
-    description: "Run the application's working-state SQL migrations against every eligible editor datatag binding for this application's Amazon RDS databases as a BACKGROUND TASK. Returns a taskId IMMEDIATELY; the user already sees live progress in the chat's background-tasks indicator. " +
+    description: "Run the application's working-state SQL migrations against every eligible editor datatag binding for this application's App Databases as a BACKGROUND TASK. Returns a taskId IMMEDIATELY; the user already sees live progress in the chat's background-tasks indicator. " +
         "DO NOT call waitForTask right after this — that defeats the whole point of a background task and blocks your turn while migrations run. Instead: keep working on anything that does not need migrations to have landed yet (UI scaffolding, additional API code, the next migration file). When you reach a step that genuinely needs migrationState='migrated' (for example, executing a SELECT against the new tables), FIRST call checkTask({ taskId }) — it returns instantly. Only fall back to waitForTask if checkTask still reports state='running' AND there is nothing else useful to do. " +
-        "REQUIRED after provisionDatabase if any application tables need to exist — provisioning only creates an empty RDS database. Reads SQL files from each binding's migrationDirectory set on provisionDatabase and applies any not yet recorded in the in-DB migration ledger; if provisionDatabase did not set a migrationDirectory, no SQL files are loaded. Seed/INSERT rows belong in migrations only when deployed apps will always need that data; for edit-only test/demo data insert at runtime against the integration instead of a .sql seed file. Re-firing is safe; already-applied versions are skipped. The terminal result includes migrationState='migrated' on success.",
+        "REQUIRED after provisionDatabase if any application tables need to exist — provisioning only creates an empty App Database. Reads SQL files from each binding's migrationDirectory set on provisionDatabase and applies any not yet recorded in the in-DB migration ledger; if provisionDatabase did not set a migrationDirectory, no SQL files are loaded. Seed/INSERT rows belong in migrations only when deployed apps will always need that data; for authoring-only test/demo data insert at runtime against the integration instead of a .sql seed file. Re-firing is safe; already-applied versions are skipped. The terminal result includes migrationState='migrated' on success. " +
+        "If the server returns errorCode DESTRUCTIVE_MIGRATION_ACK_REQUIRED, immediately re-call startApplyDevDatabaseMigrations with acknowledgeDestructive=true. That re-call raises a permission request the user approves or denies in the UI before any destructive change runs - the approval button is the confirmation, so you do not need to ask in chat first. Never run the migration another way (for example raw SQL) or tell the user to drop objects manually.",
     externalHandleSchema: applyMigrationsHandleSchema,
     inputSchema: applyMigrationsInputSchema,
     name: "startApplyDevDatabaseMigrations",
@@ -139,6 +148,74 @@ const TERMINAL_LIFECYCLE_STATES = new Set([
     "failed",
     "cancelled",
 ]);
+/** Max length for code/message/requestId/providerLabel in agent-facing
+ *  lifecycle fields. Matches `SAFE_INTERP_MAX_LEN` in build-install-packages.ts
+ *  so a multi-KB provider string cannot crowd out the rest of agent context. */
+const LIFECYCLE_FAILURE_FIELD_MAX_LEN = 100;
+function sanitizeLifecycleFailureField(value) {
+    // Defense-in-depth for LLM-facing task fields: server already redacts
+    // credential material, but worker messages / labels can still carry
+    // newlines / backticks that would otherwise reach agent context verbatim.
+    const scrubbed = stripUnsafeChars(scrubSecrets(value)).trim();
+    return scrubbed.length > LIFECYCLE_FAILURE_FIELD_MAX_LEN
+        ? `${scrubbed.slice(0, LIFECYCLE_FAILURE_FIELD_MAX_LEN)}…`
+        : scrubbed;
+}
+const DEFAULT_PROVIDER_LABEL = "App Database";
+/**
+ * APPS-5377: Clark historically assumed "Amazon RDS" because tool copy
+ * hard-coded it. Aurora Serverless still uses the RDS API and
+ * `*.rds.amazonaws.com` hostnames (including Multi-AZ cluster writers
+ * that share the `*.cluster-*` DNS pattern with Aurora), so hostname
+ * sniffing replaces one confident mislabel with another.
+ *
+ * Keep the generic `App Database` label unless the backend explicitly
+ * supplies `providerLabel` / `provider_label` on the lifecycle response
+ * or connectionMetadata.
+ */
+export function inferManagedDatabaseProviderLabel(connectionMetadata) {
+    // Prefer an explicit backend hint if present (future / passthrough).
+    const explicit = connectionMetadata?.providerLabel ?? connectionMetadata?.provider_label;
+    if (typeof explicit === "string" && explicit.trim()) {
+        return {
+            providerLabel: explicit.trim(),
+            source: "connectionMetadata",
+        };
+    }
+    return { providerLabel: DEFAULT_PROVIDER_LABEL, source: "default" };
+}
+function sanitizeProviderLabel(value) {
+    const scrubbed = sanitizeLifecycleFailureField(value);
+    return scrubbed.length > 0 ? scrubbed : DEFAULT_PROVIDER_LABEL;
+}
+function withProviderLabel(response) {
+    if (response.providerLabel) {
+        const providerLabel = sanitizeProviderLabel(response.providerLabel);
+        getLogger().debug({
+            bindingKey: response.bindingKey,
+            requestId: response.requestId,
+            providerLabel,
+            source: "server",
+        }, "[devDatabase] using server-provided providerLabel");
+        return providerLabel === response.providerLabel
+            ? response
+            : { ...response, providerLabel };
+    }
+    const { providerLabel: inferredLabel, source } = inferManagedDatabaseProviderLabel(response.connectionMetadata);
+    const providerLabel = sanitizeProviderLabel(inferredLabel);
+    getLogger().debug({
+        bindingKey: response.bindingKey,
+        requestId: response.requestId,
+        providerLabel,
+        source,
+    }, source === "connectionMetadata"
+        ? "[devDatabase] using providerLabel from connectionMetadata"
+        : "[devDatabase] using generic providerLabel (prefer server field when available)");
+    return {
+        ...response,
+        providerLabel,
+    };
+}
 function toToolError(error) {
     if (error instanceof DevDatabaseClientError) {
         return new Error(`${error.code}: ${error.message}`);
@@ -193,19 +270,6 @@ const LIFECYCLE_FAILURE_AGENT_GUIDANCE = {
         unsupported_provider_capability: "The agent does not support this database operation; update OPA lifecycle configuration, then retry.",
     },
 };
-/** Max length for code/message/requestId in agent-facing lifecycle failures.
- *  Matches `SAFE_INTERP_MAX_LEN` in build-install-packages.ts so a multi-KB
- *  provider error cannot crowd out the rest of the agent context. */
-const LIFECYCLE_FAILURE_FIELD_MAX_LEN = 100;
-function sanitizeLifecycleFailureField(value) {
-    // Defense-in-depth for LLM-facing task errors: server already redacts
-    // credential material, but worker messages can still carry newlines /
-    // backticks that would otherwise reach agent context verbatim.
-    const scrubbed = stripUnsafeChars(scrubSecrets(value)).trim();
-    return scrubbed.length > LIFECYCLE_FAILURE_FIELD_MAX_LEN
-        ? `${scrubbed.slice(0, LIFECYCLE_FAILURE_FIELD_MAX_LEN)}…`
-        : scrubbed;
-}
 function formatLifecycleTaskFailure(action, response, 
 // Durable id from the persisted task handle when progress omits it
 // (Scout / Bugbot: ProvisionHandle.requestId must be read, not only written).
@@ -255,6 +319,47 @@ fallbackRequestId) {
         userDefault;
     return { error, detail };
 }
+/**
+ * Keep only characters the chat mention parser accepts inside `@Name[id=…]`
+ * (letters, numbers, `_` `.` `-` `$`, and interior spaces). Scrub secrets /
+ * unsafe chars and cap length like sibling lifecycle fields so a long
+ * `logicalName` cannot inflate completed task results fed back to the model.
+ * Punctuation such as `()`, `/`, or apostrophes would otherwise prevent a
+ * match and leave the raw `[id=<uuid>]` visible in assistant text. Display
+ * name still comes from entity lookup by id when the tag resolves.
+ */
+export function mentionSafeTagName(name) {
+    const scrubbed = stripUnsafeChars(scrubSecrets(name)).trim();
+    const sanitized = scrubbed
+        .replace(/[^\p{L}\p{N}_.\-$ ]+/gu, "")
+        .replace(/\s+/g, " ")
+        .trim();
+    const capped = sanitized.length > LIFECYCLE_FAILURE_FIELD_MAX_LEN
+        ? sanitized.slice(0, LIFECYCLE_FAILURE_FIELD_MAX_LEN).trimEnd()
+        : sanitized;
+    return capped || "entity";
+}
+/**
+ * Attach `@logicalName[id=integrationId]` for user-facing chat stickers.
+ * Uses a parser-safe label derived from logicalName. Keeps integrationId
+ * available for codegen.
+ */
+function withEntityTag(response, fallbackLogicalName) {
+    if (response.entityTag) {
+        return response;
+    }
+    const name = response.logicalName ?? fallbackLogicalName;
+    if (!response.integrationId || !name) {
+        if (response.integrationId && !name) {
+            getLogger().warn("[devDatabase] cannot attach entityTag: response missing logicalName and no fallback provided; chat may only have bare integrationId");
+        }
+        return response;
+    }
+    return {
+        ...response,
+        entityTag: `@${mentionSafeTagName(name)}[id=${response.integrationId}]`,
+    };
+}
 /** A completed task hands its whole result to the LLM, so per-datatag error text
  *  needs the same scrubbing a top-level failure gets. Partial success is the
  *  common case here: the task completes while some datatags carry provider
@@ -276,10 +381,40 @@ function withSanitizedTargets(response) {
         })),
     };
 }
-function lifecycleStatusFor(response, fallbackRequestId) {
+const REGISTERING_CONNECTION_MESSAGE = "Database provisioned; registering the connection";
+/**
+ * When the server says runtime config is not ready yet, keep the task running
+ * so Clark does not treat a vacant `{}` projection as executable (ENG-5285).
+ * Older servers omit the fields — preserve prior complete-on-ready behavior,
+ * except the migrate-then-project case (ready + migration still pending).
+ */
+function awaitingRuntimeConfiguration(response) {
+    if (response.runtimeConfigurationReady !== false) {
+        return false;
+    }
+    if (typeof response.expectsRuntimeConfiguration === "boolean") {
+        return response.expectsRuntimeConfiguration;
+    }
+    // Compat for servers that only send runtimeConfigurationReady: projection
+    // was historically deferred until migrate, so pending migration may complete.
+    return response.migrationState !== "pending";
+}
+function enrichCompletedResponse(response, fallbackLogicalName) {
+    return withEntityTag(withProviderLabel(withSanitizedTargets(response)), fallbackLogicalName);
+}
+function lifecycleStatusFor(response, fallbackRequestId, fallbackLogicalName) {
     switch (response.lifecycleState) {
         case "ready":
-            return { state: "completed", result: withSanitizedTargets(response) };
+            if (awaitingRuntimeConfiguration(response)) {
+                return {
+                    state: "running",
+                    message: REGISTERING_CONNECTION_MESSAGE,
+                };
+            }
+            return {
+                state: "completed",
+                result: enrichCompletedResponse(response, fallbackLogicalName),
+            };
         case "failed": {
             const { error, detail } = formatLifecycleTaskFailure("dev database provisioning", response, fallbackRequestId);
             return { state: "failed", error, detail };
@@ -291,10 +426,19 @@ function lifecycleStatusFor(response, fallbackRequestId) {
             return { state: "running", message: response.lifecycleState };
     }
 }
-function migrationStatusFor(response, fallbackRequestId) {
+function migrationStatusFor(response, fallbackRequestId, fallbackLogicalName) {
     switch (response.migrationState) {
         case "migrated":
-            return { state: "completed", result: withSanitizedTargets(response) };
+            if (awaitingRuntimeConfiguration(response)) {
+                return {
+                    state: "running",
+                    message: REGISTERING_CONNECTION_MESSAGE,
+                };
+            }
+            return {
+                state: "completed",
+                result: enrichCompletedResponse(response, fallbackLogicalName),
+            };
         case "failed": {
             const { error, detail } = formatLifecycleTaskFailure("applying migrations", response, fallbackRequestId);
             return { state: "failed", error, detail };
@@ -309,6 +453,33 @@ function isPreconditionFailure(response) {
 }
 const DEFAULT_MIGRATION_TASK_LABEL = "the database schema update";
 const MAX_MIGRATION_FILENAMES_IN_TASK_LABEL = 3;
+/**
+ * Deterministic next step for Clark when the server blocks a destructive
+ * migration. This is deliberately kept out of the length-capped `error`
+ * field (see the precondition branch below): `error` is clamped to
+ * LIFECYCLE_FAILURE_FIELD_MAX_LEN, so a findings list would truncate the
+ * instruction and Clark would improvise (for example try to run the DROP as
+ * raw SQL, or tell the user to drop the object by hand). `detail` is not
+ * clamped, so the whole instruction reaches the model verbatim.
+ *
+ * Re-calling with `acknowledgeDestructive=true` is what raises the
+ * user-facing permission request; the approval button is the confirmation,
+ * so Clark must not seek a separate chat confirmation first, and must not try
+ * to bypass the block.
+ */
+const DESTRUCTIVE_MIGRATION_ACK_AGENT_GUIDANCE = "This apply includes destructive schema changes and needs the user's " +
+    "permission. Re-call startApplyDevDatabaseMigrations with " +
+    "acknowledgeDestructive=true; that raises a permission request the user " +
+    "approves or denies before anything is dropped. Do not run the SQL another " +
+    "way and do not ask the user to drop objects manually.";
+const SINGLE_APP_DATABASE_PRECONDITION_AGENT_GUIDANCE = "This application already has an App Database, and only one App Database " +
+    "per application is supported. Explain that limit to the user. Do not add " +
+    "tables, migrations, or schema to the existing database as a substitute for " +
+    "creating another database. Only modify the existing database if the user " +
+    "explicitly asks to.";
+function isSingleAppDatabasePreconditionFailure(response) {
+    return /already has (?:a )?(?:dev |app )?database|only one (?:dev |app )?database per application/i.test(response.errorMessage ?? "");
+}
 function migrationTaskLabel(response) {
     if (response.migrationState === "failed") {
         return DEFAULT_MIGRATION_TASK_LABEL;
@@ -322,20 +493,37 @@ function migrationTaskLabel(response) {
     if (migrations.length === 0) {
         return "No database migration files to apply";
     }
-    const filenames = migrations
+    // The dispatch always carries every SQL file in the migration directory,
+    // because the worker replays them against its own ledger. Name only the ones
+    // this run adds, so a row for a one-file change does not read like the whole
+    // schema is being rebuilt. Servers that don't report the added files leave us
+    // no way to tell them apart, so fall back to naming the whole set.
+    const applying = response.newMigrationFilenames ??
+        migrations.map(({ filename }) => filename);
+    // An empty added-set is an estimate, not the worker's ledger, and this label
+    // is set once and never revisited. Naming nothing is honest; asserting the
+    // schema is current would stay on screen even if the run then failed.
+    if (applying.length === 0) {
+        return DEFAULT_MIGRATION_TASK_LABEL;
+    }
+    const filenames = applying
         .slice(0, MAX_MIGRATION_FILENAMES_IN_TASK_LABEL)
-        .map(({ filename }) => sanitizeLifecycleFailureField(filename));
+        .map((filename) => sanitizeLifecycleFailureField(filename));
     if (filenames.some((filename) => filename.length === 0)) {
         return DEFAULT_MIGRATION_TASK_LABEL;
     }
-    const remaining = Math.max(0, migrations.length - MAX_MIGRATION_FILENAMES_IN_TASK_LABEL);
+    const remaining = Math.max(0, applying.length - MAX_MIGRATION_FILENAMES_IN_TASK_LABEL);
     return `Database migrations: ${filenames.join(", ")}${remaining > 0 ? ` (+${remaining} more)` : ""}`;
 }
 function updateProvisionHandleFromResponse(handle, response) {
     handle.engine = response.engine;
     handle.integrationId = response.integrationId;
     handle.lifecycleState = response.lifecycleState;
-    handle.logicalName = response.logicalName;
+    // Poll envelopes may omit logicalName; keep the name captured at task /
+    // watch start so entityTag can still be attached on completion.
+    if (response.logicalName) {
+        handle.logicalName = response.logicalName;
+    }
     if (response.requestId) {
         handle.requestId = response.requestId;
     }
@@ -367,7 +555,7 @@ function fanOutTargetsFromResponse(response) {
         },
     ];
 }
-async function spawnSiblingWatchTasks(deps, { logicalName, primaryBindingKey, targets, toolOpts, watchKind = "provision", }) {
+async function spawnSiblingWatchTasks(deps, { logicalName, primaryBindingKey, signal, targets, toolOpts, watchKind = "provision", }) {
     const taskStore = deps.getTaskStore?.();
     if (!taskStore) {
         return [];
@@ -375,7 +563,19 @@ async function spawnSiblingWatchTasks(deps, { logicalName, primaryBindingKey, ta
     const startedTaskIds = [];
     const ownerUserId = deps.getCurrentOwnerId?.();
     const siblings = targets.filter((target) => target.bindingKey !== primaryBindingKey);
+    // Spawning is sequential and each start is awaited, so a cancel can land
+    // between siblings or while one is in flight. Stop at the next boundary and
+    // retire the watches this kickoff already created: their parent is gone, so
+    // nobody would consume them and they would keep polling on their own.
+    const stopIfCancelled = async () => {
+        if (signal?.aborted !== true) {
+            return;
+        }
+        await Promise.allSettled(startedTaskIds.map((taskId) => taskStore.cancel(taskId)));
+        signal.throwIfAborted();
+    };
     for (const target of siblings) {
+        await stopIfCancelled();
         try {
             const rawInitialError = !target.ok
                 ? (target.errorMessage ??
@@ -406,6 +606,7 @@ async function spawnSiblingWatchTasks(deps, { logicalName, primaryBindingKey, ta
             // unobserved binding may still be provisioning.
             throw error;
         }
+        await stopIfCancelled();
     }
     return startedTaskIds;
 }
@@ -486,19 +687,21 @@ export function createDevDatabaseTaskTypes(deps) {
                 throw toToolError(error);
             }
             updateProvisionHandleFromResponse(handle, response);
+            const fallbackLogicalName = handle.logicalName ?? handle.requirement.logicalName;
             if (handle.watchKind === "migration") {
                 if (TERMINAL_LIFECYCLE_STATES.has(response.lifecycleState) &&
                     response.lifecycleState !== "ready") {
-                    return lifecycleStatusFor(response, handle.requestId);
+                    return lifecycleStatusFor(response, handle.requestId, fallbackLogicalName);
                 }
-                return migrationStatusFor(response, handle.requestId);
+                return migrationStatusFor(response, handle.requestId, fallbackLogicalName);
             }
-            return lifecycleStatusFor(response, handle.requestId);
+            return lifecycleStatusFor(response, handle.requestId, fallbackLogicalName);
         },
     };
     const provisionDevDatabaseTaskType = {
         ...provisionDevDatabaseTaskMetadata,
-        start: async (input, toolOpts) => {
+        pendingLabel: (input) => provisionLabel(input.requirement.logicalName),
+        start: async (input, toolOpts, signal) => {
             let response;
             try {
                 // Client never sends a profile — the server resolves editor
@@ -512,6 +715,7 @@ export function createDevDatabaseTaskTypes(deps) {
             catch (error) {
                 throw toToolError(error);
             }
+            signal?.throwIfAborted();
             // The application already has a database (typically under a
             // different name — only one dev database per application is
             // supported), or another precondition blocks provisioning. Surface
@@ -520,6 +724,9 @@ export function createDevDatabaseTaskTypes(deps) {
             // opaque "did not include lifecycle state" error. Mirrors the
             // applyMigrations precondition branch below.
             if (isPreconditionFailure(response)) {
+                const detail = isSingleAppDatabasePreconditionFailure(response)
+                    ? SINGLE_APP_DATABASE_PRECONDITION_AGENT_GUIDANCE
+                    : undefined;
                 return {
                     externalHandle: {
                         bindingKey: "precondition-failure",
@@ -530,6 +737,7 @@ export function createDevDatabaseTaskTypes(deps) {
                         error: sanitizeLifecycleFailureField(response.errorMessage ??
                             response.errorCode ??
                             "createDevDb precondition failed"),
+                        ...(detail ? { detail } : {}),
                     },
                     label: provisionLabel(input.requirement.logicalName),
                 };
@@ -552,6 +760,7 @@ export function createDevDatabaseTaskTypes(deps) {
                 const siblingTaskIds = await spawnSiblingWatchTasks(deps, {
                     logicalName: input.requirement.logicalName,
                     primaryBindingKey: response.bindingKey,
+                    signal,
                     targets,
                     toolOpts,
                 });
@@ -564,7 +773,7 @@ export function createDevDatabaseTaskTypes(deps) {
             if (TERMINAL_LIFECYCLE_STATES.has(response.lifecycleState)) {
                 return {
                     externalHandle: handle,
-                    initialStatus: heldForSiblings(deps, lifecycleStatusFor(response), handle.siblingTaskIds),
+                    initialStatus: heldForSiblings(deps, lifecycleStatusFor(response, undefined, input.requirement.logicalName), handle.siblingTaskIds),
                     label,
                 };
             }
@@ -590,18 +799,23 @@ export function createDevDatabaseTaskTypes(deps) {
                 throw toToolError(error);
             }
             updateProvisionHandleFromResponse(handle, response);
-            return heldForSiblings(deps, lifecycleStatusFor(response, handle.requestId), handle.siblingTaskIds);
+            return heldForSiblings(deps, lifecycleStatusFor(response, handle.requestId, handle.logicalName ?? handle.requirement.logicalName), handle.siblingTaskIds);
         },
     };
     const applyDevDatabaseMigrationsTaskType = {
         ...applyDevDatabaseMigrationsTaskMetadata,
-        start: async (_input, toolOpts) => {
+        // Kickoff uploads the working directory and then asks the server what
+        // needs applying, so there is nothing to name yet. `start` swaps in the
+        // filenames once it knows them.
+        pendingLabel: () => DEFAULT_MIGRATION_TASK_LABEL,
+        start: async (input, toolOpts, signal) => {
             try {
                 await deps.ensureFilesSynced?.();
             }
             catch (error) {
                 throw toToolError(error);
             }
+            signal?.throwIfAborted();
             let response;
             try {
                 // Never pass bindingKey — server fans out migrate_schema across
@@ -610,21 +824,43 @@ export function createDevDatabaseTaskTypes(deps) {
                 // projected integration configs (migrations never ran there).
                 response = await deps.getClient().applyMigrations({
                     applicationId: deps.applicationId,
+                    ...(input.acknowledgeDestructive === true
+                        ? { acknowledgeDestructive: true }
+                        : {}),
                 });
             }
             catch (error) {
                 throw toToolError(error);
             }
+            signal?.throwIfAborted();
             if (isPreconditionFailure(response)) {
+                const baseError = sanitizeLifecycleFailureField(response.errorMessage ??
+                    response.errorCode ??
+                    "applyMigrations precondition failed");
+                const isDestructiveAck = response.errorCode === "DESTRUCTIVE_MIGRATION_ACK_REQUIRED";
+                const findingsSuffix = isDestructiveAck &&
+                    Array.isArray(response.findings) &&
+                    response.findings.length > 0
+                    ? sanitizeLifecycleFailureField(`Findings: ${response.findings
+                        .map((finding) => `${sanitizeLifecycleFailureField(finding.fileName)} (${sanitizeLifecycleFailureField(finding.kind)})`)
+                        .join("; ")}`)
+                    : "";
+                const error = sanitizeLifecycleFailureField(findingsSuffix ? `${baseError} ${findingsSuffix}` : baseError);
                 return {
                     externalHandle: {
                         requestId: "precondition-failure",
                     },
                     initialStatus: {
                         state: "failed",
-                        error: sanitizeLifecycleFailureField(response.errorMessage ??
-                            response.errorCode ??
-                            "applyMigrations precondition failed"),
+                        error,
+                        // The re-call instruction goes in `detail`, not `error`: `error`
+                        // is clamped, so a findings list would truncate the actionable
+                        // step. `detail` reaches Clark verbatim, so it reliably re-calls
+                        // with acknowledgeDestructive=true and the user gets a permission
+                        // request instead of Clark improvising a bypass.
+                        ...(isDestructiveAck
+                            ? { detail: DESTRUCTIVE_MIGRATION_ACK_AGENT_GUIDANCE }
+                            : {}),
                     },
                     label: DEFAULT_MIGRATION_TASK_LABEL,
                 };
@@ -632,6 +868,7 @@ export function createDevDatabaseTaskTypes(deps) {
             const label = migrationTaskLabel(response);
             const handle = {
                 bindingKey: response.bindingKey,
+                logicalName: response.logicalName,
                 requestId: response.requestId,
             };
             const targets = fanOutTargetsFromResponse(response);
@@ -640,6 +877,7 @@ export function createDevDatabaseTaskTypes(deps) {
                 const siblingTaskIds = await spawnSiblingWatchTasks(deps, {
                     logicalName: response.logicalName ?? "database",
                     primaryBindingKey: response.bindingKey,
+                    signal,
                     targets,
                     toolOpts,
                     watchKind: "migration",
@@ -648,18 +886,14 @@ export function createDevDatabaseTaskTypes(deps) {
                     handle.siblingTaskIds = siblingTaskIds;
                 }
             }
-            // Migrations sometimes finish synchronously (no SQL to apply).
-            if (response.migrationState === "migrated") {
-                return {
-                    externalHandle: handle,
-                    initialStatus: heldForSiblings(deps, { state: "completed", result: withSanitizedTargets(response) }, handle.siblingTaskIds),
-                    label,
-                };
-            }
-            if (response.migrationState === "failed") {
+            // Migrations sometimes finish synchronously (no SQL to apply). Still
+            // route through migrationStatusFor so a vacant projection keeps the
+            // task running until runtimeConfigurationReady (ENG-5285).
+            if (response.migrationState === "migrated" ||
+                response.migrationState === "failed") {
                 return {
                     externalHandle: handle,
-                    initialStatus: migrationStatusFor(response, handle.requestId),
+                    initialStatus: heldForSiblings(deps, migrationStatusFor(response, handle.requestId, handle.logicalName), handle.siblingTaskIds),
                     label,
                 };
             }
@@ -684,14 +918,17 @@ export function createDevDatabaseTaskTypes(deps) {
             catch (error) {
                 throw toToolError(error);
             }
+            if (response.logicalName) {
+                handle.logicalName = response.logicalName;
+            }
             // If the underlying lifecycle went terminal (failed/cancelled)
             // while migrations are still pending, surface the lifecycle
             // failure instead of spinning forever on migrationState.
             if (TERMINAL_LIFECYCLE_STATES.has(response.lifecycleState) &&
                 response.lifecycleState !== "ready") {
-                return lifecycleStatusFor(response, handle.requestId);
+                return lifecycleStatusFor(response, handle.requestId, handle.logicalName);
             }
-            return heldForSiblings(deps, migrationStatusFor(response, handle.requestId), handle.siblingTaskIds);
+            return heldForSiblings(deps, migrationStatusFor(response, handle.requestId, handle.logicalName), handle.siblingTaskIds);
         },
     };
     return {