aui-agent-builder 0.3.83 → 0.3.86

package/dist/commands/push.js

@@ -10,6 +10,7 @@ import { AUIClient, applyScopeLevel } from "../api-client/index.js";
 import { findAuiFiles, parseAuiFile } from "../utils/index.js";
 import { validate } from "./validate.js";
 import { getTracer, SpanStatusCode, setUserContext } from "../telemetry.js";
+import { trace } from "@opentelemetry/api";
 import { getItemLevelDiff } from "../utils/git.js";
 import { AuthenticationError, CLIError, ConfigError, ValidationError } from "../errors/index.js";
 import { StatusLine, Spinner, ErrorDisplay, Hint, } from "../ui/components/index.js";
@@ -23,20 +24,54 @@ function log(node) {
 }
 function startSpinner(label) {
     const inst = render(_jsx(Spinner, { label: label }));
+    let unmounted = false;
+    const safeUnmount = () => {
+        if (unmounted)
+            return;
+        unmounted = true;
+        inst.unmount();
+    };
     return {
         succeed(msg) {
-            inst.unmount();
+            safeUnmount();
             log(_jsx(StatusLine, { kind: "success", label: msg }));
         },
         fail(msg) {
-            inst.unmount();
+            safeUnmount();
             log(_jsx(StatusLine, { kind: "error", label: msg }));
         },
         stop() {
-            inst.unmount();
+            safeUnmount();
+        },
+        /**
+         * Internal: unconditionally unmount, no log line. Used by `withSpinner`
+         * to guarantee the spinner stops even when the wrapped body throws an
+         * exception that escapes the surrounding try/catch (which would
+         * otherwise leave a phantom spinner spinning forever).
+         */
+        _forceUnmount() {
+            safeUnmount();
         },
     };
 }
+/**
+ * Wrap a sync- or async-returning callback so the spinner ALWAYS unmounts,
+ * even on uncaught exceptions. The callback can call `.succeed()` / `.fail()`
+ * itself to render a final status line; otherwise the spinner just stops.
+ *
+ * This pattern eliminates the "phantom spinner" foot-gun where an exception
+ * thrown between `startSpinner(...)` and `.succeed/.fail` leaves the Ink
+ * render mounted forever — blocking the chat UI's "Still thinking…" state.
+ */
+async function withSpinner(label, fn) {
+    const spinner = startSpinner(label);
+    try {
+        return await fn(spinner);
+    }
+    finally {
+        spinner._forceUnmount();
+    }
+}
 /**
  * Push local agent configuration to the backend
  */
@@ -90,13 +125,47 @@ async function _push(pushSpan, agentCode, options = {}) {
             log(_jsx(StatusLine, { kind: "info", label: "Validating configuration..." }));
         else
             stderrLog("Validating configuration...");
-        const valid = await validate(projectRoot, { verbose: false });
+        // Wrap the validate call in its own span so a "stuck at validate"
+        // hang shows up clearly in Logfire as `aui.push.preflight.validate`
+        // with status = unset (still running) — instead of the parent
+        // `aui.push` span just sitting there with no clue why.
+        const validateTracer = getTracer();
+        const valid = await validateTracer.startActiveSpan("aui.push.preflight.validate", async (vSpan) => {
+            vSpan.setAttribute("push.preflight.step", "validate");
+            vSpan.setAttribute("push.preflight.skipValidation", false);
+            vSpan.setAttribute("push.preflight.force", options.force === true);
+            try {
+                const ok = await validate(projectRoot, { verbose: false });
+                vSpan.setAttribute("push.preflight.validate.ok", ok);
+                vSpan.setStatus({ code: SpanStatusCode.OK });
+                return ok;
+            }
+            catch (err) {
+                // validate() shouldn't throw under normal conditions, but if a
+                // schema fetch or git call inside it does, surface it here so
+                // we don't lose the error to the parent span's generic handler.
+                const msg = err instanceof Error ? err.message : String(err);
+                vSpan.setStatus({ code: SpanStatusCode.ERROR, message: msg });
+                vSpan.recordException(err instanceof Error ? err : new Error(msg));
+                throw err;
+            }
+            finally {
+                vSpan.end();
+            }
+        });
         if (!valid && !options.force) {
             pushSpan.setAttribute("push.exit_reason", "validation_failed");
+            pushSpan.addEvent("preflight.validation_rejected_push");
             throw new ValidationError("Push aborted due to validation errors.", {
                 suggestion: "Fix the errors above, or use --force to push anyway.",
             });
         }
+        if (!valid && options.force) {
+            pushSpan.addEvent("preflight.validation_failed_but_forced");
+        }
+    }
+    else {
+        pushSpan.addEvent("preflight.validation_skipped");
     }
     if (!json)
         log(_jsx(StatusLine, { kind: "info", label: "Pushing agent changes..." }));
@@ -237,208 +306,15 @@ async function _push(pushSpan, agentCode, options = {}) {
             log(_jsx(Box, { paddingX: 1, children: _jsx(StatusLine, { kind: "muted", label: "Dry run \u2014 no changes pushed." }) }));
             return;
         }
-        // ─── Push integration upserts before KB ───
-        // KB uploads need the integration (and its knowledge base) to exist first.
-        // Only create/patch/replace integrations here — not deletes: entities/workflows
-        // may still reference an integration until we push entity changes below.
-        let integrationUpsertsAlreadyPushed = false;
-        /** When set, reused in the main Agent Settings push — avoids resolving the draft twice. */
-        let resolvedPushDraftCache = null;
-        let cachedPushAgentManagementId;
-        if (diff && diff.hasChanges) {
-            const intSession = await getValidSession();
-            if (intSession) {
-                const intAsp = await resolveAgentSettingsParams(config, projectConfig, intSession, projectRoot);
-                if (intAsp) {
-                    const intClient = new AUIClient({
-                        baseUrl: config.apiUrl,
-                        authToken: config.authToken,
-                        accountId: config.accountId,
-                        organizationId: config.organizationId,
-                        environment: config.environment,
-                    });
-                    const intPushLogDir = path.join(projectRoot, ".aui", "push-logs");
-                    fs.mkdirSync(intPushLogDir, { recursive: true });
-                    intClient.setPushLogDir(intPushLogDir);
-                    if (options.apiKey) {
-                        saveAgentSettingsApiKey(options.apiKey);
-                        intClient.setAgentSettingsApiKey(options.apiKey);
-                    }
-                    const intSavedKey = loadAgentSettingsApiKey();
-                    if (intSavedKey && !options.apiKey) {
-                        intClient.setAgentSettingsApiKey(intSavedKey);
-                    }
-                    const intPushTasks = buildPushTasks(diff, fileData, projectRoot, getFileDiff);
-                    const integrationUpsertTasksEarly = intPushTasks.filter(isIntegrationUpsertTask);
-                    if (integrationUpsertTasksEarly.length > 0) {
-                        // Same as main push: integrations must carry agent_version_id on the body.
-                        // Without this, pre-KB upserts omit version_id while parameters / scope_entities
-                        // / rules use agentSettingsParams after resolveVersionDraft (and main skips upserts).
-                        if (projectConfig.version_id || options.versionId) {
-                            resolvedPushDraftCache = await resolveVersionDraft(config, projectConfig, intSession, options.versionId);
-                            intAsp.version_id = resolvedPushDraftCache.versionId;
-                            intAsp.agent_id = resolvedPushDraftCache.agentId;
-                            cachedPushAgentManagementId = resolvedPushDraftCache.agentId;
-                        }
-                        else {
-                            if (!cachedPushAgentManagementId) {
-                                cachedPushAgentManagementId = await resolvePushAgentManagementId(config, projectConfig, intSession, projectRoot);
-                            }
-                            intAsp.agent_id = cachedPushAgentManagementId;
-                        }
-                        log(_jsx(Box, { paddingX: 1, children: _jsxs(Text, { color: colors.info, children: [icons.bullet, " Pushing integrations (before KB upload)..."] }) }));
-                        for (const task of integrationUpsertTasksEarly) {
-                            const taskResult = {
-                                label: task.label,
-                                status: "success",
-                            };
-                            try {
-                                await executePushTask(intClient, intAsp, task);
-                            }
-                            catch (err) {
-                                const errMsg = err instanceof Error ? err.message : String(err);
-                                taskResult.status = "failed";
-                                taskResult.error = errMsg;
-                            }
-                            log(_jsx(Box, { paddingX: 2, children: _jsx(PushTaskLine, { result: taskResult }) }));
-                        }
-                        integrationUpsertsAlreadyPushed = true;
-                    }
-                }
-            }
-        }
-        // ─── Knowledge Hubs Push (full files) ───
-        const { getKnowledgeHubChanges } = await import("../utils/git.js");
-        const kbChanges = getKnowledgeHubChanges(projectRoot);
-        if (kbChanges.length > 0) {
-            const kbConfig = getConfig();
-            const kbSession = await getValidSession();
-            const kbNetworkId = projectConfig.agent_id || kbSession?.network_id;
-            if (kbNetworkId && kbConfig.authToken) {
-                const { KBViewClient } = await import("../api-client/kb-view-client.js");
-                const { buildScope, readKbFolder } = await import("../services/kb-view.service.js");
-                const { loadAgentSettingsApiKey: loadAsKey } = await import("../config/index.js");
-                const kbViewClient = new KBViewClient({
-                    authToken: kbConfig.authToken,
-                    apiKey: loadAsKey() || undefined,
-                    organizationId: kbConfig.organizationId || "",
-                    environment: kbConfig.environment || "staging",
-                });
-                const kbLogDir = path.join(projectRoot, ".aui", "push-logs");
-                fs.mkdirSync(kbLogDir, { recursive: true });
-                kbViewClient.setPushLogDir(kbLogDir);
-                const scope = buildScope({
-                    networkId: kbNetworkId,
-                    organizationId: projectConfig.organization_id || kbConfig.organizationId || "",
-                    accountId: projectConfig.account_id || kbConfig.accountId || "",
-                });
-                const userId = kbSession?.user_id || "cli";
-                // Collect all changed KB directories (skip root-level files)
-                const changedKBDirs = new Set();
-                for (const change of kbChanges) {
-                    if (change.kbDirName) {
-                        changedKBDirs.add(change.kbDirName);
-                    }
-                }
-                // Split into existing (will upload) and deleted (will delete from server)
-                const existingKBDirs = [...changedKBDirs].filter((d) => fs.existsSync(path.join(projectRoot, "knowledge-hubs", d)));
-                const deletedKBDirs = [...changedKBDirs].filter((d) => !fs.existsSync(path.join(projectRoot, "knowledge-hubs", d)));
-                // Delete KBs that were removed locally
-                let kbDeleteSucceeded = true;
-                if (deletedKBDirs.length > 0) {
-                    const { getBaselineFileContent } = await import("../utils/git.js");
-                    const deleteSpinner = startSpinner(`Deleting ${deletedKBDirs.length} knowledge base(s) from server...`);
-                    try {
-                        for (const kbDirName of deletedKBDirs) {
-                            const baselineKb = getBaselineFileContent(projectRoot, `knowledge-hubs/${kbDirName}/kb.json`);
-                            const kbName = baselineKb?.name || kbDirName;
-                            const kbId = baselineKb?.knowledge_base_id;
-                            if (!kbId) {
-                                log(_jsx(Box, { paddingX: 1, children: _jsx(StatusLine, { kind: "warning", label: `Cannot delete "${kbName}" — no knowledge_base_id stored. Push the KB first, then delete.` }) }));
-                                continue;
-                            }
-                            await kbViewClient.deleteKnowledgeBase(kbId, scope, kbName);
-                            log(_jsx(Box, { paddingX: 1, children: _jsx(StatusLine, { kind: "success", label: `Deleted: ${kbName}` }) }));
-                        }
-                        deleteSpinner.succeed(`${deletedKBDirs.length} knowledge base(s) deleted`);
-                    }
-                    catch (error) {
-                        kbDeleteSucceeded = false;
-                        deleteSpinner.fail("Knowledge base deletion failed");
-                        log(_jsx(ErrorDisplay, { error: error }));
-                    }
-                }
-                // Upload full files for each changed KB
-                let kbUploadSucceeded = false;
-                if (existingKBDirs.length > 0) {
-                    const kbSpinner = startSpinner(`Pushing ${existingKBDirs.length} knowledge base(s)...`);
-                    try {
-                        for (const kbDirName of existingKBDirs) {
-                            const kbDir = path.join(projectRoot, "knowledge-hubs", kbDirName);
-                            const kbData = readKbFolder(kbDir);
-                            if (!kbData)
-                                continue;
-                            const SUPPORTED_EXTENSIONS = new Set([".pdf", ".md", ".txt", ".json"]);
-                            const supportedFiles = kbData.binaryFiles.filter((f) => SUPPORTED_EXTENSIONS.has(path.extname(f).toLowerCase()));
-                            const skippedFiles = kbData.binaryFiles.filter((f) => !SUPPORTED_EXTENSIONS.has(path.extname(f).toLowerCase()));
-                            for (const skipped of skippedFiles) {
-                                log(_jsx(Box, { paddingX: 1, children: _jsx(StatusLine, { kind: "warning", label: `Skipped unsupported file: ${path.basename(skipped)} (only .pdf, .md, .txt, .json)` }) }));
-                            }
-                            if (supportedFiles.length > 0) {
-                                const importResult = await kbViewClient.importFiles({
-                                    files: supportedFiles,
-                                    scope,
-                                    created_by: userId,
-                                    knowledge_base_name: kbData.name,
-                                    knowledge_base_description: kbData.description,
-                                });
-                                if (importResult.knowledge_base_id) {
-                                    const kbJsonPath = path.join(kbDir, "kb.json");
-                                    try {
-                                        const raw = JSON.parse(fs.readFileSync(kbJsonPath, "utf-8"));
-                                        raw.knowledge_base_id = importResult.knowledge_base_id;
-                                        fs.writeFileSync(kbJsonPath, JSON.stringify(raw, null, 2) + "\n");
-                                    }
-                                    catch { /* kb.json write failed, non-fatal */ }
-                                }
-                            }
-                        }
-                        kbSpinner.succeed(`Knowledge base(s) pushed`);
-                        kbUploadSucceeded = true;
-                    }
-                    catch (error) {
-                        kbSpinner.fail("Knowledge base push failed");
-                        log(_jsx(ErrorDisplay, { error: error }));
-                    }
-                }
-                else {
-                    kbUploadSucceeded = true;
-                }
-                const kbPushSucceeded = kbUploadSucceeded && kbDeleteSucceeded;
-                // Commit KB changes to baseline only if push succeeded
-                if (kbPushSucceeded) {
-                    const kbFilesToAdd = kbChanges
-                        .filter((c) => c.status !== "deleted")
-                        .map((c) => c.file);
-                    const kbFilesToDelete = kbChanges
-                        .filter((c) => c.status === "deleted")
-                        .map((c) => c.file);
-                    if (kbFilesToAdd.length > 0 || kbFilesToDelete.length > 0) {
-                        const { commitBaselineFiles: commitKBFiles, removeBaselineFiles } = await import("../utils/git.js");
-                        if (kbFilesToDelete.length > 0) {
-                            removeBaselineFiles(projectRoot, kbFilesToDelete);
-                        }
-                        if (kbFilesToAdd.length > 0) {
-                            commitKBFiles(projectRoot, kbFilesToAdd, "pushed knowledge hub changes");
-                        }
-                        else {
-                            commitKBFiles(projectRoot, [], "removed knowledge hub files");
-                        }
-                    }
-                }
-            }
-        }
         // ─── Agent Config Push ───
+        //
+        // Knowledge Bases used to be pushed here (BEFORE entity writes) with a
+        // special pre-step that pushed integrations even earlier so KB uploads
+        // would find their integration. That ordering caused two production
+        // bugs: integrations were PATCHed before the parameters they reference
+        // existed (CTS-12425), and tools were pushed in parallel with their
+        // dependencies (CTS-12426). The KB push has been moved into the unified
+        // dependency-ordered flow below — see `pushKnowledgeHubs` invocation.
         if (!diff || !diff.hasChanges) {
             pushSpan.setAttribute("push.exit_reason", "no_agent_config_changes");
             log(_jsx(Box, { paddingX: 1, children: _jsx(StatusLine, { kind: "success", label: "No agent config changes to push." }) }));
@@ -477,21 +353,48 @@ async function _push(pushSpan, agentCode, options = {}) {
         // If the project has version_id in .auirc or --version-id is passed,
         // we validate it's a draft. If no version context exists, we auto-detect
         // available drafts. Push is rejected if no draft is found.
+        //
+        // Wrapped in an `aui.push.preflight.resolve-version` span so a hang on
+        // listAgents / listVersions / getVersion shows up clearly in Logfire
+        // instead of being lumped under the parent push span. This is the
+        // step that hits agent-management with up to 3 sequential calls.
         let prePushDraft = null;
         if (projectConfig.version_id || options.versionId) {
-            prePushDraft =
-                resolvedPushDraftCache ??
-                    (await resolveVersionDraft(config, projectConfig, session, options.versionId));
+            const resolveTracer = getTracer();
+            prePushDraft = await resolveTracer.startActiveSpan("aui.push.preflight.resolve-version", async (rSpan) => {
+                rSpan.setAttribute("push.preflight.step", "resolve-version");
+                rSpan.setAttribute("push.preflight.has_explicit_version_id", !!options.versionId);
+                rSpan.setAttribute("push.preflight.has_auirc_version_id", !!projectConfig.version_id);
+                if (projectConfig.agent_id) {
+                    rSpan.setAttribute("push.preflight.network_id", projectConfig.agent_id);
+                }
+                try {
+                    const draft = await resolveVersionDraft(config, projectConfig, session, options.versionId);
+                    rSpan.setAttribute("push.preflight.resolved_version_id", draft.versionId);
+                    rSpan.setAttribute("push.preflight.resolved_version_label", draft.label);
+                    rSpan.setAttribute("push.preflight.resolved_agent_id", draft.agentId);
+                    rSpan.setStatus({ code: SpanStatusCode.OK });
+                    return draft;
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    rSpan.setStatus({ code: SpanStatusCode.ERROR, message: msg });
+                    rSpan.recordException(err instanceof Error ? err : new Error(msg));
+                    throw err;
+                }
+                finally {
+                    rSpan.end();
+                }
+            });
             agentSettingsParams.version_id = prePushDraft.versionId;
-            agentSettingsParams.agent_id = prePushDraft.agentId;
-            cachedPushAgentManagementId = prePushDraft.agentId;
+            pushSpan.setAttribute("push.version_id", prePushDraft.versionId);
+            pushSpan.setAttribute("push.version_label", prePushDraft.label);
             log(_jsx(StatusLine, { kind: "info", label: `Pushing into draft version: ${prePushDraft.label}` }));
         }
         else {
-            if (!cachedPushAgentManagementId) {
-                cachedPushAgentManagementId = await resolvePushAgentManagementId(config, projectConfig, session, projectRoot);
-            }
-            agentSettingsParams.agent_id = cachedPushAgentManagementId;
+            pushSpan.addEvent("preflight.no_draft_version_required", {
+                reason: "legacy push (no version_id in .auirc or --version-id flag)",
+            });
         }
         const pushTasks = buildPushTasks(diff, fileData, projectRoot, getFileDiff);
         pushSpan.setAttribute("push.task_count", pushTasks.length);
@@ -526,82 +429,55 @@ async function _push(pushSpan, agentCode, options = {}) {
         };
         const agentCodeStr = projectConfig.agent_code || projectConfig.agent_id || "unknown";
         const agentIdStr = projectConfig.agent_id || "unknown";
-        const pushStep = async (tasks, label, parallel) => {
+        /**
+         * Run one push step (a group of related tasks for one entity-type)
+         * STRICTLY SEQUENTIALLY. There is intentionally no `parallel` flag — the
+         * agent-settings backend has no optimistic locking and concurrent writes
+         * to the same agent silently merge / drop unresolvable references / re-
+         * sequence array items (see file header doc + CTS-12340 / -12425 / -12426
+         * for prior incidents). If you think you need to parallelize, you don't.
+         */
+        const pushStep = async (tasks, label) => {
             if (tasks.length === 0)
                 return true;
             log(_jsx(Box, { paddingX: 1, children: _jsxs(Text, { color: colors.info, children: [icons.bullet, " ", label, "..."] }) }));
             const stepFailed = [];
             try {
-                if (parallel) {
-                    const results = await Promise.allSettled(tasks.map((t) => executePushTask(client, agentSettingsParams, t)));
-                    for (let i = 0; i < results.length; i++) {
-                        const taskResult = {
-                            label: tasks[i].label,
-                            status: "success",
-                        };
-                        if (results[i].status === "fulfilled") {
-                            succeeded++;
-                            if (tasks[i].file)
-                                succeededFiles.push(tasks[i].file);
-                        }
-                        else {
-                            const err = results[i].reason;
-                            if (isAuthError(err)) {
-                                authFailed = true;
-                                authFailedTasks.push(tasks[i]);
-                                taskResult.status = "auth-failed";
-                            }
-                            else {
-                                failed++;
-                                const errMsg = err instanceof Error ? err.message : String(err);
-                                const failure = {
-                                    label: tasks[i].label,
-                                    file: tasks[i].file,
-                                    error: errMsg,
-                                };
-                                pushFailures.push(failure);
-                                stepFailed.push(failure);
-                                taskResult.status = "failed";
-                                taskResult.error = errMsg;
-                            }
+                for (const task of tasks) {
+                    const taskResult = {
+                        label: task.label,
+                        status: "success",
+                    };
+                    try {
+                        const result = await executePushTask(client, agentSettingsParams, task);
+                        succeeded++;
+                        if (task.file)
+                            succeededFiles.push(task.file);
+                        if (isAlreadyAbsentResult(result)) {
+                            taskResult.label = `${task.label} (already absent)`;
                         }
-                        log(_jsx(Box, { paddingX: 2, children: _jsx(PushTaskLine, { result: taskResult }) }));
                     }
-                }
-                else {
-                    for (const task of tasks) {
-                        const taskResult = {
-                            label: task.label,
-                            status: "success",
-                        };
-                        try {
-                            await executePushTask(client, agentSettingsParams, task);
-                            succeeded++;
-                            if (task.file)
-                                succeededFiles.push(task.file);
+                    catch (err) {
+                        if (isAuthError(err)) {
+                            authFailed = true;
+                            authFailedTasks.push(task);
+                            taskResult.status = "auth-failed";
                         }
-                        catch (err) {
-                            if (isAuthError(err)) {
-                                authFailed = true;
-                                authFailedTasks.push(task);
-                                taskResult.status = "auth-failed";
-                            }
-                            else {
-                                failed++;
-                                const errMsg = err instanceof Error ? err.message : String(err);
-                                const failure = {
-                                    label: task.label,
-                                    file: task.file,
-                                    error: errMsg,
-                                };
-                                pushFailures.push(failure);
-                                stepFailed.push(failure);
-                                taskResult.status = "failed";
-                                taskResult.error = errMsg;
-                            }
+                        else {
+                            failed++;
+                            const errMsg = err instanceof Error ? err.message : String(err);
+                            const failure = {
+                                label: task.label,
+                                file: task.file,
+                                error: errMsg,
+                            };
+                            pushFailures.push(failure);
+                            stepFailed.push(failure);
+                            taskResult.status = "failed";
+                            taskResult.error = errMsg;
                         }
-                        log(_jsx(Box, { paddingX: 2, children: _jsx(PushTaskLine, { result: taskResult }) }));
                     }
+                    log(_jsx(Box, { paddingX: 2, children: _jsx(PushTaskLine, { result: taskResult }) }));
                 }
                 return stepFailed.length === 0 && !authFailed;
             }
@@ -627,17 +503,50 @@ async function _push(pushSpan, agentCode, options = {}) {
             t.type === "delete-tool");
         const settingsTasks = pushTasks.filter((t) => t.type === "patch-general-settings");
         const rulesTasks = pushTasks.filter((t) => t.type === "put-rules");
-        await pushStep(paramTasks, "Pushing parameters", false);
-        // Integrations before entities so workflows/tools can safely reference integration codes.
-        if (!integrationUpsertsAlreadyPushed) {
-            await pushStep(integrationUpsertTasks, "Pushing integrations", false);
-        }
-        await pushStep(entityTasks, "Pushing entities", false);
-        // Delete integrations after entity changes drop references where needed.
-        await pushStep(integrationDeleteTasks, "Removing integrations", false);
-        await pushStep(toolTasks, "Pushing tools", true);
-        await pushStep(settingsTasks, "Pushing general settings", false);
-        await pushStep(rulesTasks, "Pushing rules", false);
+        // ─── Push order — see file header for rationale ─────────────────────
+        //
+        // Phase 1: UPSERTS, top-down by dependency (least → most depends-on).
+        //   Every step is sequential by construction (`pushStep` has no
+        //   parallel mode). Do not work around this — the agent-settings
+        //   backend silently merges / drops unresolvable refs on concurrent
+        //   writes.
+        // 1. Parameters — referenced by entities, integrations, tools, rules.
+        await pushStep(paramTasks, "Pushing parameters");
+        // 2. Entities — reference parameters; referenced by tools, integrations.
+        await pushStep(entityTasks, "Pushing entities");
+        // 3. Integration upserts — reference parameters / entities. Must be
+        //    pushed BEFORE knowledge-base uploads (KBs attach to integrations)
+        //    AND before tools (tools reference integration codes).
+        await pushStep(integrationUpsertTasks, "Pushing integrations");
+        // 4. Knowledge Bases — reference integrations existing on the platform.
+        //    KB failures are folded into the same `failed` counter / pushFailures
+        //    array as agent-settings writes, so they hit the "X failed." line, the
+        //    JSON envelope, and the non-zero exit code (BFF contract: zero silent
+        //    errors anywhere in the push pipeline).
+        const kbResult = await pushKnowledgeHubs(projectRoot, projectConfig);
+        pushSpan.setAttribute("push.kb.ok", kbResult.ok);
+        pushSpan.setAttribute("push.kb.failures", kbResult.failures.length);
+        if (!kbResult.ok) {
+            pushSpan.addEvent("kb.failures_folded_into_pushFailures", {
+                count: kbResult.failures.length,
+            });
+            for (const kbFailure of kbResult.failures) {
+                failed++;
+                pushFailures.push(kbFailure);
+            }
+        }
+        // 5. Tools — reference parameters, entities, integrations. Sequential:
+        //    parallel tool pushes caused inter-tool race conditions in
+        //    production (chain-activation, success-rule re-sequencing).
+        await pushStep(toolTasks, "Pushing tools");
+        // 6. Rules — reference tools, parameters, entities.
+        await pushStep(rulesTasks, "Pushing rules");
+        // 7. General settings — mostly standalone but may reference defaults.
+        await pushStep(settingsTasks, "Pushing general settings");
+        // Phase 2: DELETES, bottom-up. Integrations get deleted last so any
+        // tool / entity update above that still referenced them succeeds first.
+        await pushStep(integrationDeleteTasks, "Removing integrations");
+        // Phase 3: Snapshot — runs at the very end of `_push` (see below).
         // Auth fallback
         if (authFailed && authFailedTasks.length > 0 && !savedApiKey) {
             // The auth fallback prompts for an API key. In a non-TTY environment
@@ -652,10 +561,16 @@ async function _push(pushSpan, agentCode, options = {}) {
                 process.stdout.isTTY === true;
             if (!isInteractive) {
                 failed += authFailedTasks.length;
+                pushSpan.addEvent("auth.fallback.non_interactive_rejected", {
+                    failed_task_count: authFailedTasks.length,
+                });
                 throw new AuthenticationError(`Authentication failed for ${authFailedTasks.length} push task(s); cannot prompt for an API key (non-interactive session).`, {
                     suggestion: "Pass --api-key <key>, set AUI_AGENT_TOOLS_API_KEY, or run `aui login` to refresh credentials.",
                 });
             }
+            pushSpan.addEvent("auth.fallback.api_key_prompted", {
+                failed_task_count: authFailedTasks.length,
+            });
             log(_jsxs(Box, { flexDirection: "column", paddingX: 1, children: [_jsx(StatusLine, { kind: "warning", label: "Authentication failed. Your access token may not have permission." }), _jsx(Hint, { message: "You can provide an API key as a fallback. It will be saved to ~/.aui/agent-settings-key" })] }));
             const { key } = await inquirer.prompt([
                 {
@@ -668,6 +583,9 @@ async function _push(pushSpan, agentCode, options = {}) {
             if (key && key.trim()) {
                 saveAgentSettingsApiKey(key.trim());
                 client.setAgentSettingsApiKey(key.trim());
+                pushSpan.addEvent("auth.fallback.api_key_provided", {
+                    retrying_task_count: authFailedTasks.length,
+                });
                 log(_jsx(StatusLine, { kind: "success", label: "Key saved." }));
                 log(_jsx(Box, { paddingX: 1, children: _jsx(StatusLine, { kind: "info", label: `Retrying ${authFailedTasks.length} change(s) with API key...` }) }));
                 authFailed = false;
@@ -697,10 +615,16 @@ async function _push(pushSpan, agentCode, options = {}) {
             }
             else {
                 failed += authFailedTasks.length;
+                pushSpan.addEvent("auth.fallback.api_key_skipped", {
+                    uncovered_task_count: authFailedTasks.length,
+                });
             }
         }
         else if (authFailed && authFailedTasks.length > 0) {
             failed += authFailedTasks.length;
+            pushSpan.addEvent("auth.fallback.saved_key_still_failed", {
+                failed_task_count: authFailedTasks.length,
+            });
             log(_jsx(ErrorDisplay, { error: new AuthenticationError("Auth failed even with saved API key.", {
                     suggestion: "Try: rm ~/.aui/agent-settings-key",
                 }) }));
@@ -734,6 +658,7 @@ async function _push(pushSpan, agentCode, options = {}) {
         if (prePushDraft) {
             const SNAPSHOT_MAX_ATTEMPTS = 4;
             const SNAPSHOT_RETRY_BASE_MS = 1000;
+            const snapshotTracer = getTracer();
             for (let attempt = 1; attempt <= SNAPSHOT_MAX_ATTEMPTS; attempt++) {
                 snapshotAttempts = attempt;
                 const label = attempt === 1
@@ -742,26 +667,65 @@ async function _push(pushSpan, agentCode, options = {}) {
                 if (json)
                     stderrLog(label);
                 const snapshotSpinner = json ? null : startSpinner(label);
+                // Per-attempt span — each snapshot upload is a network call that can
+                // hang for minutes (large multipart upload). Surfacing each attempt
+                // separately in Logfire lets us see retry behavior, attempt latency,
+                // and which attempt finally succeeded. Logfire query:
+                //   `name:"aui.push.task.snapshot" AND attributes."snapshot.attempt":3`
+                // finds every push that needed a third try.
                 let attemptError;
-                try {
-                    const snapshotResult = await pushSnapshot(client, prePushDraft.agentId, prePushDraft.versionId, projectRoot, fileData);
-                    if (snapshotResult.success) {
-                        const okMsg = attempt === 1
-                            ? `Snapshot pushed (${fileData.length} file(s))`
-                            : `Snapshot pushed (${fileData.length} file(s), attempt ${attempt}/${SNAPSHOT_MAX_ATTEMPTS})`;
-                        if (snapshotSpinner)
-                            snapshotSpinner.succeed(okMsg);
-                        else
-                            stderrLog(okMsg);
-                        snapshotSucceeded = true;
-                        snapshotError = undefined;
-                        break;
+                const attemptResolved = await snapshotTracer.startActiveSpan("aui.push.task.snapshot", async (snapSpan) => {
+                    snapSpan.setAttribute("push.task.type", "snapshot");
+                    snapSpan.setAttribute("push.task.label", label);
+                    snapSpan.setAttribute("snapshot.attempt", attempt);
+                    snapSpan.setAttribute("snapshot.max_attempts", SNAPSHOT_MAX_ATTEMPTS);
+                    snapSpan.setAttribute("snapshot.file_count", fileData.length);
+                    snapSpan.setAttribute("snapshot.agent_id", prePushDraft.agentId);
+                    snapSpan.setAttribute("snapshot.version_id", prePushDraft.versionId);
+                    try {
+                        const snapshotResult = await pushSnapshot(client, prePushDraft.agentId, prePushDraft.versionId, projectRoot, fileData);
+                        if (snapshotResult.success) {
+                            snapSpan.setStatus({ code: SpanStatusCode.OK });
+                            snapSpan.setAttribute("snapshot.outcome", "success");
+                            return { ok: true, error: undefined };
+                        }
+                        const errMsg = snapshotResult.error || "Unknown snapshot error";
+                        snapSpan.setStatus({ code: SpanStatusCode.ERROR, message: errMsg });
+                        snapSpan.setAttribute("snapshot.outcome", "failed");
+                        snapSpan.setAttribute("push.task.error", errMsg);
+                        if (attempt < SNAPSHOT_MAX_ATTEMPTS) {
+                            snapSpan.addEvent("snapshot.retry_will_follow", {
+                                next_attempt: attempt + 1,
+                                backoff_ms: SNAPSHOT_RETRY_BASE_MS * Math.pow(2, attempt - 1),
+                            });
+                        }
+                        return { ok: false, error: errMsg };
                     }
-                    attemptError = snapshotResult.error || "Unknown snapshot error";
-                }
-                catch (error) {
-                    attemptError = error instanceof Error ? error.message : String(error);
+                    catch (error) {
+                        const errMsg = error instanceof Error ? error.message : String(error);
+                        snapSpan.setStatus({ code: SpanStatusCode.ERROR, message: errMsg });
+                        snapSpan.recordException(error instanceof Error ? error : new Error(errMsg));
+                        snapSpan.setAttribute("snapshot.outcome", "exception");
+                        snapSpan.setAttribute("push.task.error", errMsg);
+                        return { ok: false, error: errMsg };
+                    }
+                    finally {
+                        snapSpan.end();
+                    }
+                });
+                if (attemptResolved.ok) {
+                    const okMsg = attempt === 1
+                        ? `Snapshot pushed (${fileData.length} file(s))`
+                        : `Snapshot pushed (${fileData.length} file(s), attempt ${attempt}/${SNAPSHOT_MAX_ATTEMPTS})`;
+                    if (snapshotSpinner)
+                        snapshotSpinner.succeed(okMsg);
+                    else
+                        stderrLog(okMsg);
+                    snapshotSucceeded = true;
+                    snapshotError = undefined;
+                    break;
                 }
+                attemptError = attemptResolved.error;
                 snapshotError = attemptError;
                 const isLast = attempt === SNAPSHOT_MAX_ATTEMPTS;
                 const failMsg = isLast
@@ -795,20 +759,51 @@ async function _push(pushSpan, agentCode, options = {}) {
         // This ensures: if snapshot fails, user re-runs `aui push` to retry both
         // failed entity pushes AND the snapshot. Local files remain the source
         // of truth until the server has captured them.
+        //
+        // CRITICAL (CTS-12340 follow-up): when one file has BOTH succeeded and
+        // failed tasks (e.g. integrations.aui.json with a successful DELETE on
+        // web-search and a failed POST on search-flights), do NOT commit that
+        // file to baseline. If we did, the next push's git diff would treat the
+        // failed item as "already on the platform" and emit a PATCH that 404s.
+        // The previous behaviour stuck users in an unrecoverable retry loop.
         let baselineUpdated = false;
         const canCommitBaseline = !prePushDraft || snapshotSucceeded;
         if (canCommitBaseline) {
+            // A file is committable iff EVERY task that targeted it succeeded.
+            // Build the failed-files set from `pushFailures` (which now includes
+            // both agent-settings entity failures AND knowledge-hub failures —
+            // see the KB push step).
+            const failedFiles = new Set();
+            for (const f of pushFailures) {
+                if (f.file)
+                    failedFiles.add(f.file);
+            }
+            const filesSafeToCommit = succeededFiles.filter((f) => !failedFiles.has(f));
             if (failed > 0 && succeeded > 0) {
-                if (succeededFiles.length > 0) {
-                    commitBaselineFiles(projectRoot, succeededFiles, `pushed ${succeeded} change(s)`);
+                if (filesSafeToCommit.length > 0) {
+                    commitBaselineFiles(projectRoot, filesSafeToCommit, `pushed ${succeeded} change(s) (${failedFiles.size} file(s) held back due to per-task failures)`);
                     baselineUpdated = true;
+                    pushSpan.addEvent("baseline.partial_commit", {
+                        committed_files: filesSafeToCommit.length,
+                        held_back_files: failedFiles.size,
+                    });
+                }
+                else {
+                    pushSpan.addEvent("baseline.fully_held_back", {
+                        failed_files: failedFiles.size,
+                    });
                 }
             }
             else if (failed === 0) {
                 commitBaseline(projectRoot, "pushed changes");
                 baselineUpdated = true;
+                pushSpan.addEvent("baseline.full_commit");
             }
         }
+        else {
+            pushSpan.addEvent("baseline.skipped_due_to_snapshot_failure");
+        }
+        pushSpan.setAttribute("push.baseline_updated", baselineUpdated);
         log(_jsx(PushFinalSummary, { succeeded: succeeded, failed: failed, baselineUpdated: baselineUpdated, logDir: logRelPath, memoryPath: memoryPath, snapshotStatus: snapshotStatus, snapshotError: snapshotError }));
         if (failed > 0) {
             log(_jsxs(Box, { flexDirection: "column", paddingX: 1, children: [_jsx(StatusLine, { kind: "warning", label: `${failed} entity change(s) failed to push to DB.` }), pushFailures.map((f) => (_jsxs(Box, { flexDirection: "column", marginLeft: 2, children: [_jsxs(Text, { color: "red", children: ["  ", icons.error, " ", f.label] }), _jsxs(Text, { color: colors.muted, children: ["    Error: ", f.error] }), f.file && _jsxs(Text, { color: colors.muted, children: ["    File: ", f.file] })] }, f.label))), _jsxs(Box, { marginTop: 1, children: [_jsx(Text, { color: colors.info, bold: true, children: "What to do next: " }), _jsxs(Text, { color: colors.muted, children: ["Fix the issues above and re-run ", _jsx(Text, { bold: true, children: "aui push" }), " to retry the failed changes."] })] })] }));
@@ -902,13 +897,11 @@ async function _push(pushSpan, agentCode, options = {}) {
             throw error;
     }
 }
-/**
- * Lookup the agent-management record for the current `.auirc` project
- * (preferred) or the active session fallback — same precedence as draft
- * resolution. Each attempt records its error so callers can surface the full
- * picture instead of silently dropping `agent_id` from request bodies.
- */
-async function lookupAgentManagementInfoForPush(config, projectConfig, session) {
+async function resolveVersionDraft(config, projectConfig, session, explicitVersionId) {
+    // Every error path below MUST throw a typed CLIError (not return null).
+    // Returning null silently exits the CLI with code 0 — the BFF then thinks
+    // the push succeeded when nothing actually happened, and the failure
+    // never reaches Logfire because no exception bubbled to handleError.
     const client = new AUIClient({
         baseUrl: config.apiUrl,
         authToken: config.authToken,
@@ -920,98 +913,55 @@ async function lookupAgentManagementInfoForPush(config, projectConfig, session)
     if (key)
         client.setAgentSettingsApiKey(key);
     let agentInfo;
-    const errors = [];
     const agentMgmtId = session.agent_management_id;
+    // Project's network_id (from .auirc) takes priority over session — when
+    // you're inside a project, that's the agent you mean. Session agent may
+    // point at a different agent (e.g. last `aui agents --switch`).
     const projectNetworkId = projectConfig.agent_id;
     const fallbackNetworkId = session.network_id;
     if (projectNetworkId) {
         try {
             const resp = await client.agentManagement.listAgents(client.getOrganizationId(), 1, 50, { network_id: projectNetworkId });
-            agentInfo = resp.items.find((a) => a.scope.network_id === projectNetworkId ||
-                a.id === projectNetworkId);
-            if (!agentInfo) {
-                errors.push(`listAgents(network_id=${projectNetworkId}) returned ${resp.items.length} item(s), none matched.`);
-            }
+            agentInfo = resp.items.find((a) => a.scope.network_id === projectNetworkId || a.id === projectNetworkId);
         }
         catch (err) {
-            errors.push(`listAgents(network_id=${projectNetworkId}) threw: ${err instanceof Error ? err.message : String(err)}`);
+            // Listing fall-through is fine because the next two branches try other
+            // resolution paths AND a final ConfigError is thrown below if none
+            // succeed. But emit a debug warning so an operator with AUI_DEBUG=1
+            // can see WHICH branch failed and why (zero silent errors policy).
+            if (process.env.AUI_DEBUG) {
+                console.warn(`[debug] resolveVersionDraft: listAgents(network_id=${projectNetworkId}) failed:`, err instanceof Error ? err.message : err);
+            }
         }
     }
-    // Try the session's agent_management_id even when the project has a network
-    // id — it's a direct getAgent call, no list scan, and it gracefully covers
-    // the case where listAgents fell through above.
-    if (!agentInfo && agentMgmtId) {
+    // Fall back to session's agent_management_id only when not inside a project
+    if (!agentInfo && !projectNetworkId && agentMgmtId) {
         try {
             agentInfo = await client.agentManagement.getAgent(agentMgmtId);
         }
         catch (err) {
-            errors.push(`getAgent(${agentMgmtId}) threw: ${err instanceof Error ? err.message : String(err)}`);
+            if (process.env.AUI_DEBUG) {
+                console.warn(`[debug] resolveVersionDraft: getAgent(${agentMgmtId}) failed (stale id?):`, err instanceof Error ? err.message : err);
+            }
         }
     }
-    if (!agentInfo && fallbackNetworkId && fallbackNetworkId !== projectNetworkId) {
+    // Last resort: session's network_id
+    if (!agentInfo && fallbackNetworkId) {
         try {
             const resp = await client.agentManagement.listAgents(client.getOrganizationId(), 1, 50, { network_id: fallbackNetworkId });
-            agentInfo = resp.items.find((a) => a.scope.network_id === fallbackNetworkId ||
-                a.id === fallbackNetworkId);
-            if (!agentInfo) {
-                errors.push(`listAgents(network_id=${fallbackNetworkId}) returned ${resp.items.length} item(s), none matched.`);
-            }
+            agentInfo = resp.items.find((a) => a.scope.network_id === fallbackNetworkId || a.id === fallbackNetworkId);
         }
         catch (err) {
-            errors.push(`listAgents(network_id=${fallbackNetworkId}) threw: ${err instanceof Error ? err.message : String(err)}`);
+            if (process.env.AUI_DEBUG) {
+                console.warn(`[debug] resolveVersionDraft: listAgents(network_id=${fallbackNetworkId}) failed:`, err instanceof Error ? err.message : err);
+            }
         }
     }
-    return { agentInfo, errors };
-}
-/**
- * Return the agent-management UUID to send as `agent_id` on agent-settings
- * write bodies. Reads `.auirc` first; falls back to `lookupAgentManagementInfoForPush`
- * and **persists** the resolved id back to `.auirc` so subsequent pushes don't
- * pay the lookup cost. Throws `ConfigError` if no id can be resolved — never
- * silently returns undefined, because that's how entities ended up in the DB
- * without `agent_id`.
- */
-async function resolvePushAgentManagementId(config, projectConfig, session, projectRoot) {
-    if (projectConfig.agent_management_id)
-        return projectConfig.agent_management_id;
-    const { agentInfo, errors } = await lookupAgentManagementInfoForPush(config, projectConfig, session);
-    if (!agentInfo) {
-        const detail = errors.length > 0 ? `\n  - ${errors.join("\n  - ")}` : "";
-        throw new ConfigError(`Could not resolve agent-management id for this project.${detail}`, {
-            suggestion: "Re-run `aui import-agent` (will populate .auirc.agent_management_id) or `aui pull` to back-fill it.",
-        });
-    }
-    // Migrate legacy projects: persist back so the next push skips the lookup.
-    try {
-        saveProjectConfig({ ...projectConfig, agent_management_id: agentInfo.id }, projectRoot);
-    }
-    catch {
-        // .auirc write failure is non-fatal — we already have the id in memory.
-    }
-    return agentInfo.id;
-}
-async function resolveVersionDraft(config, projectConfig, session, explicitVersionId) {
-    // Every error path below MUST throw a typed CLIError (not return null).
-    // Returning null silently exits the CLI with code 0 — the BFF then thinks
-    // the push succeeded when nothing actually happened, and the failure
-    // never reaches Logfire because no exception bubbled to handleError.
-    const { agentInfo, errors: lookupErrors } = await lookupAgentManagementInfoForPush(config, projectConfig, session);
     if (!agentInfo) {
-        const detail = lookupErrors.length > 0 ? `\n  - ${lookupErrors.join("\n  - ")}` : "";
-        throw new ConfigError(`Could not resolve agent for version management.${detail}`, {
+        throw new ConfigError("Could not resolve agent for version management.", {
             suggestion: "Run `aui import-agent` to link an agent, or check your session with `aui status`.",
         });
     }
-    const client = new AUIClient({
-        baseUrl: config.apiUrl,
-        authToken: config.authToken,
-        accountId: config.accountId,
-        organizationId: config.organizationId,
-        environment: config.environment,
-    });
-    const key = loadAgentSettingsApiKey();
-    if (key)
-        client.setAgentSettingsApiKey(key);
     // If user passed --version-id, validate it's a draft
     if (explicitVersionId) {
         let ver;
@@ -1146,8 +1096,14 @@ async function resolveAgentSettingsParams(config, projectConfig, session, projec
                 saveProjectConfig({ ...projectConfig, network_category_id: categoryId }, projectRoot);
             }
         }
-        catch {
-            // ignore fetch failure
+        catch (err) {
+            // Falls through to the explicit ConfigError below if no categoryId
+            // could be resolved. Surface in AUI_DEBUG so the operator can see
+            // why the auto-fetch failed instead of just the generic "Missing
+            // network_category_id" message.
+            if (process.env.AUI_DEBUG) {
+                console.warn(`[debug] resolveAgentSettingsParams: networks.get(${networkId}) failed:`, err instanceof Error ? err.message : err);
+            }
         }
     }
     if (!categoryId) {
@@ -1182,6 +1138,262 @@ async function resolveAgentSettingsParams(config, projectConfig, session, projec
     }
     return baseParams;
 }
+// ─── Push Task Classification Helpers ───
+/**
+ * Integration tasks split into two phases by the unified push order:
+ *   - Upserts (POST/PATCH/PUT) run BEFORE knowledge bases + tools, so KBs
+ *     can attach to integrations and tools can reference integration codes.
+ *   - Deletes run AFTER tools / entities, so the last write that mentioned
+ *     the integration succeeds before the row is removed.
+ */
+function isIntegrationUpsertTask(t) {
+    return (t.type === "put-integrations" ||
+        t.type === "create-integration" ||
+        t.type === "patch-integration");
+}
+async function pushKnowledgeHubs(projectRoot, projectConfig) {
+    const { getKnowledgeHubChanges } = await import("../utils/git.js");
+    const kbChanges = getKnowledgeHubChanges(projectRoot);
+    if (kbChanges.length === 0)
+        return { ok: true, failures: [] };
+    const kbConfig = getConfig();
+    const kbSession = await getValidSession();
+    const kbNetworkId = projectConfig.agent_id || kbSession?.network_id;
+    if (!kbNetworkId || !kbConfig.authToken) {
+        return {
+            ok: false,
+            failures: [
+                {
+                    label: "Push knowledge hubs",
+                    error: "Cannot push knowledge hubs: missing network_id or auth token. Re-run `aui login` and `aui import-agent`.",
+                },
+            ],
+        };
+    }
+    const { KBViewClient } = await import("../api-client/kb-view-client.js");
+    const { buildScope, readKbFolder } = await import("../services/kb-view.service.js");
+    const { loadAgentSettingsApiKey: loadAsKey } = await import("../config/index.js");
+    const kbViewClient = new KBViewClient({
+        authToken: kbConfig.authToken,
+        apiKey: loadAsKey() || undefined,
+        organizationId: kbConfig.organizationId || "",
+        environment: kbConfig.environment || "staging",
+    });
+    const kbLogDir = path.join(projectRoot, ".aui", "push-logs");
+    fs.mkdirSync(kbLogDir, { recursive: true });
+    kbViewClient.setPushLogDir(kbLogDir);
+    const scope = buildScope({
+        networkId: kbNetworkId,
+        organizationId: projectConfig.organization_id || kbConfig.organizationId || "",
+        accountId: projectConfig.account_id || kbConfig.accountId || "",
+    });
+    const userId = kbSession?.user_id || "cli";
+    const changedKBDirs = new Set();
+    for (const change of kbChanges) {
+        if (change.kbDirName)
+            changedKBDirs.add(change.kbDirName);
+    }
+    const existingKBDirs = [...changedKBDirs].filter((d) => fs.existsSync(path.join(projectRoot, "knowledge-hubs", d)));
+    const deletedKBDirs = [...changedKBDirs].filter((d) => !fs.existsSync(path.join(projectRoot, "knowledge-hubs", d)));
+    const failures = [];
+    let kbDeleteSucceeded = true;
+    if (deletedKBDirs.length > 0) {
+        const { getBaselineFileContent } = await import("../utils/git.js");
+        const deleteSpinner = startSpinner(`Deleting ${deletedKBDirs.length} knowledge base(s) from server...`);
+        try {
+            for (const kbDirName of deletedKBDirs) {
+                const baselineKb = getBaselineFileContent(projectRoot, `knowledge-hubs/${kbDirName}/kb.json`);
+                const kbName = baselineKb?.name || kbDirName;
+                const kbId = baselineKb?.knowledge_base_id;
+                if (!kbId) {
+                    log(_jsx(Box, { paddingX: 1, children: _jsx(StatusLine, { kind: "warning", label: `Cannot delete "${kbName}" — no knowledge_base_id stored. Push the KB first, then delete.` }) }));
+                    continue;
+                }
+                // Per-KB delete in its own span so each one shows up in Logfire as
+                // `aui.push.task.kb-delete` with status, kb name, kb id, and error
+                // body. Same observability shape as agent-settings entity tasks.
+                const kbDelTracer = getTracer();
+                await kbDelTracer.startActiveSpan("aui.push.task.kb-delete", async (span) => {
+                    span.setAttribute("push.task.type", "kb-delete");
+                    span.setAttribute("push.task.label", `Delete knowledge base: ${kbName}`);
+                    span.setAttribute("push.task.file", `knowledge-hubs/${kbDirName}/kb.json`);
+                    span.setAttribute("push.task.kb_id", kbId);
+                    span.setAttribute("push.task.kb_name", kbName);
+                    try {
+                        await kbViewClient.deleteKnowledgeBase(kbId, scope, kbName);
+                        span.setStatus({ code: SpanStatusCode.OK });
+                        log(_jsx(Box, { paddingX: 1, children: _jsx(StatusLine, { kind: "success", label: `Deleted: ${kbName}` }) }));
+                    }
+                    catch (delErr) {
+                        // Per-KB error: count it, keep going so partial work shows up.
+                        if (isNotFoundError(delErr)) {
+                            span.setStatus({ code: SpanStatusCode.OK });
+                            span.addEvent("fallback.delete_404_already_absent");
+                            span.setAttribute("push.task.fallback", "delete_404_already_absent");
+                            log(_jsx(Box, { paddingX: 1, children: _jsx(StatusLine, { kind: "success", label: `Deleted: ${kbName} (already absent)` }) }));
+                        }
+                        else {
+                            kbDeleteSucceeded = false;
+                            const errMsg = delErr instanceof Error ? delErr.message : String(delErr);
+                            span.setStatus({ code: SpanStatusCode.ERROR, message: errMsg });
+                            span.recordException(delErr instanceof Error ? delErr : new Error(errMsg));
+                            span.setAttribute("push.task.error", errMsg);
+                            if (delErr.statusCode) {
+                                span.setAttribute("push.task.error_status_code", delErr.statusCode);
+                            }
+                            failures.push({
+                                label: `Delete knowledge base: ${kbName}`,
+                                file: `knowledge-hubs/${kbDirName}/kb.json`,
+                                error: errMsg,
+                            });
+                            log(_jsx(Box, { paddingX: 1, children: _jsx(StatusLine, { kind: "error", label: `Failed to delete "${kbName}": ${errMsg}` }) }));
+                        }
+                    }
+                    finally {
+                        span.end();
+                    }
+                });
+            }
+            if (kbDeleteSucceeded) {
+                deleteSpinner.succeed(`${deletedKBDirs.length} knowledge base(s) deleted`);
+            }
+            else {
+                deleteSpinner.fail(`Knowledge base deletion completed with errors`);
+            }
+        }
+        catch (error) {
+            kbDeleteSucceeded = false;
+            deleteSpinner.fail("Knowledge base deletion failed");
+            const errMsg = error instanceof Error ? error.message : String(error);
+            failures.push({
+                label: "Delete knowledge bases (batch)",
+                error: errMsg,
+            });
+            log(_jsx(ErrorDisplay, { error: error }));
+        }
+    }
+    let kbUploadSucceeded = false;
+    if (existingKBDirs.length > 0) {
+        const kbSpinner = startSpinner(`Pushing ${existingKBDirs.length} knowledge base(s)...`);
+        let hadUploadFailure = false;
+        try {
+            for (const kbDirName of existingKBDirs) {
+                const kbDir = path.join(projectRoot, "knowledge-hubs", kbDirName);
+                const kbData = readKbFolder(kbDir);
+                if (!kbData)
+                    continue;
+                const SUPPORTED_EXTENSIONS = new Set([".pdf", ".md", ".txt", ".json"]);
+                const supportedFiles = kbData.binaryFiles.filter((f) => SUPPORTED_EXTENSIONS.has(path.extname(f).toLowerCase()));
+                const skippedFiles = kbData.binaryFiles.filter((f) => !SUPPORTED_EXTENSIONS.has(path.extname(f).toLowerCase()));
+                for (const skipped of skippedFiles) {
+                    log(_jsx(Box, { paddingX: 1, children: _jsx(StatusLine, { kind: "warning", label: `Skipped unsupported file: ${path.basename(skipped)} (only .pdf, .md, .txt, .json)` }) }));
+                }
+                if (supportedFiles.length > 0) {
+                    // Per-KB upload in its own span — Logfire query
+                    // `name:"aui.push.task.kb-upload" AND status_code:ERROR` finds
+                    // every KB push failure across all agents.
+                    const kbUpTracer = getTracer();
+                    await kbUpTracer.startActiveSpan("aui.push.task.kb-upload", async (span) => {
+                        span.setAttribute("push.task.type", "kb-upload");
+                        span.setAttribute("push.task.label", `Push knowledge base: ${kbData.name || kbDirName}`);
+                        span.setAttribute("push.task.file", `knowledge-hubs/${kbDirName}/kb.json`);
+                        span.setAttribute("push.task.kb_name", kbData.name || kbDirName);
+                        span.setAttribute("push.task.file_count", supportedFiles.length);
+                        try {
+                            const importResult = await kbViewClient.importFiles({
+                                files: supportedFiles,
+                                scope,
+                                created_by: userId,
+                                knowledge_base_name: kbData.name,
+                                knowledge_base_description: kbData.description,
+                            });
+                            span.setStatus({ code: SpanStatusCode.OK });
+                            if (importResult.knowledge_base_id) {
+                                span.setAttribute("push.task.kb_id", importResult.knowledge_base_id);
+                                const kbJsonPath = path.join(kbDir, "kb.json");
+                                try {
+                                    const raw = JSON.parse(fs.readFileSync(kbJsonPath, "utf-8"));
+                                    raw.knowledge_base_id = importResult.knowledge_base_id;
+                                    fs.writeFileSync(kbJsonPath, JSON.stringify(raw, null, 2) + "\n");
+                                }
+                                catch (writeErr) {
+                                    // kb.json id write fail is non-fatal but tell the user so the
+                                    // next push doesn't surprise them with "no knowledge_base_id stored".
+                                    span.addEvent("kb_id_writeback_failed");
+                                    if (process.env.AUI_DEBUG) {
+                                        console.warn(`[debug] failed to write knowledge_base_id back to ${kbJsonPath}:`, writeErr);
+                                    }
+                                    log(_jsx(Box, { paddingX: 1, children: _jsx(StatusLine, { kind: "warning", label: `Could not persist knowledge_base_id back to ${path.basename(kbJsonPath)} — re-import or run \`aui pull\` to recover.` }) }));
+                                }
+                            }
+                        }
+                        catch (uploadErr) {
+                            hadUploadFailure = true;
+                            const errMsg = uploadErr instanceof Error ? uploadErr.message : String(uploadErr);
+                            span.setStatus({ code: SpanStatusCode.ERROR, message: errMsg });
+                            span.recordException(uploadErr instanceof Error ? uploadErr : new Error(errMsg));
+                            span.setAttribute("push.task.error", errMsg);
+                            if (uploadErr.statusCode) {
+                                span.setAttribute("push.task.error_status_code", uploadErr.statusCode);
+                            }
+                            failures.push({
+                                label: `Push knowledge base: ${kbData.name || kbDirName}`,
+                                file: `knowledge-hubs/${kbDirName}/kb.json`,
+                                error: errMsg,
+                            });
+                            log(_jsx(Box, { paddingX: 1, children: _jsx(StatusLine, { kind: "error", label: `Failed to push "${kbData.name || kbDirName}": ${errMsg}` }) }));
+                        }
+                        finally {
+                            span.end();
+                        }
+                    });
+                }
+            }
+            if (hadUploadFailure) {
+                kbSpinner.fail(`Knowledge base push completed with errors`);
+                kbUploadSucceeded = false;
+            }
+            else {
+                kbSpinner.succeed(`Knowledge base(s) pushed`);
+                kbUploadSucceeded = true;
+            }
+        }
+        catch (error) {
+            kbSpinner.fail("Knowledge base push failed");
+            const errMsg = error instanceof Error ? error.message : String(error);
+            failures.push({
+                label: "Push knowledge bases (batch)",
+                error: errMsg,
+            });
+            log(_jsx(ErrorDisplay, { error: error }));
+        }
+    }
+    else {
+        kbUploadSucceeded = true;
+    }
+    const kbPushSucceeded = kbUploadSucceeded && kbDeleteSucceeded;
+    if (kbPushSucceeded) {
+        const kbFilesToAdd = kbChanges
+            .filter((c) => c.status !== "deleted")
+            .map((c) => c.file);
+        const kbFilesToDelete = kbChanges
+            .filter((c) => c.status === "deleted")
+            .map((c) => c.file);
+        if (kbFilesToAdd.length > 0 || kbFilesToDelete.length > 0) {
+            const { commitBaselineFiles: commitKBFiles, removeBaselineFiles } = await import("../utils/git.js");
+            if (kbFilesToDelete.length > 0) {
+                removeBaselineFiles(projectRoot, kbFilesToDelete);
+            }
+            if (kbFilesToAdd.length > 0) {
+                commitKBFiles(projectRoot, kbFilesToAdd, "pushed knowledge hub changes");
+            }
+            else {
+                commitKBFiles(projectRoot, [], "removed knowledge hub files");
+            }
+        }
+    }
+    return { ok: kbPushSucceeded && failures.length === 0, failures };
+}
 // ─── Array File Info Helper ───
 function getArrayFileInfoForPush(filePath, dir) {
     try {
@@ -1210,11 +1422,6 @@ function getArrayFileInfoForPush(filePath, dir) {
         return null;
     }
 }
-function isIntegrationUpsertTask(t) {
-    return (t.type === "put-integrations" ||
-        t.type === "create-integration" ||
-        t.type === "patch-integration");
-}
 function writePushMemory(projectRoot, agentCode, agentId, pushTasks, succeededFiles, pushFailures) {
     try {
         const memoryDir = path.join(projectRoot, "memory");
@@ -1304,7 +1511,13 @@ function writePushMemory(projectRoot, agentCode, agentId, pushTasks, succeededFi
         fs.writeFileSync(filePath, lines.join("\n"), "utf-8");
         return path.relative(projectRoot, filePath);
     }
-    catch {
+    catch (err) {
+        // Memory file is diagnostic only — its failure shouldn't block the push.
+        // But emit a debug warning so an operator chasing "where's my push memory"
+        // sees what went wrong.
+        if (process.env.AUI_DEBUG) {
+            console.warn("[debug] writePushMemory failed:", err instanceof Error ? err.message : err);
+        }
         return undefined;
     }
 }
@@ -1594,95 +1807,323 @@ async function executePushTask(client, params, task) {
         }
     });
 }
-// Fall back to PATCH only on a 409 Conflict from the create call — the BFF
-// returns 409 specifically for "already exists" conflicts, so any other
-// status code is a real error and must be surfaced (not masked behind a
-// follow-up PATCH that would likely fail with a misleading "not found").
+// ─── Adaptive fallback matrix (per write task) ────────────────────────────
+//
+// Every entity write goes through three layers, applied in this order:
+//
+//   (a) `withTransientRetry`   — retries once on 500/502/503/504 with a 1s
+//                                back-off. Per-call, isolated from other
+//                                tasks. 4xx is never retried (deterministic).
+//   (b) `POST 409 → PATCH`     — the create call hit a row with the same
+//                                code; the platform already has it. Convert
+//                                to a PATCH and continue. Pre-existing.
+//   (c) `PATCH 404 → POST`     — the patch call hit "not found"; baseline
+//                                drifted (item never landed on the platform
+//                                from a prior partial push). Convert to a
+//                                POST so the row reappears. NEW.
+//   (d) `DELETE 404 → success` — the delete target is already gone. The
+//                                desired end state is reached. Treat as
+//                                success and log "(already absent)" so the
+//                                user can see what happened. NEW.
+//
+// All four layers are visible in the per-task push log files under
+// `.aui/push-logs/` so the BFF / agent-builder-bff can audit decisions.
 function isAlreadyExistsConflict(err) {
     if (!err || typeof err !== "object")
         return false;
-    const statusCode = err.statusCode
+    const code = err.statusCode
+        ?? err.status;
+    return code === 409;
+}
+function isNotFoundError(err) {
+    if (!err || typeof err !== "object")
+        return false;
+    const code = err.statusCode
         ?? err.status;
-    return statusCode === 409;
+    return code === 404;
+}
+function isTransient5xx(err) {
+    if (!err || typeof err !== "object")
+        return false;
+    const code = err.statusCode
+        ?? err.status;
+    return code === 500 || code === 502 || code === 503 || code === 504;
+}
+/**
+ * Tag the currently-active span with a fallback-decision event + attribute,
+ * so Logfire shows exactly which adaptive layer fired during a push.
+ *
+ * Useful queries once published:
+ *   - `attributes."push.task.fallback":"patch_404_to_post"` → every drift
+ *     recovery (next push self-healed a previously-failed POST).
+ *   - `attributes."push.task.fallback":"transient_retry"` → backend 5xx
+ *     events that were absorbed by the retry layer.
+ *   - `attributes."push.task.fallback":"post_409_to_patch"` → "create"
+ *     calls that converted to "update" because the row pre-existed.
+ *   - `attributes."push.task.fallback":"delete_404_already_absent"` →
+ *     deletes that no-op'd because the row was already gone.
+ *
+ * No-op when there's no active span (e.g. unit tests outside the push flow).
+ */
+function recordFallbackEvent(kind, detail) {
+    const span = trace.getActiveSpan();
+    if (!span)
+        return;
+    span.addEvent(`fallback.${kind}`, detail);
+    span.setAttribute("push.task.fallback", kind);
+    for (const [k, v] of Object.entries(detail ?? {})) {
+        span.setAttribute(`push.task.fallback.${k}`, v);
+    }
+}
+/**
+ * Run one entity-settings write call once, and retry exactly once on a
+ * transient 5xx after a 1s back-off. The snapshot upload has its own
+ * retry loop (see `pushSnapshot`); this is the equivalent for individual
+ * agent-settings writes. Never retries on 4xx — those are deterministic.
+ */
+async function withTransientRetry(label, fn) {
+    try {
+        return await fn();
+    }
+    catch (err) {
+        if (!isTransient5xx(err))
+            throw err;
+        const code = err.statusCode
+            ?? err.status;
+        if (process.env.AUI_DEBUG) {
+            console.log(`[debug] ${label} got ${code}, retrying once after 1000ms`);
+        }
+        recordFallbackEvent("transient_retry", {
+            label,
+            status_code: code ?? 0,
+            backoff_ms: 1000,
+        });
+        await new Promise((r) => setTimeout(r, 1000));
+        return await fn();
+    }
+}
+/**
+ * A delete that has been short-circuited because the row was already absent
+ * on the platform. Returned as a successful resolution so callers don't
+ * count the task as failed, but tagged so the per-task log line can show
+ * "(already absent)" instead of a generic ✓.
+ */
+const DELETE_ALREADY_ABSENT = Object.freeze({
+    __aui_already_absent__: true,
+    message: "Already absent on platform — treated as success",
+});
+function isAlreadyAbsentResult(value) {
+    return (!!value
+        && typeof value === "object"
+        && value.__aui_already_absent__ === true);
 }
 async function _executePushTask(client, params, task) {
     switch (task.type) {
         case "patch-tool":
-            return client.patchTool(params, task.toolName, task.body);
-        case "create-tool":
-            try {
-                return await client.createTool(params, task.body);
-            }
-            catch (err) {
-                if (isAlreadyExistsConflict(err)) {
-                    if (process.env.AUI_DEBUG) {
-                        console.log(`[debug] create-tool: already-exists detected, falling back to PATCH`);
+            return withTransientRetry(`PATCH tool ${task.toolName}`, async () => {
+                try {
+                    return await client.patchTool(params, task.toolName, task.body);
+                }
+                catch (err) {
+                    if (isNotFoundError(err)) {
+                        if (process.env.AUI_DEBUG) {
+                            console.log(`[debug] patch-tool ${task.toolName}: 404 not found, falling back to POST`);
+                        }
+                        recordFallbackEvent("patch_404_to_post", { task_type: "patch-tool", tool: String(task.toolName ?? "") });
+                        return client.createTool(params, task.body);
                     }
-                    const body = task.body;
-                    const toolCode = body.code || "";
-                    const toolName = toolCode.toUpperCase().replace(/-/g, "_");
-                    return client.patchTool(params, toolName, body);
+                    throw err;
                 }
-                if (process.env.AUI_DEBUG) {
-                    const statusCode = err.statusCode ?? err.status;
-                    console.log(`[debug] create-tool failed (${statusCode}); not already-exists, surfacing original`);
+            });
+        case "create-tool":
+            return withTransientRetry(`POST tool ${task.toolName ?? task.itemCode}`, async () => {
+                try {
+                    return await client.createTool(params, task.body);
                 }
-                throw err;
-            }
+                catch (err) {
+                    if (isAlreadyExistsConflict(err)) {
+                        if (process.env.AUI_DEBUG) {
+                            console.log(`[debug] create-tool: 409 already-exists, falling back to PATCH`);
+                        }
+                        const body = task.body;
+                        const toolCode = body.code || "";
+                        const toolName = toolCode.toUpperCase().replace(/-/g, "_");
+                        recordFallbackEvent("post_409_to_patch", { task_type: "create-tool", tool: toolName });
+                        return client.patchTool(params, toolName, body);
+                    }
+                    throw err;
+                }
+            });
         case "delete-tool":
-            return client.deleteTool(params, task.toolName);
+            return withTransientRetry(`DELETE tool ${task.toolName}`, async () => {
+                try {
+                    return await client.deleteTool(params, task.toolName);
+                }
+                catch (err) {
+                    if (isNotFoundError(err)) {
+                        if (process.env.AUI_DEBUG) {
+                            console.log(`[debug] delete-tool ${task.toolName}: 404 already absent`);
+                        }
+                        recordFallbackEvent("delete_404_already_absent", { task_type: "delete-tool", tool: String(task.toolName ?? "") });
+                        return DELETE_ALREADY_ABSENT;
+                    }
+                    throw err;
+                }
+            });
         case "patch-general-settings":
-            return client.patchGeneralSettings(params, task.body);
+            return withTransientRetry("PATCH general-settings", () => client.patchGeneralSettings(params, task.body));
         case "put-parameters":
-            return client.putParameters(params, task.body, task.oldBody);
+            return withTransientRetry("PUT parameters", () => client.putParameters(params, task.body, task.oldBody));
         case "put-entities":
-            return client.putEntities(params, task.body, task.oldBody);
+            return withTransientRetry("PUT entities", () => client.putEntities(params, task.body, task.oldBody));
         case "put-integrations":
-            return client.putIntegrations(params, task.body, task.oldBody);
+            return withTransientRetry("PUT integrations", () => client.putIntegrations(params, task.body, task.oldBody));
         case "create-parameter":
-            try {
-                return await client.createParameter(params, task.body);
-            }
-            catch (err) {
-                if (isAlreadyExistsConflict(err)) {
-                    return client.patchParameter(params, task.itemCode, task.body);
+            return withTransientRetry(`POST param ${task.itemCode}`, async () => {
+                try {
+                    return await client.createParameter(params, task.body);
                 }
-                throw err;
-            }
+                catch (err) {
+                    if (isAlreadyExistsConflict(err)) {
+                        if (process.env.AUI_DEBUG) {
+                            console.log(`[debug] create-parameter ${task.itemCode}: 409, falling back to PATCH`);
+                        }
+                        recordFallbackEvent("post_409_to_patch", { task_type: "create-parameter", code: String(task.itemCode ?? "") });
+                        return client.patchParameter(params, task.itemCode, task.body);
+                    }
+                    throw err;
+                }
+            });
         case "patch-parameter":
-            return client.patchParameter(params, task.itemCode, task.body);
+            return withTransientRetry(`PATCH param ${task.itemCode}`, async () => {
+                try {
+                    return await client.patchParameter(params, task.itemCode, task.body);
+                }
+                catch (err) {
+                    if (isNotFoundError(err)) {
+                        if (process.env.AUI_DEBUG) {
+                            console.log(`[debug] patch-parameter ${task.itemCode}: 404 not found, falling back to POST`);
+                        }
+                        recordFallbackEvent("patch_404_to_post", { task_type: "patch-parameter", code: String(task.itemCode ?? "") });
+                        return client.createParameter(params, task.body);
+                    }
+                    throw err;
+                }
+            });
         case "delete-parameter":
-            return client.deleteParameter(params, task.itemCode, task.body);
+            return withTransientRetry(`DELETE param ${task.itemCode}`, async () => {
+                try {
+                    return await client.deleteParameter(params, task.itemCode, task.body);
+                }
+                catch (err) {
+                    if (isNotFoundError(err)) {
+                        if (process.env.AUI_DEBUG) {
+                            console.log(`[debug] delete-parameter ${task.itemCode}: 404 already absent`);
+                        }
+                        recordFallbackEvent("delete_404_already_absent", { task_type: "delete-parameter", code: String(task.itemCode ?? "") });
+                        return DELETE_ALREADY_ABSENT;
+                    }
+                    throw err;
+                }
+            });
         case "create-entity":
-            try {
-                return await client.createEntity(params, task.body);
-            }
-            catch (err) {
-                if (isAlreadyExistsConflict(err)) {
-                    return client.patchEntity(params, task.itemCode, task.body);
+            return withTransientRetry(`POST entity ${task.itemCode}`, async () => {
+                try {
+                    return await client.createEntity(params, task.body);
                 }
-                throw err;
-            }
+                catch (err) {
+                    if (isAlreadyExistsConflict(err)) {
+                        if (process.env.AUI_DEBUG) {
+                            console.log(`[debug] create-entity ${task.itemCode}: 409, falling back to PATCH`);
+                        }
+                        recordFallbackEvent("post_409_to_patch", { task_type: "create-entity", code: String(task.itemCode ?? "") });
+                        return client.patchEntity(params, task.itemCode, task.body);
+                    }
+                    throw err;
+                }
+            });
         case "patch-entity":
-            return client.patchEntity(params, task.itemCode, task.body);
+            return withTransientRetry(`PATCH entity ${task.itemCode}`, async () => {
+                try {
+                    return await client.patchEntity(params, task.itemCode, task.body);
+                }
+                catch (err) {
+                    if (isNotFoundError(err)) {
+                        if (process.env.AUI_DEBUG) {
+                            console.log(`[debug] patch-entity ${task.itemCode}: 404, falling back to POST`);
+                        }
+                        recordFallbackEvent("patch_404_to_post", { task_type: "patch-entity", code: String(task.itemCode ?? "") });
+                        return client.createEntity(params, task.body);
+                    }
+                    throw err;
+                }
+            });
         case "delete-entity":
-            return client.deleteEntity(params, task.itemCode);
+            return withTransientRetry(`DELETE entity ${task.itemCode}`, async () => {
+                try {
+                    return await client.deleteEntity(params, task.itemCode);
+                }
+                catch (err) {
+                    if (isNotFoundError(err)) {
+                        if (process.env.AUI_DEBUG) {
+                            console.log(`[debug] delete-entity ${task.itemCode}: 404 already absent`);
+                        }
+                        recordFallbackEvent("delete_404_already_absent", { task_type: "delete-entity", code: String(task.itemCode ?? "") });
+                        return DELETE_ALREADY_ABSENT;
+                    }
+                    throw err;
+                }
+            });
         case "create-integration":
-            try {
-                return await client.createIntegration(params, task.body);
-            }
-            catch (err) {
-                if (isAlreadyExistsConflict(err)) {
-                    return client.patchIntegration(params, task.itemCode, task.body);
+            return withTransientRetry(`POST integration ${task.itemCode}`, async () => {
+                try {
+                    return await client.createIntegration(params, task.body);
                 }
-                throw err;
-            }
+                catch (err) {
+                    if (isAlreadyExistsConflict(err)) {
+                        if (process.env.AUI_DEBUG) {
+                            console.log(`[debug] create-integration ${task.itemCode}: 409, falling back to PATCH`);
+                        }
+                        recordFallbackEvent("post_409_to_patch", { task_type: "create-integration", code: String(task.itemCode ?? "") });
+                        return client.patchIntegration(params, task.itemCode, task.body);
+                    }
+                    throw err;
+                }
+            });
         case "patch-integration":
-            return client.patchIntegration(params, task.itemCode, task.body);
+            return withTransientRetry(`PATCH integration ${task.itemCode}`, async () => {
+                try {
+                    return await client.patchIntegration(params, task.itemCode, task.body);
+                }
+                catch (err) {
+                    if (isNotFoundError(err)) {
+                        if (process.env.AUI_DEBUG) {
+                            console.log(`[debug] patch-integration ${task.itemCode}: 404 not found, falling back to POST`);
+                        }
+                        recordFallbackEvent("patch_404_to_post", { task_type: "patch-integration", code: String(task.itemCode ?? "") });
+                        return client.createIntegration(params, task.body);
+                    }
+                    throw err;
+                }
+            });
         case "delete-integration":
-            return client.deleteIntegration(params, task.itemCode);
+            return withTransientRetry(`DELETE integration ${task.itemCode}`, async () => {
+                try {
+                    return await client.deleteIntegration(params, task.itemCode);
+                }
+                catch (err) {
+                    if (isNotFoundError(err)) {
+                        if (process.env.AUI_DEBUG) {
+                            console.log(`[debug] delete-integration ${task.itemCode}: 404 already absent`);
+                        }
+                        recordFallbackEvent("delete_404_already_absent", { task_type: "delete-integration", code: String(task.itemCode ?? "") });
+                        return DELETE_ALREADY_ABSENT;
+                    }
+                    throw err;
+                }
+            });
         case "put-rules":
-            return client.putRules(params, task.body);
+            return withTransientRetry("PUT rules", () => client.putRules(params, task.body));
         default:
             throw new Error(`Unknown push task type: ${task.type}`);
     }