aui-agent-builder 0.3.83 → 0.3.85

package/dist/commands/push.js

@@ -237,208 +237,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." }) }));
@@ -479,20 +286,10 @@ async function _push(pushSpan, agentCode, options = {}) {
         // available drafts. Push is rejected if no draft is found.
         let prePushDraft = null;
         if (projectConfig.version_id || options.versionId) {
-            prePushDraft =
-                resolvedPushDraftCache ??
-                    (await resolveVersionDraft(config, projectConfig, session, options.versionId));
+            prePushDraft = await resolveVersionDraft(config, projectConfig, session, options.versionId);
             agentSettingsParams.version_id = prePushDraft.versionId;
-            agentSettingsParams.agent_id = prePushDraft.agentId;
-            cachedPushAgentManagementId = prePushDraft.agentId;
             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;
-        }
         const pushTasks = buildPushTasks(diff, fileData, projectRoot, getFileDiff);
         pushSpan.setAttribute("push.task_count", pushTasks.length);
         if (diff) {
@@ -526,82 +323,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 +397,45 @@ 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);
+        if (!kbResult.ok) {
+            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
@@ -795,12 +593,29 @@ 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;
                 }
             }
@@ -902,13 +717,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 +733,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 +916,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 +958,215 @@ 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;
+                }
+                try {
+                    await kbViewClient.deleteKnowledgeBase(kbId, scope, kbName);
+                    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)) {
+                        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);
+                        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}` }) }));
+                    }
+                }
+            }
+            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) {
+                    try {
+                        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 (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".
+                                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);
+                        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}` }) }));
+                    }
+                }
+            }
+            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 +1195,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 +1284,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 +1580,280 @@ 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;
+}
+/**
+ * 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`);
+        }
+        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`);
+                        }
+                        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, "_");
+                        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`);
+                        }
+                        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`);
+                        }
+                        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`);
+                        }
+                        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`);
+                        }
+                        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`);
+                        }
+                        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`);
+                        }
+                        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`);
+                        }
+                        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`);
+                        }
+                        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`);
+                        }
+                        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`);
+                        }
+                        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}`);
     }