aui-agent-builder 0.3.103 → 0.3.105

package/dist/commands/legacy/push-records-mode.js

@@ -0,0 +1,2575 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as fs from "fs";
+import * as path from "path";
+import { render } from "ink";
+import { Box, Text } from "ink";
+import inquirer from "inquirer";
+// NOTE: never import `node-fetch` directly. Per the workspace rule in
+// `.cursor/rules/repo-primer.mdc`, all HTTP must go through
+// `utils/fetch-with-timeout.js` to guarantee the 60s default timeout
+// that prevents hung backends from wedging push indefinitely. The
+// legacy pipeline only makes HTTP calls via `client.agentManagement.*`
+// (which already routes through the centralized fetch wrapper), so
+// there's no fetch import here on purpose.
+import { getConfig, loadProjectConfig, saveProjectConfig, loadAgentSettingsApiKey, saveAgentSettingsApiKey, } from "../../config/index.js";
+import { getValidSession } from "../../services/auth.service.js";
+import { AUIClient, applyScopeLevel } from "../../api-client/index.js";
+import { findAuiFiles, parseAuiFile } from "../../utils/index.js";
+import { validate } from "../validate.js";
+import { getTracer, SpanStatusCode, setUserContext, setAgentContext, } 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";
+import { colors, icons } from "../../ui/theme.js";
+import { PushFileSummary, PushChangesView, PushTaskLine, PushFinalSummary, } from "../../ui/views/PushView.js";
+import { isJsonMode, outputJson, stderrLog } from "../../utils/json-output.js";
+// ─── Ink Rendering Helpers ───
+function log(node) {
+    const { unmount } = render(node);
+    unmount();
+}
+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) {
+            safeUnmount();
+            log(_jsx(StatusLine, { kind: "success", label: msg }));
+        },
+        fail(msg) {
+            safeUnmount();
+            log(_jsx(StatusLine, { kind: "error", label: msg }));
+        },
+        stop() {
+            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();
+    }
+}
+/**
+ * Run the legacy records-mode push flow.
+ *
+ * Caller contract — `push.tsx` MUST:
+ *   1. Have already opened the parent `aui.push` span (passed in as
+ *      `pushSpan`) — the legacy code attaches a pile of attributes to
+ *      it.
+ *   2. Have already determined that the target agent is records-mode
+ *      (`AgentInfo.bundle_mode === false` or missing). Calling this
+ *      against a blob-mode agent will result in 422 errors from the
+ *      first `/view` call.
+ *
+ * The function performs the entire legacy pipeline end-to-end:
+ *   validate → resolve draft → preflight → per-entity dispatch (params
+ *   → entities → integrations → KBs → tools → rules → general settings
+ *   → integration deletes) → snapshot push → write push memory.
+ */
+export async function runLegacyPush(pushSpan, agentCode, options = {}) {
+    pushSpan.setAttribute("push.dispatch.mode", "records");
+    await _push(pushSpan, agentCode, options);
+}
+async function _push(pushSpan, agentCode, options = {}) {
+    const config = getConfig();
+    const projectRoot = config.projectRoot || process.cwd();
+    if (!config.isAuthenticated) {
+        throw new AuthenticationError("Not logged in.");
+    }
+    const projectConfig = loadProjectConfig(projectRoot);
+    if (!projectConfig) {
+        const auircPath = path.join(projectRoot, ".auirc");
+        const exists = fs.existsSync(auircPath);
+        throw new ConfigError("No agent linked to this project.", {
+            suggestion: exists
+                ? ".auirc file exists but could not be read (check if it contains valid JSON)."
+                : "Run `aui import` first to link an agent.",
+        });
+    }
+    pushSpan.setAttribute("push.agent_code", projectConfig.agent_code || "");
+    pushSpan.setAttribute("push.agent_id", projectConfig.agent_id || "");
+    if (!projectConfig.agent_id) {
+        throw new ConfigError('.auirc is missing "agent_id". Re-import the agent.', {
+            suggestion: "Run: aui import",
+        });
+    }
+    const json = isJsonMode();
+    // Record up-front whether the user invoked --force. We tag this on the
+    // root push span (not just the preflight span) so dashboards / alerts
+    // that look at the top of a trace can immediately see "this push used
+    // --force" without drilling into preflight. Keeps the audit trail
+    // legible regardless of where the user is browsing in Logfire.
+    pushSpan.setAttribute("push.force_used", options.force === true);
+    if (!options.skipValidation) {
+        if (!json)
+            log(_jsx(StatusLine, { kind: "info", label: "Validating configuration..." }));
+        else
+            stderrLog("Validating configuration...");
+        // 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();
+        // Captured via the `onResult` callback below. Held in a ref so it's
+        // available outside the closure where the bypass event fires. The
+        // explicit `ValidateResultSummary | null` type is necessary —
+        // TypeScript's strict control-flow analysis would otherwise narrow
+        // the declared type to `null` after the await, since the assignment
+        // happens inside a callback whose execution it can't trace.
+        let validateSummary = null;
+        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);
+            // Validation now hits the agent-settings backend (see
+            // commands/validate.tsx). Surface the agent identifiers on this
+            // span so a Logfire row tells the on-call exactly which agent
+            // was being validated when the preflight failed — without
+            // having to drill into the nested `aui.validate.remote` child.
+            await setUserContext(vSpan);
+            await setAgentContext(vSpan, {
+                agentId: projectConfig.agent_id,
+                agentCode: projectConfig.agent_code,
+                agentManagementId: projectConfig.agent_management_id,
+                versionId: projectConfig.version_id,
+                versionLabel: projectConfig.version_label,
+                networkId: projectConfig.agent_id,
+                accountId: projectConfig.account_id,
+                organizationId: projectConfig.organization_id,
+                networkCategoryId: projectConfig.network_category_id,
+            });
+            try {
+                const ok = await validate(projectRoot, {
+                    verbose: false,
+                    onResult: (s) => {
+                        validateSummary = s;
+                        // Denormalize the validate result onto the preflight span
+                        // so the trace's top-level shows the verdict + counts
+                        // without having to expand the nested `aui.validate`
+                        // child. Especially valuable when --force later
+                        // bypasses: the bypass event reads from these.
+                        vSpan.setAttribute("push.preflight.validate.ok", s.ok);
+                        vSpan.setAttribute("push.preflight.validate.error_count", s.errorCount);
+                        vSpan.setAttribute("push.preflight.validate.warning_count", s.warningCount);
+                        vSpan.setAttribute("push.preflight.validate.remote_reachable", s.remoteReachable);
+                        if (s.remoteValid !== null) {
+                            vSpan.setAttribute("push.preflight.validate.remote_valid", s.remoteValid);
+                        }
+                        if (s.remoteStatusCode !== null) {
+                            vSpan.setAttribute("push.preflight.validate.remote_status_code", s.remoteStatusCode);
+                        }
+                        if (s.remoteFailureReason) {
+                            vSpan.setAttribute("push.preflight.validate.remote_failure_reason", s.remoteFailureReason);
+                        }
+                        if (s.issueCodes.length > 0) {
+                            vSpan.setAttribute("push.preflight.validate.issue_codes", s.issueCodes.join(","));
+                        }
+                        if (s.topIssueMessages.length > 0) {
+                            vSpan.setAttribute("push.preflight.validate.top_messages", JSON.stringify(s.topIssueMessages));
+                        }
+                    },
+                });
+                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();
+            }
+        });
+        // ── Safety gate: a falsy validate() result MUST block the push ──
+        //
+        // The remote validator may return false because:
+        //   • the backend reported `valid: false` (real validation errors)
+        //   • the backend was unreachable / 5xx (infra failure)
+        //   • the local project lacks an agent_id or auth (cannot run validate)
+        // In every case we refuse to push so the user can fix the underlying
+        // issue. `--force` remains the explicit escape hatch for emergencies
+        // (matches the pre-remote-validate contract documented in this file).
+        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) {
+            // Loud-log a --force bypass. The event carries the same data we
+            // attached to the preflight span (error count, codes, top
+            // messages, remote reachability) so anyone reading the trace —
+            // or filtering Logfire for `event.name = 'preflight.validation_failed_but_forced'`
+            // — sees WHY validation failed and what was bypassed without
+            // needing to JOIN against nested spans. This is the closest we
+            // get to an audit log of "who pushed broken stuff and what was
+            // broken about it" without changing user behaviour.
+            //
+            // Cast: TS narrows `validateSummary` to `null` after the await
+            // because it can't see the callback set it (control-flow analysis
+            // doesn't track mutation through closures). Cast back to the
+            // declared union — the runtime value really is `ValidateResultSummary | null`.
+            const s = validateSummary;
+            pushSpan.setAttribute("push.preflight.validate.bypassed", true);
+            if (s) {
+                pushSpan.setAttribute("push.preflight.validate.bypassed.error_count", s.errorCount);
+                pushSpan.setAttribute("push.preflight.validate.bypassed.warning_count", s.warningCount);
+                pushSpan.setAttribute("push.preflight.validate.bypassed.remote_reachable", s.remoteReachable);
+                if (s.issueCodes.length > 0) {
+                    pushSpan.setAttribute("push.preflight.validate.bypassed.issue_codes", s.issueCodes.join(","));
+                }
+                if (s.topIssueMessages.length > 0) {
+                    pushSpan.setAttribute("push.preflight.validate.bypassed.top_messages", JSON.stringify(s.topIssueMessages));
+                }
+                if (s.remoteFailureReason) {
+                    pushSpan.setAttribute("push.preflight.validate.bypassed.remote_failure_reason", s.remoteFailureReason);
+                }
+                if (s.remoteStatusCode !== null) {
+                    pushSpan.setAttribute("push.preflight.validate.bypassed.remote_status_code", s.remoteStatusCode);
+                }
+            }
+            pushSpan.addEvent("preflight.validation_failed_but_forced", {
+                error_count: s?.errorCount ?? -1,
+                warning_count: s?.warningCount ?? -1,
+                remote_reachable: s?.remoteReachable ?? false,
+                issue_codes: s?.issueCodes.join(",") ?? "",
+                top_messages: s ? JSON.stringify(s.topIssueMessages) : "",
+                remote_failure_reason: s?.remoteFailureReason ?? "",
+            });
+            // Also yell at the user on stderr so they can't miss it in their
+            // terminal. JSON mode: stderr too — the user/agent reading JSON
+            // output still sees stderr separately from the JSON envelope.
+            const summary_line = s
+                ? `--force used: bypassing ${s.errorCount} error(s) and ${s.warningCount} warning(s) from validate.` +
+                    (s.issueCodes.length
+                        ? ` Codes: ${s.issueCodes.join(", ")}.`
+                        : "") +
+                    (s.remoteReachable
+                        ? ""
+                        : ` Validate endpoint was unreachable (${s.remoteFailureReason ?? "unknown"}).`)
+                : "--force used: bypassing validation failure.";
+            stderrLog(`⚠️  ${summary_line}`);
+        }
+    }
+    else {
+        pushSpan.addEvent("preflight.validation_skipped");
+    }
+    if (!json)
+        log(_jsx(StatusLine, { kind: "info", label: "Pushing agent changes..." }));
+    else
+        stderrLog("Reading local files...");
+    const spinner = json ? null : startSpinner("Reading local files...");
+    const fileData = [];
+    try {
+        const files = await findAuiFiles(projectRoot);
+        for (const file of files) {
+            const parsed = parseAuiFile(file);
+            if (!parsed)
+                continue;
+            const relativePath = path.relative(projectRoot, file);
+            let type = "unknown";
+            const isToolPath = relativePath.startsWith("tools/") || relativePath.startsWith("tools\\");
+            // Cherry-picked from 7d3aa7c (master) on 2026-05-24.
+            // Recognize agent.aui.json by filename (not just by the wrapper
+            // key), mirroring `validate.tsx:222` which accepts both
+            //   { "general_settings": {...} }   (wrapped — `aui pull` writes this)
+            //   {...top-level fields...}        (flat — Agent Builder skills write this)
+            // Without this, a flat agent.aui.json fell through to type
+            // "unknown" and `buildPushTasks` never had a chance to emit a
+            // patch-general-settings task — same "silently dropped" class
+            // of bug the tool-modify branch had.
+            const isSettingsPath = relativePath === "agent.aui.json";
+            if (parsed.general_settings || isSettingsPath)
+                type = "general_settings";
+            else if (parsed.tool || isToolPath)
+                type = "tool";
+            else if (parsed.parameters)
+                type = "parameters";
+            else if (parsed.entities)
+                type = "entities";
+            else if (parsed.integrations)
+                type = "integrations";
+            else if (parsed.rules)
+                type = "rules";
+            fileData.push({ file: relativePath, type, data: parsed });
+        }
+        if (json)
+            stderrLog(`Read ${fileData.length} files`);
+        else
+            spinner.succeed(`Read ${fileData.length} files`);
+        const summary = {};
+        for (const fd of fileData) {
+            summary[fd.type] = (summary[fd.type] || 0) + 1;
+        }
+        const pushFiles = fileData.map((fd) => ({
+            file: fd.file,
+            type: fd.type,
+        }));
+        if (!json) {
+            log(_jsx(PushFileSummary, { agentCode: projectConfig.agent_code || projectConfig.agent_id, agentId: projectConfig.agent_id, files: pushFiles, summary: summary }));
+        }
+        // ─── Git-based change detection ───
+        const { getDiffSummary, getFileDiff, getItemLevelDiff: getItemDiff, hasOwnGitRepo, initAndCommitBaseline, commitBaseline, commitBaselineFiles, } = await import("../../utils/git.js");
+        if (!hasOwnGitRepo(projectRoot)) {
+            pushSpan.setAttribute("push.exit_reason", "baseline_initialized");
+            initAndCommitBaseline(projectRoot, "baseline: initialized from existing files");
+            if (json) {
+                outputJson({ dry_run: options.dryRun ?? false, baseline_initialized: true, has_changes: false });
+                return;
+            }
+            log(_jsx(Box, { paddingX: 1, children: _jsx(Hint, { message: "Baseline initialized. Run `aui push` again after making changes." }) }));
+            return;
+        }
+        const diff = hasOwnGitRepo(projectRoot)
+            ? getDiffSummary(projectRoot)
+            : null;
+        if (diff && !diff.hasChanges) {
+            pushSpan.setAttribute("push.exit_reason", "no_changes");
+            if (json) {
+                outputJson({ dry_run: options.dryRun ?? false, has_changes: false, changes: [] });
+                return;
+            }
+            log(_jsx(Box, { paddingX: 1, children: _jsx(StatusLine, { kind: "success", label: "No changes detected since last import/push." }) }));
+            return;
+        }
+        if (diff && !json) {
+            const changeFiles = diff.changedFiles.map((change) => {
+                const result = {
+                    file: change.file,
+                    status: change.status,
+                };
+                if ((change.status === "modified" || change.status === "added") &&
+                    !change.file.startsWith("knowledge-hubs/")) {
+                    const arrayFileInfo = getArrayFileInfoForPush(change.file, projectRoot);
+                    if (arrayFileInfo) {
+                        const itemChanges = getItemDiff(projectRoot, change.file, arrayFileInfo.arrayKey, arrayFileInfo.itemKey);
+                        if (itemChanges.length > 0) {
+                            result.itemChanges = itemChanges.map((item) => ({
+                                key: item.key,
+                                status: item.status,
+                                fieldChanges: item.fieldChanges,
+                            }));
+                        }
+                    }
+                    else if (change.status === "modified") {
+                        const fieldDiffs = getFileDiff(projectRoot, change.file);
+                        if (fieldDiffs.length > 0) {
+                            result.fieldDiffs = fieldDiffs;
+                        }
+                    }
+                }
+                return result;
+            });
+            log(_jsx(PushChangesView, { changes: changeFiles }));
+        }
+        if (options.dryRun) {
+            pushSpan.setAttribute("push.exit_reason", "dry_run");
+            if (isJsonMode()) {
+                outputJson({
+                    dry_run: true,
+                    agent: {
+                        code: projectConfig.agent_code || projectConfig.agent_id,
+                        id: projectConfig.agent_id,
+                    },
+                    files: pushFiles,
+                    summary,
+                    changes: diff
+                        ? diff.changedFiles.map((change) => {
+                            const result = {
+                                file: change.file,
+                                status: change.status,
+                            };
+                            if (change.status === "modified" || change.status === "added") {
+                                const arrayFileInfo = getArrayFileInfoForPush(change.file, projectRoot);
+                                if (arrayFileInfo) {
+                                    const itemChanges = getItemDiff(projectRoot, change.file, arrayFileInfo.arrayKey, arrayFileInfo.itemKey);
+                                    if (itemChanges.length > 0) {
+                                        result.item_changes = itemChanges;
+                                    }
+                                }
+                                else if (change.status === "modified") {
+                                    const fieldDiffs = getFileDiff(projectRoot, change.file);
+                                    if (fieldDiffs.length > 0) {
+                                        result.field_diffs = fieldDiffs;
+                                    }
+                                }
+                            }
+                            return result;
+                        })
+                        : [],
+                });
+                return;
+            }
+            log(_jsx(Box, { paddingX: 1, children: _jsx(StatusLine, { kind: "muted", label: "Dry run \u2014 no changes pushed." }) }));
+            return;
+        }
+        // ─── 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." }) }));
+            return;
+        }
+        const session = await getValidSession();
+        if (!session) {
+            throw new AuthenticationError("Session expired.");
+        }
+        // Use scope level from --scope-level flag, or from .auirc (saved during import)
+        const effectiveScopeLevel = options.scopeLevel ||
+            projectConfig.scope_level;
+        if (effectiveScopeLevel && effectiveScopeLevel !== "network") {
+            log(_jsx(StatusLine, { kind: "info", label: `Scope level: ${effectiveScopeLevel} (from ${options.scopeLevel ? "flag" : ".auirc"})` }));
+        }
+        const agentSettingsParams = await resolveAgentSettingsParams(config, projectConfig, session, projectRoot, effectiveScopeLevel);
+        const client = new AUIClient({
+            baseUrl: config.apiUrl,
+            authToken: config.authToken,
+            accountId: config.accountId,
+            organizationId: config.organizationId,
+            environment: config.environment,
+        });
+        const pushLogDir = path.join(projectRoot, ".aui", "push-logs");
+        fs.mkdirSync(pushLogDir, { recursive: true });
+        client.setPushLogDir(pushLogDir);
+        if (options.apiKey) {
+            saveAgentSettingsApiKey(options.apiKey);
+            client.setAgentSettingsApiKey(options.apiKey);
+        }
+        const savedApiKey = loadAgentSettingsApiKey();
+        if (savedApiKey && !options.apiKey) {
+            client.setAgentSettingsApiKey(savedApiKey);
+        }
+        // Version management: push is only allowed to draft versions.
+        // 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) {
+            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;
+            // Per a117251 (alboim): every agent-settings write body must carry the
+            // agent-management UUID. Setting it on `agentSettingsParams` here means
+            // every subsequent `client.<entity>` call funnels through `versionBody`
+            // and includes `agent_id` automatically.
+            agentSettingsParams.agent_id = prePushDraft.agentId;
+            pushSpan.setAttribute("push.version_id", prePushDraft.versionId);
+            pushSpan.setAttribute("push.version_label", prePushDraft.label);
+            pushSpan.setAttribute("push.agent_management_id", prePushDraft.agentId);
+            // Persist agent_management_id back to .auirc on first push so subsequent
+            // pushes skip the listAgents lookup. Mirrors what
+            // `resolvePushAgentManagementId` does in the legacy branch — keeps both
+            // paths converging on the same .auirc state. Non-fatal if the write
+            // fails (we already have the id in memory for this push).
+            if (!projectConfig.agent_management_id) {
+                try {
+                    saveProjectConfig({ ...projectConfig, agent_management_id: prePushDraft.agentId }, projectRoot);
+                    pushSpan.addEvent("auirc.agent_management_id_persisted_from_draft", {
+                        agent_management_id: prePushDraft.agentId,
+                    });
+                }
+                catch (err) {
+                    if (process.env.AUI_DEBUG) {
+                        console.warn("[debug] failed to persist agent_management_id back to .auirc:", err instanceof Error ? err.message : err);
+                    }
+                }
+            }
+        }
+        else {
+            // Legacy push (no version_id) — populate `agent_id` on write
+            // bodies when we can find one. `resolvePushAgentManagementId`
+            // returns `undefined` for pure-legacy agents that have no
+            // agent-management entry at all; in that case we leave
+            // `agentSettingsParams.agent_id` unset and the per-entity
+            // writes downstream fall back to scope-filter-only behaviour
+            // (which is how these agents pushed before agent-management
+            // existed). See the function's doc comment.
+            pushSpan.addEvent("preflight.no_draft_version_required", {
+                reason: "legacy push (no version_id in .auirc or --version-id flag)",
+            });
+            const legacyAgentId = await resolvePushAgentManagementId(config, projectConfig, session, projectRoot);
+            if (legacyAgentId) {
+                agentSettingsParams.agent_id = legacyAgentId;
+                pushSpan.setAttribute("push.agent_management_id", legacyAgentId);
+            }
+            else {
+                pushSpan.addEvent("preflight.pure_legacy_no_agent_management_id", {
+                    reason: "agent has no agent-management entry — per-entity writes will use scope filters only",
+                    network_id: projectConfig.agent_id ?? "(unknown)",
+                });
+                pushSpan.setAttribute("push.agent_management_id", "(pure_legacy)");
+            }
+        }
+        const pushTasks = buildPushTasks(diff, fileData, projectRoot, getFileDiff);
+        pushSpan.setAttribute("push.task_count", pushTasks.length);
+        if (diff) {
+            pushSpan.setAttribute("push.diff.added", diff.totalAdded);
+            pushSpan.setAttribute("push.diff.modified", diff.totalModified);
+            pushSpan.setAttribute("push.diff.deleted", diff.totalDeleted);
+        }
+        // pushKnowledgeHubs runs as a separate dependency-ordered step;
+        // short-circuiting on pushTasks alone would silently no-op
+        // KB-only pushes (e.g. user edited only `.csv.json` sidecars or
+        // `kb.json` manifest entries). Cherry-picked from d7d91ab on
+        // master (2026-05-24) — the bundle-mode equivalent lives in
+        // `commands/push.tsx` (where the bundle is always sent on any
+        // change, so the analog condition is implicit).
+        const hasKbChanges = diff?.changedFiles?.some((c) => c.file.startsWith("knowledge-hubs/")) ?? false;
+        if (pushTasks.length === 0 && !hasKbChanges) {
+            pushSpan.setAttribute("push.exit_reason", "no_pushable_tasks");
+            log(_jsx(Box, { paddingX: 1, children: _jsx(StatusLine, { kind: "success", label: "No pushable changes detected." }) }));
+            return;
+        }
+        if (pushTasks.length > 0) {
+            log(_jsx(Box, { paddingX: 1, children: _jsx(StatusLine, { kind: "info", label: `Pushing ${pushTasks.length} change(s)...` }) }));
+        }
+        let succeeded = 0;
+        let failed = 0;
+        let authFailed = false;
+        const succeededFiles = [];
+        const authFailedTasks = [];
+        const pushFailures = [];
+        const isAuthError = (err) => {
+            if (!(err instanceof Error))
+                return false;
+            const msg = err.message.toLowerCase();
+            const code = err.statusCode;
+            return (code === 401 ||
+                code === 403 ||
+                msg.includes("unauthorized") ||
+                msg.includes("forbidden") ||
+                msg.includes("not a member") ||
+                msg.includes("not member"));
+        };
+        const agentCodeStr = projectConfig.agent_code || projectConfig.agent_id || "unknown";
+        const agentIdStr = projectConfig.agent_id || "unknown";
+        /**
+         * 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 {
+                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)`;
+                        }
+                    }
+                    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;
+                        }
+                    }
+                    log(_jsx(Box, { paddingX: 2, children: _jsx(PushTaskLine, { result: taskResult }) }));
+                }
+                return stepFailed.length === 0 && !authFailed;
+            }
+            catch (err) {
+                // Don't swallow — a thrown error here means the loop body itself
+                // (not a per-task failure) blew up. Letting the original `} catch
+                // { return false; }` swallow it caused exit 0 with no telemetry.
+                throw err;
+            }
+        };
+        const paramTasks = pushTasks.filter((t) => t.type === "put-parameters" ||
+            t.type === "create-parameter" ||
+            t.type === "patch-parameter" ||
+            t.type === "delete-parameter");
+        const entityTasks = pushTasks.filter((t) => t.type === "put-entities" ||
+            t.type === "create-entity" ||
+            t.type === "patch-entity" ||
+            t.type === "delete-entity");
+        const integrationUpsertTasks = pushTasks.filter(isIntegrationUpsertTask);
+        const integrationDeleteTasks = pushTasks.filter((t) => t.type === "delete-integration");
+        const toolTasks = pushTasks.filter((t) => t.type === "patch-tool" ||
+            t.type === "create-tool" ||
+            t.type === "delete-tool");
+        const settingsTasks = pushTasks.filter((t) => t.type === "patch-general-settings");
+        const rulesTasks = pushTasks.filter((t) => t.type === "put-rules");
+        // ─── 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
+            // (`agent-builder-bff` E2B sandbox, CI, JSON mode being piped) the
+            // inquirer prompt would block forever waiting on stdin and the
+            // sandbox would eventually SIGTERM the process — exactly the silent
+            // failure mode users were hitting. Detect that up front
+            // and throw a structured AuthenticationError so handleError can
+            // print it, emit the JSON envelope, and exit non-zero.
+            const isInteractive = !json &&
+                process.stdin.isTTY === true &&
+                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([
+                {
+                    type: "password",
+                    name: "key",
+                    message: "Paste the Agent Settings API key (or press Enter to skip):",
+                    mask: "*",
+                },
+            ]);
+            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;
+                const retryTasks = [...authFailedTasks];
+                authFailedTasks.length = 0;
+                for (const task of retryTasks) {
+                    const retrySpinner = startSpinner(task.label);
+                    try {
+                        await executePushTask(client, agentSettingsParams, task);
+                        succeeded++;
+                        if (task.file)
+                            succeededFiles.push(task.file);
+                        retrySpinner.succeed(task.label);
+                    }
+                    catch (err) {
+                        failed++;
+                        const errMsg = err instanceof Error ? err.message : String(err);
+                        pushFailures.push({
+                            label: task.label,
+                            file: task.file,
+                            error: errMsg,
+                        });
+                        retrySpinner.fail(task.label);
+                        log(_jsx(ErrorDisplay, { error: err }));
+                    }
+                }
+            }
+            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",
+                }) }));
+        }
+        const logRelPath = path.relative(projectRoot, pushLogDir);
+        pushSpan.setAttribute("push.succeeded", succeeded);
+        pushSpan.setAttribute("push.failed", failed);
+        if (pushFailures.length > 0) {
+            pushSpan.setAttribute("push.failures", JSON.stringify(pushFailures));
+        }
+        // ─── Push Snapshot (last step — after entity push) ───
+        // The snapshot captures the local file state and uploads it as the
+        // source of truth for this push. Runs regardless of entity-push outcomes
+        // so the file history is preserved even on partial DB failures.
+        // Files = source of truth; DB updates are best-effort.
+        //
+        // IMPORTANT: snapshot failures must be loud — they are NOT counted in
+        // the entity `failed` counter, so without explicit surfacing here and
+        // a thrown CLIError at the end of `_push`, a snapshot failure would
+        // be hidden behind the "All N change(s) pushed successfully" summary
+        // and the process would exit 0.
+        // Retry policy: snapshot upload is the source-of-truth step; transient
+        // failures (network blips, 5xx, timeouts) are common with multipart
+        // uploads, so we retry up to 3 times with exponential backoff (1s, 2s,
+        // 4s) before giving up. 4xx responses are still retried — keeping the
+        // policy dumb here mirrors the single retry already in the api-client
+        // layer for entity pushes.
+        let snapshotSucceeded = false;
+        let snapshotError;
+        let snapshotAttempts = 0;
+        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
+                    ? "Pushing snapshot (file state)..."
+                    : `Retrying snapshot push (attempt ${attempt}/${SNAPSHOT_MAX_ATTEMPTS})...`;
+                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;
+                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 };
+                    }
+                    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
+                    ? `Snapshot push failed after ${attempt} attempt(s): ${attemptError}`
+                    : `Snapshot push failed (attempt ${attempt}/${SNAPSHOT_MAX_ATTEMPTS}): ${attemptError}`;
+                if (snapshotSpinner)
+                    snapshotSpinner.fail(failMsg);
+                else
+                    stderrLog(failMsg);
+                if (isLast)
+                    break;
+                const delayMs = SNAPSHOT_RETRY_BASE_MS * Math.pow(2, attempt - 1);
+                if (json)
+                    stderrLog(`Waiting ${delayMs}ms before retry...`);
+                await new Promise((resolve) => setTimeout(resolve, delayMs));
+            }
+            pushSpan.setAttribute("push.snapshot.success", snapshotSucceeded);
+            pushSpan.setAttribute("push.snapshot.attempts", snapshotAttempts);
+            if (!snapshotSucceeded && snapshotError) {
+                pushSpan.setAttribute("push.snapshot.error", snapshotError);
+            }
+        }
+        const snapshotStatus = prePushDraft
+            ? snapshotSucceeded
+                ? "succeeded"
+                : "failed"
+            : undefined;
+        const memoryPath = writePushMemory(projectRoot, agentCodeStr, agentIdStr, pushTasks, succeededFiles, pushFailures);
+        // ─── Baseline Update ───
+        // Only commit baseline if snapshot succeeded (or no draft = legacy mode).
+        // 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 (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."] })] })] }));
+        }
+        // ─── Snapshot result message ───
+        if (prePushDraft) {
+            if (!snapshotSucceeded) {
+                log(_jsxs(Box, { flexDirection: "column", paddingX: 1, children: [_jsx(StatusLine, { kind: "error", label: `Snapshot upload failed${snapshotError ? `: ${snapshotError}` : ""}` }), _jsxs(Box, { marginTop: 1, children: [_jsx(Text, { color: colors.info, bold: true, children: "What to do next: " }), _jsxs(Text, { color: colors.muted, children: ["Re-run ", _jsx(Text, { bold: true, children: "aui push" }), " to retry the snapshot. Your local files are the source of truth \u2014 they remain unchanged."] })] })] }));
+            }
+            else if (failed === 0) {
+                log(_jsx(StatusLine, { kind: "info", label: `All changes pushed into draft ${prePushDraft.label}. Run: aui version publish → aui version activate` }));
+            }
+            else {
+                log(_jsx(StatusLine, { kind: "warning", label: `Snapshot saved for draft ${prePushDraft.label}, but ${failed} DB update(s) failed. Re-run "aui push" to retry the DB updates before publishing.` }));
+            }
+        }
+        const snapshotFailed = snapshotStatus === "failed";
+        pushSpan.setAttribute("push.exit_reason", failed > 0
+            ? succeeded > 0
+                ? "partial_failure"
+                : "failed"
+            : snapshotFailed
+                ? "snapshot_failed"
+                : "completed");
+        pushSpan.setAttribute("push.succeeded_count", succeeded);
+        pushSpan.setAttribute("push.failed_count", failed);
+        // ─── Final structured JSON envelope (success path) ───
+        // The BFF / CI consumes --json output programmatically. On success we
+        // emit a single envelope at the very end so the caller can parse one
+        // top-level JSON document with the full push outcome. Failure paths
+        // are handled by handleError() via outputJsonError().
+        if (json && !snapshotFailed && failed === 0) {
+            outputJson({
+                agent: {
+                    code: agentCodeStr,
+                    id: agentIdStr,
+                },
+                version: prePushDraft
+                    ? { id: prePushDraft.versionId, label: prePushDraft.label }
+                    : undefined,
+                succeeded_count: succeeded,
+                failed_count: 0,
+                succeeded_files: succeededFiles,
+                snapshot: snapshotStatus
+                    ? {
+                        status: snapshotStatus,
+                        attempts: snapshotAttempts,
+                    }
+                    : undefined,
+                baseline_updated: baselineUpdated,
+                log_dir: logRelPath,
+                memory_path: memoryPath,
+            });
+        }
+        // ─── Failure throws (loud + non-zero exit + JSON error envelope) ───
+        // Snapshot failure takes priority because if the snapshot doesn't land
+        // the version's file history is incomplete, even when individual DB
+        // updates succeeded. Falls through to handleError() which prints the
+        // formatted error and exits non-zero.
+        if (snapshotFailed) {
+            throw new CLIError(`Snapshot upload failed${snapshotError ? `: ${snapshotError}` : ""}`, {
+                suggestion: "Re-run `aui push` to retry the snapshot. Your local files are the source of truth — they remain unchanged.",
+            });
+        }
+        // Entity-task partial / total failure. Without this throw, `aui push`
+        // would print "X failed" to stdout and exit 0 — the BFF would have no
+        // way to know the push didn't fully apply, and Logfire would record a
+        // "completed" span — a real reported failure mode.
+        if (failed > 0) {
+            const labels = pushFailures.map((f) => f.label).join(", ");
+            throw new CLIError(`${failed} entity push task(s) failed: ${labels}`, {
+                suggestion: succeeded > 0
+                    ? `${succeeded} change(s) were saved. Fix the errors above and re-run \`aui push\` to retry the rest.`
+                    : "Fix the errors above and re-run `aui push`.",
+            });
+        }
+    }
+    catch (error) {
+        if (spinner)
+            spinner.fail("Push failed");
+        // CLIErrors carry actionable info and a meaningful exit code — let
+        // handleError() format them and exit non-zero. Without this re-throw
+        // a snapshot-failure CLIError thrown above would be swallowed in TUI
+        // mode and the process would exit 0.
+        if (error instanceof CLIError) {
+            throw error;
+        }
+        if (!json)
+            log(_jsx(ErrorDisplay, { error: error }));
+        else
+            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) {
+    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);
+    let agentInfo;
+    const errors = [];
+    const agentMgmtId = session.agent_management_id;
+    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.`);
+            }
+        }
+        catch (err) {
+            // Accumulate into `errors` so the eventual ConfigError can list every
+            // resolution path that failed (alboim's a117251). Also emit AUI_DEBUG
+            // warning for live operator observability (zero silent errors policy).
+            errors.push(`listAgents(network_id=${projectNetworkId}) threw: ${err instanceof Error ? err.message : String(err)}`);
+            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) {
+        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) {
+        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.`);
+            }
+        }
+        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`.
+ */
+/**
+ * Returns the agent_management_id for the push call's `agent_id` query
+ * param, or `undefined` for pure-legacy agents that predate
+ * agent-management entirely.
+ *
+ * Pure-legacy semantics (2026-05-26): if neither `.auirc` nor
+ * `lookupAgentManagementInfoForPush` can find an agent_management_id,
+ * the agent existed in `networks` before agent-management was even a
+ * thing. The per-entity write endpoints (`POST /v1/parameters/view`,
+ * etc.) accept these via scope filters alone (network_id + account_id
+ * + organization_id + network_category_id) — that's how the CLI
+ * pushed to them historically. `versionBody()` in the API client
+ * only emits the `agent_id` query param when `params.agent_id` is
+ * truthy, so returning `undefined` here cleanly degrades to the
+ * scope-filter path.
+ *
+ * Sibling of the same fix in `push.tsx` (pre-flight short-circuit)
+ * and `pull-agent.tsx` (records-mode dispatch when no
+ * agent_management_id) — keep all three in lock-step.
+ */
+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) {
+        // Pure-legacy agent — no agent_management_id anywhere. Return
+        // undefined; the per-entity writes downstream will use scope
+        // filters only (network_id + account_id + organization_id +
+        // network_category_id from `.auirc`). Log the errors at debug
+        // for triage but don't bail — pre-agent-management agents
+        // pushed this way for years before bundle_mode existed.
+        if (process.env.AUI_DEBUG && errors.length > 0) {
+            console.log(`[debug] resolvePushAgentManagementId: no agent_management_id found, falling back to scope-filter-only writes. Lookup errors:\n  - ${errors.join("\n  - ")}`);
+        }
+        return undefined;
+    }
+    // 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}`, {
+            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;
+        try {
+            ver = await client.agentManagement.getVersion(agentInfo.id, explicitVersionId);
+        }
+        catch (error) {
+            throw new CLIError(`Could not fetch version "${explicitVersionId}": ${error instanceof Error ? error.message : String(error)}`, {
+                suggestion: "Check the version ID with `aui version list` and try again.",
+                cause: error,
+            });
+        }
+        if (ver.status !== "draft") {
+            throw new ValidationError(`Version v${ver.version_number} is "${ver.status}" — you can only push to a draft version.`, {
+                suggestion: "Create a new draft with `aui version create`, then push with `aui push --version-id <new-draft-id>`.",
+            });
+        }
+        const label = `v${ver.version_number}`;
+        return { versionId: ver.id, label, agentId: agentInfo.id };
+    }
+    // Resolve from .auirc version_id or auto-detect drafts
+    let allVersions = [];
+    try {
+        const versionsResp = await client.agentManagement.listVersions(agentInfo.id, 1, 50);
+        allVersions = versionsResp.items;
+    }
+    catch (error) {
+        throw new CLIError("Could not fetch versions for this agent.", {
+            suggestion: "Check your connection and try again. Use `aui version list` to debug.",
+            cause: error,
+        });
+    }
+    // If .auirc has a version_id, validate it's still a draft
+    if (projectConfig.version_id) {
+        const configVersion = allVersions.find((v) => v.id === projectConfig.version_id);
+        if (configVersion) {
+            if (configVersion.status !== "draft") {
+                throw new ValidationError(`The version in your .auirc (v${configVersion.version_number}) is "${configVersion.status}" — you can only push to a draft version.`, {
+                    suggestion: "Create a new draft (`aui version create`), import it (`aui import-agent --version <new-draft-id>`), then `aui push`.",
+                });
+            }
+            const label = `v${configVersion.version_number}`;
+            return { versionId: configVersion.id, label, agentId: agentInfo.id };
+        }
+    }
+    // Auto-detect drafts
+    const drafts = allVersions.filter((v) => v.status === "draft");
+    if (drafts.length === 0) {
+        throw new ValidationError("No draft version found — you can only push to a draft version.", {
+            suggestion: "Create a new draft (`aui version create`), import it (`aui import-agent --version <draft-id>`), then `aui push`.",
+        });
+    }
+    if (drafts.length === 1) {
+        const draft = drafts[0];
+        const label = `v${draft.version_number}`;
+        return { versionId: draft.id, label, agentId: agentInfo.id };
+    }
+    // Multiple drafts — auto-pick the latest (drafts are sorted DESC by created_at)
+    // No interactive prompt: keeps `aui push` non-blocking. Use --version-id to
+    // explicitly target a different draft.
+    const latest = drafts[0];
+    const latestLabel = `v${latest.version_number}`;
+    if (!isJsonMode()) {
+        log(_jsxs(Box, { flexDirection: "column", paddingX: 1, children: [_jsx(StatusLine, { kind: "info", label: `${drafts.length} drafts found — auto-selecting latest: ${latestLabel}` }), _jsxs(Text, { color: colors.muted, children: ["  Tip: pass ", _jsxs(Text, { bold: true, children: ["--version-id ", '<id>'] }), " to target a specific draft."] })] }));
+    }
+    return { versionId: latest.id, label: latestLabel, agentId: agentInfo.id };
+}
+/**
+ * Push a snapshot of all local agent files to the server via multipart upload.
+ * This captures the current state of the files to maintain version history.
+ * Version bump happens automatically on the server when snapshot succeeds.
+ *
+ * If any files fail, the user must re-run `aui push` to retry.
+ */
+async function pushSnapshot(client, agentId, versionId, projectRoot, fileData) {
+    const filesToUpload = [];
+    for (const fd of fileData) {
+        const fullPath = path.join(projectRoot, fd.file);
+        if (!fs.existsSync(fullPath))
+            continue;
+        const content = fs.readFileSync(fullPath);
+        filesToUpload.push({
+            filePath: fullPath,
+            fileName: path.basename(fd.file),
+            content,
+        });
+    }
+    if (filesToUpload.length === 0) {
+        return { success: true, failed: [] };
+    }
+    // 2026-05-24 — the legacy multipart /push endpoint was retired when
+    // the server moved to JSON bundles. For records-mode (legacy) agents
+    // the per-entity DB writes ARE the canonical state; there's no
+    // separate "snapshot" to upload anymore. Returning a synthetic
+    // success keeps the rest of the legacy pipeline's bookkeeping
+    // (succeededFiles, push memory, exit code) intact.
+    //
+    // Variables silenced so eslint/tsc don't flag them as unused — they
+    // still feed structured logging if the call site adds debug output
+    // before this no-op.
+    void client;
+    void agentId;
+    void versionId;
+    return { success: true, failed: [] };
+}
+// ─── Agent Settings Params Resolution ───
+async function resolveAgentSettingsParams(config, projectConfig, session, projectRoot, scopeLevel) {
+    // Throws ConfigError on any missing config field — never returns null.
+    // See note on resolveVersionDraft for why silent returns are forbidden.
+    const networkId = projectConfig.agent_id || session.network_id;
+    const accountId = projectConfig.account_id || config.accountId;
+    const organizationId = projectConfig.organization_id || config.organizationId;
+    const userId = session.user_id;
+    if (!networkId || !accountId || !organizationId) {
+        const missing = [];
+        if (!networkId)
+            missing.push("network_id (agent_id in .auirc)");
+        if (!accountId)
+            missing.push("account_id (in .auirc or session)");
+        if (!organizationId)
+            missing.push("organization_id (in .auirc or session)");
+        throw new ConfigError(`Missing: ${missing.join(", ")}`, {
+            suggestion: "Re-import the agent (`aui import`) or re-login (`aui login`).",
+        });
+    }
+    let categoryId = projectConfig.network_category_id;
+    if (!categoryId) {
+        try {
+            const client = new AUIClient({
+                baseUrl: config.apiUrl,
+                authToken: config.authToken,
+                accountId,
+                organizationId,
+                environment: config.environment,
+            });
+            const resp = (await client.networks.get(networkId));
+            const cat = resp?.data?.category;
+            if (cat) {
+                categoryId = typeof cat === "string" ? cat : cat._id;
+                saveProjectConfig({ ...projectConfig, network_category_id: categoryId }, projectRoot);
+            }
+        }
+        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) {
+        throw new ConfigError("Missing network_category_id.", {
+            suggestion: "Re-import the agent (`aui import`) to fix.",
+        });
+    }
+    const baseParams = {
+        updated_by: userId,
+        network_id: networkId,
+        account_id: accountId,
+        organization_id: organizationId,
+        network_category_id: categoryId,
+    };
+    if (scopeLevel && scopeLevel !== "network") {
+        const scoped = applyScopeLevel({
+            network_id: networkId,
+            account_id: accountId,
+            organization_id: organizationId,
+            network_category_id: categoryId,
+        }, scopeLevel);
+        if (process.env.AUI_DEBUG) {
+            console.log(`[debug] push scope params: ${JSON.stringify(scoped)}`);
+        }
+        return {
+            updated_by: userId,
+            network_id: scoped.network_id ?? "",
+            account_id: scoped.account_id ?? "",
+            organization_id: scoped.organization_id ?? "",
+            network_category_id: scoped.network_category_id ?? "",
+        };
+    }
+    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);
+                    await setUserContext(span);
+                    await setAgentContext(span, {
+                        agentId: projectConfig.agent_management_id,
+                        agentCode: projectConfig.agent_code,
+                        versionId: projectConfig.version_id,
+                        versionLabel: projectConfig.version_label,
+                        networkId: kbNetworkId,
+                        accountId: projectConfig.account_id,
+                        organizationId: projectConfig.organization_id,
+                        networkCategoryId: projectConfig.network_category_id,
+                    });
+                    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);
+                        await setUserContext(span);
+                        await setAgentContext(span, {
+                            agentId: projectConfig.agent_management_id,
+                            agentCode: projectConfig.agent_code,
+                            versionId: projectConfig.version_id,
+                            versionLabel: projectConfig.version_label,
+                            networkId: kbNetworkId,
+                            accountId: projectConfig.account_id,
+                            organizationId: projectConfig.organization_id,
+                            networkCategoryId: projectConfig.network_category_id,
+                        });
+                        try {
+                            const importResult = await kbViewClient.importFiles({
+                                files: supportedFiles,
+                                scope,
+                                created_by: userId,
+                                knowledge_base_name: kbData.name,
+                                knowledge_base_description: kbData.description ?? undefined,
+                            });
+                            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();
+                        }
+                    });
+                }
+                // importFiles ingests binaries only; sidecar edits + non-file
+                // Resources reach the server through importJson. After
+                // importFiles so binary re-extracts don't clobber manifest
+                // edits. Cherry-picked from d7d91ab — this is the
+                // records-mode mirror of the same block in
+                // `commands/push.tsx`'s `pushKnowledgeHubs`. KB push is
+                // mode-agnostic but each push pipeline carries its own copy
+                // because they have different surrounding bookkeeping
+                // (`failures` array shape, telemetry context wiring).
+                const hasJsonPayload = kbData.tabular_files.length > 0 || kbData.markdown_files.length > 0;
+                if (hasJsonPayload) {
+                    const kbJsonTracer = getTracer();
+                    await kbJsonTracer.startActiveSpan("aui.push.task.kb-import-json", async (span) => {
+                        span.setAttribute("push.task.type", "kb-import-json");
+                        span.setAttribute("push.task.label", `Sync knowledge base manifest: ${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.tabular_count", kbData.tabular_files.length);
+                        span.setAttribute("push.task.markdown_count", kbData.markdown_files.length);
+                        await setUserContext(span);
+                        await setAgentContext(span, {
+                            agentId: projectConfig.agent_management_id,
+                            agentCode: projectConfig.agent_code,
+                            versionId: projectConfig.version_id,
+                            versionLabel: projectConfig.version_label,
+                            networkId: kbNetworkId,
+                            accountId: projectConfig.account_id,
+                            organizationId: projectConfig.organization_id,
+                            networkCategoryId: projectConfig.network_category_id,
+                        });
+                        try {
+                            await kbViewClient.importJson({
+                                scope,
+                                knowledge_bases: [
+                                    {
+                                        name: kbData.name,
+                                        description: kbData.description,
+                                        tabular_files: kbData.tabular_files,
+                                        markdown_files: kbData.markdown_files,
+                                    },
+                                ],
+                                created_by: userId,
+                                network_id: scope.network_id,
+                            });
+                            span.setStatus({ code: SpanStatusCode.OK });
+                        }
+                        catch (importErr) {
+                            hadUploadFailure = true;
+                            const errMsg = importErr instanceof Error
+                                ? importErr.message
+                                : String(importErr);
+                            span.setStatus({ code: SpanStatusCode.ERROR, message: errMsg });
+                            span.recordException(importErr instanceof Error ? importErr : new Error(errMsg));
+                            span.setAttribute("push.task.error", errMsg);
+                            if (importErr.statusCode) {
+                                span.setAttribute("push.task.error_status_code", importErr.statusCode);
+                            }
+                            failures.push({
+                                label: `Sync knowledge base manifest: ${kbData.name || kbDirName}`,
+                                file: `knowledge-hubs/${kbDirName}/kb.json`,
+                                error: errMsg,
+                            });
+                            log(_jsx(Box, { paddingX: 1, children: _jsx(StatusLine, { kind: "error", label: `Failed to sync manifest for "${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 {
+        const fullPath = path.join(dir, filePath);
+        if (!fs.existsSync(fullPath))
+            return null;
+        const content = JSON.parse(fs.readFileSync(fullPath, "utf-8"));
+        const isToolPath = filePath.startsWith("tools/") || filePath.startsWith("tools\\");
+        if (content.tool || isToolPath)
+            return null;
+        if (content.parameters)
+            return { arrayKey: "parameters", itemKey: "code", label: "Parameters" };
+        if (content.entities)
+            return { arrayKey: "entities", itemKey: "name", label: "Entities" };
+        if (content.integrations)
+            return {
+                arrayKey: "integrations",
+                itemKey: "code",
+                label: "Integrations",
+            };
+        if (content.rules)
+            return { arrayKey: "rules", itemKey: "code", label: "Rules" };
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function writePushMemory(projectRoot, agentCode, agentId, pushTasks, succeededFiles, pushFailures) {
+    try {
+        const memoryDir = path.join(projectRoot, "memory");
+        fs.mkdirSync(memoryDir, { recursive: true });
+        const now = new Date();
+        const timestamp = now.toISOString().replace(/[:.]/g, "-");
+        const dateStr = now.toISOString().replace("T", " ").substring(0, 19);
+        const filename = `push-${timestamp}.md`;
+        const succeededSet = new Set(succeededFiles);
+        const failureMap = new Map();
+        for (const f of pushFailures) {
+            failureMap.set(f.label, f.error);
+        }
+        const totalSucceeded = pushTasks.filter((t) => (t.file && succeededSet.has(t.file)) ||
+            (!t.file && !failureMap.has(t.label))).length;
+        const totalFailed = pushFailures.length;
+        const overallStatus = totalFailed === 0 ? "SUCCESS" : totalSucceeded > 0 ? "PARTIAL" : "FAILED";
+        const lines = [
+            `# Push ${dateStr}`,
+            "",
+            `**Agent:** ${agentCode}`,
+            `**Agent ID:** ${agentId}`,
+            `**Status:** ${overallStatus}`,
+            `**Total:** ${totalSucceeded} succeeded, ${totalFailed} failed`,
+            "",
+            "## Changes",
+            "",
+        ];
+        const tasksByCategory = {};
+        for (const task of pushTasks) {
+            const category = task.type.split("-").slice(1).join(" ");
+            if (!tasksByCategory[category])
+                tasksByCategory[category] = [];
+            tasksByCategory[category].push(task);
+        }
+        for (const [category, tasks] of Object.entries(tasksByCategory)) {
+            lines.push(`### ${category.charAt(0).toUpperCase() + category.slice(1)}`);
+            lines.push("");
+            for (const task of tasks) {
+                const isFailed = failureMap.has(task.label);
+                const status = isFailed ? "FAILED" : "OK";
+                const icon = isFailed ? "x" : "check";
+                const action = task.type.split("-")[0];
+                lines.push(`- :${icon}: **${task.label}** — ${status}`);
+                if (task.file) {
+                    lines.push(`  - File: \`${task.file}\``);
+                }
+                if (isFailed) {
+                    lines.push(`  - Error: ${failureMap.get(task.label)}`);
+                }
+                if (action === "delete") {
+                    lines.push(`  - Action: Deleted`);
+                }
+                else if (action === "create" || !task.oldBody) {
+                    lines.push(`  - Action: Created`);
+                    lines.push(`  - Body:`);
+                    lines.push("  ```json");
+                    lines.push(`  ${JSON.stringify(task.body, null, 2).split("\n").join("\n  ")}`);
+                    lines.push("  ```");
+                }
+                else {
+                    const fieldDiffs = diffObjects(task.oldBody, task.body);
+                    if (fieldDiffs.length > 0) {
+                        lines.push(`  - Action: Modified`);
+                        lines.push(`  - Diff:`);
+                        for (const fd of fieldDiffs) {
+                            if (fd.type === "added") {
+                                lines.push(`    - **+ ${fd.path}**: \`${truncate(fd.newValue)}\``);
+                            }
+                            else if (fd.type === "removed") {
+                                lines.push(`    - **- ${fd.path}**: ~~\`${truncate(fd.oldValue)}\`~~`);
+                            }
+                            else {
+                                lines.push(`    - **~ ${fd.path}**: \`${truncate(fd.oldValue)}\` → \`${truncate(fd.newValue)}\``);
+                            }
+                        }
+                    }
+                    else {
+                        lines.push(`  - Action: Modified (no field-level diff detected)`);
+                    }
+                }
+                lines.push("");
+            }
+            lines.push("");
+        }
+        const filePath = path.join(memoryDir, filename);
+        fs.writeFileSync(filePath, lines.join("\n"), "utf-8");
+        return path.relative(projectRoot, filePath);
+    }
+    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;
+    }
+}
+function truncate(value, maxLen = 120) {
+    const str = typeof value === "string" ? value : JSON.stringify(value);
+    if (!str)
+        return "(empty)";
+    return str.length > maxLen ? str.substring(0, maxLen) + "..." : str;
+}
+function diffObjects(oldObj, newObj, prefix = "") {
+    const diffs = [];
+    const allKeys = new Set([
+        ...Object.keys(oldObj || {}),
+        ...Object.keys(newObj || {}),
+    ]);
+    for (const key of Array.from(allKeys)) {
+        const p = prefix ? `${prefix}.${key}` : key;
+        const oldVal = oldObj?.[key];
+        const newVal = newObj?.[key];
+        if (oldVal === undefined && newVal !== undefined) {
+            diffs.push({ path: p, type: "added", newValue: newVal });
+        }
+        else if (oldVal !== undefined && newVal === undefined) {
+            diffs.push({ path: p, type: "removed", oldValue: oldVal });
+        }
+        else if (oldVal !== null &&
+            newVal !== null &&
+            typeof oldVal === "object" &&
+            typeof newVal === "object" &&
+            !Array.isArray(oldVal) &&
+            !Array.isArray(newVal)) {
+            diffs.push(...diffObjects(oldVal, newVal, p));
+        }
+        else if (JSON.stringify(oldVal) !== JSON.stringify(newVal)) {
+            diffs.push({
+                path: p,
+                type: "changed",
+                oldValue: oldVal,
+                newValue: newVal,
+            });
+        }
+    }
+    return diffs;
+}
+/**
+ * Build the ordered list of API tasks the legacy push will execute,
+ * given a git diff summary, the parsed file contents, and an
+ * injectable per-file diff function.
+ *
+ * `getFileDiffFn` is parameterized so tests can stub out `git show`
+ * without a real git repo. `getItemLevelDiffFn` is optional and
+ * defaults to the production implementation; tests inject it so the
+ * array-keyed branches (parameters, entities, integrations) are
+ * exercisable without git too.
+ *
+ * Exported for unit-test access only — production callers should keep
+ * going through `_push` in this module, which threads in the real
+ * `getFileDiff` and `getItemLevelDiff` from `../../utils/git.js`.
+ *
+ * Cherry-picked from master commit 53a6024 on 2026-05-24. The
+ * underlying bug fixes (always push patch-tool on modify; accept
+ * flat-shape general-settings on add) are inlined below.
+ */
+export function buildPushTasks(diff, fileData, projectRoot, getFileDiffFn, getItemLevelDiffFn) {
+    const getItems = getItemLevelDiffFn ?? getItemLevelDiff;
+    const tasks = [];
+    for (const change of diff.changedFiles) {
+        if (change.status === "deleted") {
+            const isToolFile = change.file.includes("tools/") && change.file.endsWith(".aui.json");
+            if (isToolFile) {
+                const basename = change.file.split("/").pop().replace(".aui.json", "");
+                const toolName = basename.toUpperCase().replace(/-/g, "_");
+                tasks.push({
+                    type: "delete-tool",
+                    label: `Delete tool: ${toolName}`,
+                    toolName,
+                    file: change.file,
+                    body: {},
+                });
+            }
+            continue;
+        }
+        const fd = fileData.find((f) => f.file === change.file ||
+            change.file.endsWith("/" + f.file) ||
+            f.file.endsWith("/" + change.file));
+        if (!fd)
+            continue;
+        if (fd.type === "tool") {
+            const toolData = fd.data?.tool || fd.data;
+            if (!toolData || !toolData.code)
+                continue;
+            const toolCode = toolData.code || "";
+            const toolName = toolCode.toUpperCase().replace(/-/g, "_");
+            if (change.status === "added") {
+                tasks.push({
+                    type: "create-tool",
+                    label: `Create tool: ${toolCode}`,
+                    file: change.file,
+                    body: toolData,
+                });
+            }
+            else if (change.status === "modified") {
+                // `change.status === "modified"` comes from `getDiffSummary`
+                // (git status). That alone is the source of truth that the
+                // file content diverged from the baseline; always push the
+                // patch. The full `toolData` body is sent (consistent with
+                // the create-tool branch immediately above); the platform
+                // PATCH is idempotent for fields whose value didn't actually
+                // change, so this is safe.
+                //
+                // Pre-fix (cherry-picked from 53a6024 on 2026-05-24) this
+                // branch routed the changes through a `buildToolPatchBody`
+                // gate that only matched diff paths starting with the
+                // wrapped-shape `tool.` prefix. Tool files written in flat
+                // shape (no `{ "tool": {...} }` wrapper — accepted by the
+                // loader above and by `aui validate`) diffed to top-level
+                // paths (`response_type`, `widget`, `goal`, …), the gate
+                // returned an empty body, and the `patch-tool` task was
+                // silently dropped. Symptom: `aui diff` showed the change,
+                // `aui push` printed "No pushable changes detected" and
+                // exited 0.
+                tasks.push({
+                    type: "patch-tool",
+                    label: `Update tool: ${toolCode}`,
+                    toolName,
+                    file: change.file,
+                    body: toolData,
+                });
+            }
+        }
+        else if (fd.type === "general_settings") {
+            if (change.status === "modified") {
+                const fieldDiffs = getFileDiffFn(projectRoot, change.file);
+                const patchBody = buildSettingsPatchBody(fieldDiffs);
+                if (Object.keys(patchBody).length > 0) {
+                    tasks.push({
+                        type: "patch-general-settings",
+                        label: "Update general settings",
+                        file: change.file,
+                        body: patchBody,
+                    });
+                }
+            }
+            else if (change.status === "added") {
+                // Mirror the tool loader's `(fd.data as any)?.tool || fd.data`
+                // tolerance: accept both `{ "general_settings": {...} }`
+                // (wrapped) and `{...}` (flat). `normalizeGeneralSettings` in
+                // `pull-agent.tsx` / `import-agent.tsx` and `aui validate`
+                // (`commands/validate.tsx:222`) already permit both layouts —
+                // staying in lockstep with them here prevents the same
+                // "silently dropped" class of bug the tool-modify branch had.
+                // Cherry-picked from 53a6024 on 2026-05-24.
+                const settings = fd.data?.general_settings ?? fd.data;
+                if (settings) {
+                    tasks.push({
+                        type: "patch-general-settings",
+                        label: "Update general settings",
+                        file: change.file,
+                        body: settings,
+                    });
+                }
+            }
+        }
+        else if (fd.type === "parameters") {
+            const itemDiffs = getItems(projectRoot, change.file, "parameters", "code");
+            for (const item of itemDiffs) {
+                if (item.status === "added") {
+                    tasks.push({
+                        type: "create-parameter",
+                        label: `Create parameter: ${item.key}`,
+                        file: change.file,
+                        body: item.newItem,
+                        itemCode: item.key,
+                    });
+                }
+                else if (item.status === "modified") {
+                    tasks.push({
+                        type: "patch-parameter",
+                        label: `Update parameter: ${item.key}`,
+                        file: change.file,
+                        body: item.newItem,
+                        itemCode: item.key,
+                    });
+                }
+                else if (item.status === "deleted") {
+                    tasks.push({
+                        type: "delete-parameter",
+                        label: `Delete parameter: ${item.key}`,
+                        file: change.file,
+                        body: item.oldItem,
+                        itemCode: item.key,
+                    });
+                }
+            }
+        }
+        else if (fd.type === "entities") {
+            const itemDiffs = getItems(projectRoot, change.file, "entities", "name");
+            for (const item of itemDiffs) {
+                if (item.status === "added") {
+                    tasks.push({
+                        type: "create-entity",
+                        label: `Create entity: ${item.key}`,
+                        file: change.file,
+                        body: item.newItem,
+                        itemCode: item.key,
+                    });
+                }
+                else if (item.status === "modified") {
+                    tasks.push({
+                        type: "patch-entity",
+                        label: `Update entity: ${item.key}`,
+                        file: change.file,
+                        body: item.newItem,
+                        itemCode: item.key,
+                    });
+                }
+                else if (item.status === "deleted") {
+                    tasks.push({
+                        type: "delete-entity",
+                        label: `Delete entity: ${item.key}`,
+                        file: change.file,
+                        body: item.oldItem,
+                        itemCode: item.key,
+                    });
+                }
+            }
+        }
+        else if (fd.type === "integrations") {
+            const itemDiffs = getItems(projectRoot, change.file, "integrations", "code");
+            for (const item of itemDiffs) {
+                if (item.status === "added") {
+                    tasks.push({
+                        type: "create-integration",
+                        label: `Create integration: ${item.key}`,
+                        file: change.file,
+                        body: item.newItem,
+                        itemCode: item.key,
+                    });
+                }
+                else if (item.status === "modified") {
+                    tasks.push({
+                        type: "patch-integration",
+                        label: `Update integration: ${item.key}`,
+                        file: change.file,
+                        body: item.newItem,
+                        itemCode: item.key,
+                    });
+                }
+                else if (item.status === "deleted") {
+                    tasks.push({
+                        type: "delete-integration",
+                        label: `Delete integration: ${item.key}`,
+                        file: change.file,
+                        body: item.oldItem,
+                        itemCode: item.key,
+                    });
+                }
+            }
+        }
+        else if (fd.type === "rules") {
+            const rulesData = fd.data;
+            tasks.push({
+                type: "put-rules",
+                label: "Update rules",
+                file: change.file,
+                body: rulesData,
+            });
+        }
+    }
+    return tasks;
+}
+function buildToolPatchBody(fieldDiffs) {
+    const body = {};
+    for (const fd of fieldDiffs) {
+        if (fd.operation === "removed")
+            continue;
+        const parts = fd.path.split(".");
+        if (parts[0] === "tool" && parts.length >= 2) {
+            const topLevelKey = parts[1];
+            body[topLevelKey] = fd.newValue;
+        }
+    }
+    return body;
+}
+// Exported as of 2026-05-24 (cherry-pick of 53a6024) for unit-test
+// access from `__tests__/push-build-tasks.test.ts`.
+export function buildSettingsPatchBody(fieldDiffs) {
+    const body = {};
+    for (const fd of fieldDiffs) {
+        if (fd.operation === "removed")
+            continue;
+        const parts = fd.path.split(".");
+        if (parts.length === 0 || !parts[0])
+            continue;
+        // general_settings (agent.aui.json) files come in two
+        // equally-supported shapes:
+        //   wrapped: { "general_settings": { ...fields... } } → paths look
+        //            like `general_settings.<field>...`
+        //   flat:    { ...fields... }                          → paths look
+        //            like `<field>...`
+        // `aui validate` (`commands/validate.tsx:222`) and
+        // `normalizeGeneralSettings` in `import-agent.tsx` /
+        // `pull-agent.tsx` already accept both layouts. Pre-fix this
+        // body builder only matched the wrapped form, which silently
+        // dropped edits to flat-shape files. Match the loader behaviour
+        // here so every change reaches the platform. Cherry-picked from
+        // 53a6024 on 2026-05-24.
+        const topLevelKey = parts[0] === "general_settings" && parts.length >= 2
+            ? parts[1]
+            : parts[0];
+        body[topLevelKey] = fd.newValue;
+    }
+    return body;
+}
+// ─── Push Task Executor ───
+async function executePushTask(client, params, task) {
+    const tracer = getTracer();
+    return tracer.startActiveSpan(`aui.push.task.${task.type}`, async (span) => {
+        span.setAttribute("push.task.type", task.type);
+        span.setAttribute("push.task.label", task.label);
+        if (task.file)
+            span.setAttribute("push.task.file", task.file);
+        if (task.toolName)
+            span.setAttribute("push.task.tool_name", task.toolName);
+        if (task.itemCode)
+            span.setAttribute("push.task.item_code", task.itemCode);
+        // Tag every task span with who ran it and which agent/version/scope
+        // it targeted. The parent `aui.push` span already has these, but the
+        // Logfire row view doesn't carry parent attrs onto children — so a
+        // 500 on `aui.push.task.patch-tool` needs them attached locally for
+        // a triage glance to be self-sufficient. Identifiers only — no
+        // tokens. See `setAgentContext` JSDoc for the safety rationale.
+        await setUserContext(span);
+        await setAgentContext(span, {
+            agentId: params.agent_id,
+            versionId: params.version_id,
+            networkId: params.network_id,
+            accountId: params.account_id,
+            organizationId: params.organization_id,
+            networkCategoryId: params.network_category_id,
+        });
+        try {
+            span.setAttribute("push.task.request_payload", JSON.stringify(task.body));
+            const result = await _executePushTask(client, params, task);
+            span.setAttribute("push.task.response", JSON.stringify(result));
+            span.setStatus({ code: SpanStatusCode.OK });
+            return result;
+        }
+        catch (error) {
+            const errMsg = error instanceof Error ? error.message : String(error);
+            span.setStatus({ code: SpanStatusCode.ERROR, message: errMsg });
+            span.recordException(error instanceof Error ? error : new Error(errMsg));
+            span.setAttribute("push.task.error", errMsg);
+            if (error.statusCode)
+                span.setAttribute("push.task.error_status_code", error.statusCode);
+            if (error.responseBody)
+                span.setAttribute("push.task.error_response", JSON.stringify(error.responseBody));
+            throw error;
+        }
+        finally {
+            span.end();
+        }
+    });
+}
+// ─── 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 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 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 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);
+                    }
+                    throw err;
+                }
+            });
+        case "create-tool":
+            return withTransientRetry(`POST tool ${task.toolName ?? task.itemCode}`, async () => {
+                try {
+                    return await client.createTool(params, task.body);
+                }
+                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 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 withTransientRetry("PATCH general-settings", () => client.patchGeneralSettings(params, task.body));
+        case "put-parameters":
+            return withTransientRetry("PUT parameters", () => client.putParameters(params, task.body, task.oldBody));
+        case "put-entities":
+            return withTransientRetry("PUT entities", () => client.putEntities(params, task.body, task.oldBody));
+        case "put-integrations":
+            return withTransientRetry("PUT integrations", () => client.putIntegrations(params, task.body, task.oldBody));
+        case "create-parameter":
+            return withTransientRetry(`POST param ${task.itemCode}`, async () => {
+                try {
+                    return await client.createParameter(params, task.body);
+                }
+                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 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 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":
+            return withTransientRetry(`POST entity ${task.itemCode}`, async () => {
+                try {
+                    return await client.createEntity(params, task.body);
+                }
+                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 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 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":
+            return withTransientRetry(`POST integration ${task.itemCode}`, async () => {
+                try {
+                    return await client.createIntegration(params, task.body);
+                }
+                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 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 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 withTransientRetry("PUT rules", () => client.putRules(params, task.body));
+        default:
+            throw new Error(`Unknown push task type: ${task.type}`);
+    }
+}
+//# sourceMappingURL=push-records-mode.js.map