aui-agent-builder 0.3.103 → 0.3.105

package/dist/commands/push.js

@@ -3,20 +3,18 @@ import * as fs from "fs";
 import * as path from "path";
 import { render } from "ink";
 import { Box, Text } from "ink";
-import inquirer from "inquirer";
 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 { AUIClient, AUIAPIError } from "../api-client/index.js";
+import { findAuiFiles, parseAuiFile, assembleBundleFromFiles, } from "../utils/index.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 { 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 { PushFileSummary, PushChangesView, PushFinalSummary, } from "../ui/views/PushView.js";
 import { isJsonMode, outputJson, stderrLog } from "../utils/json-output.js";
+import { detectAgentBundleMode, isModeMismatchError, } from "./util/agent-mode.js";
+import { runLegacyPush } from "./legacy/push-records-mode.js";
 // ─── Ink Rendering Helpers ───
 function log(node) {
     const { unmount } = render(node);
@@ -45,9 +43,7 @@ function startSpinner(label) {
         },
         /**
          * 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).
+         * to guarantee the spinner stops even when the wrapped body throws.
          */
         _forceUnmount() {
             safeUnmount();
@@ -56,12 +52,10 @@ function startSpinner(label) {
 }
 /**
  * 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.
+ * even on uncaught exceptions. Eliminates the "phantom spinner" foot-gun
+ * where an exception between `startSpinner(...)` and `.succeed/.fail` leaves
+ * the Ink render mounted forever — blocking the chat UI's "Still thinking…"
+ * state until SIGTERM.
  */
 async function withSpinner(label, fn) {
     const spinner = startSpinner(label);
@@ -73,7 +67,7 @@ async function withSpinner(label, fn) {
     }
 }
 /**
- * Push local agent configuration to the backend
+ * Push local agent configuration to the backend.
  */
 export async function push(agentCode, options = {}) {
     const tracer = getTracer();
@@ -96,7 +90,7 @@ export async function push(agentCode, options = {}) {
         }
     });
 }
-async function _push(pushSpan, agentCode, options = {}) {
+async function _push(pushSpan, _agentCode, options = {}) {
     const config = getConfig();
     const projectRoot = config.projectRoot || process.cwd();
     if (!config.isAuthenticated) {
@@ -120,201 +114,71 @@ async function _push(pushSpan, agentCode, options = {}) {
         });
     }
     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.
+    // ─── Back-compat: --force / --skip-validation are no-ops ───
+    // The new push endpoint runs the v1 transcoder bundle-validate as the
+    // first thing it does (before the per-version Redis lock and any GCS
+    // write). We keep the flags so existing scripts still parse, and
+    // record on the span whether they were requested for traceability.
     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();
-            }
+    pushSpan.setAttribute("push.skip_validation_flag_used", options.skipValidation === true);
+    if (options.force || options.skipValidation) {
+        pushSpan.addEvent("preflight.legacy_flag_noop", {
+            force: options.force === true,
+            skip_validation: options.skipValidation === true,
         });
-        // ── 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 (!json) {
+            log(_jsx(Box, { paddingX: 1, children: _jsx(StatusLine, { kind: "muted", label: `${options.force ? "--force" : "--skip-validation"} is a no-op under the new push endpoint (server validates the bundle).` }) }));
         }
-        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 {
+            stderrLog(`${options.force ? "--force" : "--skip-validation"} is a no-op under the new push endpoint.`);
         }
     }
-    else {
-        pushSpan.addEvent("preflight.validation_skipped");
-    }
+    // ─── Read every .aui.json under the project ───
+    // The new push endpoint expects a FULL bundle — we no longer split
+    // changes from baseline files. Read everything once up-front.
     if (!json)
-        log(_jsx(StatusLine, { kind: "info", label: "Pushing agent changes..." }));
+        log(_jsx(StatusLine, { kind: "info", label: "Reading local agent files..." }));
     else
         stderrLog("Reading local files...");
-    const spinner = json ? null : startSpinner("Reading local files...");
-    const fileData = [];
-    try {
+    const fileData = await withSpinner("Reading local files...", async (spinner) => {
+        const out = [];
         const files = await findAuiFiles(projectRoot);
-        for (const file of files) {
-            const parsed = parseAuiFile(file);
+        for (const f of files) {
+            const parsed = parseAuiFile(f);
             if (!parsed)
                 continue;
-            const relativePath = path.relative(projectRoot, file);
-            let type = "unknown";
+            const relativePath = path.relative(projectRoot, f);
             const isToolPath = relativePath.startsWith("tools/") || relativePath.startsWith("tools\\");
-            // 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)
+            // Classify by filename first (the new /pull endpoint enforces
+            // canonical, stable filenames at the bundle root), then fall
+            // back to content-based detection for non-canonical files.
+            //
+            // Why filename-first: `agent.aui.json` historically was written
+            // wrapped — `{ "general_settings": {...} }` — by the legacy
+            // exportAgent path, so `parsed.general_settings` was a reliable
+            // probe. The new /pull endpoint returns the file body the
+            // server stored, and per the spec the canonical shape for
+            // `agent.aui.json` is the UNWRAPPED general_settings object
+            // (`{ name, objective, guardrails, ... }` directly). The
+            // wrapped-only check therefore mis-classified every freshly
+            // pulled `agent.aui.json` as "unknown" — purely a label bug
+            // (the file still uploaded fine) but confusing in the summary.
+            const basename = path.basename(relativePath);
+            let type = "unknown";
+            if (basename === "agent.aui.json")
                 type = "general_settings";
+            else if (basename === "parameters.aui.json")
+                type = "parameters";
+            else if (basename === "entities.aui.json")
+                type = "entities";
+            else if (basename === "integrations.aui.json")
+                type = "integrations";
+            else if (basename === "rules.aui.json")
+                type = "rules";
             else if (parsed.tool || isToolPath)
                 type = "tool";
+            else if (parsed.general_settings)
+                type = "general_settings"; // legacy wrapped
             else if (parsed.parameters)
                 type = "parameters";
             else if (parsed.entities)
@@ -323,750 +187,746 @@ async function _push(pushSpan, agentCode, options = {}) {
                 type = "integrations";
             else if (parsed.rules)
                 type = "rules";
-            fileData.push({ file: relativePath, type, data: parsed });
+            out.push({ file: relativePath, type, data: parsed });
         }
+        spinner.succeed(`Read ${out.length} files`);
         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." }) }));
+            stderrLog(`Read ${out.length} files`);
+        return out;
+    });
+    if (fileData.length === 0) {
+        pushSpan.setAttribute("push.exit_reason", "no_files");
+        throw new CLIError("No .aui.json files found in this project to push.", {
+            suggestion: "Run `aui import` (or `aui pull`) to download the current agent bundle first.",
+        });
+    }
+    // The previous multipart endpoint required path-separator-free,
+    // unique filenames per request. The new JSON endpoint sends ONE
+    // canonical `bundle.json` — there are no filenames on the wire
+    // anymore, so the old collision check is gone. Tool files still
+    // need locally-unique basenames to avoid one .aui.json overwriting
+    // another in the project tree, but that's a project-layout issue,
+    // not a push-time one.
+    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 diff (informational + baseline tracking) ───
+    // The new endpoint uploads the full bundle every time so the diff is
+    // *not* used to decide what to send. We still compute it for:
+    //   - showing the user what they changed (UX)
+    //   - dry-run preview
+    //   - deciding whether to commit a baseline at the end
+    const { getDiffSummary, getFileDiff, getItemLevelDiff: getItemDiff, hasOwnGitRepo, initAndCommitBaseline, commitBaseline, } = 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;
         }
-        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,
-                            }));
-                        }
+        log(_jsx(Box, { paddingX: 1, children: _jsx(Hint, { message: "Baseline initialized. Run `aui push` again to upload the current bundle." }) }));
+        return;
+    }
+    const diff = getDiffSummary(projectRoot);
+    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;
-                        }
+                }
+                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;
-                                    }
+            }
+            return result;
+        });
+        log(_jsx(PushChangesView, { changes: changeFiles }));
+    }
+    // ─── Dry run: don't contact the backend at all ───
+    if (options.dryRun) {
+        pushSpan.setAttribute("push.exit_reason", "dry_run");
+        if (json) {
+            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;
-                                    }
+                            }
+                            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 result;
+                    })
+                    : [],
+            });
             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({
+        log(_jsx(Box, { paddingX: 1, children: _jsx(StatusLine, { kind: "muted", label: `Dry run — would push ${fileData.length} file(s) as a single bundle. Nothing uploaded.` }) }));
+        return;
+    }
+    // CHERRY-PICK NOTE (53a6024 + d7d91ab — 2026-05-24)
+    // ------------------------------------------------------------------
+    // The incoming hunk added a `hasKbChanges` short-circuit + per-entity
+    // `buildPushTasks` plumbing to the records-mode push pipeline. In our
+    // dual-mode CLI that pipeline lives in
+    // `commands/legacy/push-records-mode.tsx`, NOT here — `push.tsx`
+    // assembles a single bundle and POSTs it via `/push`.
+    //
+    // For BUNDLE-MODE pushes, "KB-only changes" can't be silently
+    // dropped: the assembled bundle is sent regardless (the server
+    // diff-compares against the previous revision), and the KB push
+    // is its own independent step via `pushKnowledgeHubs` below. The
+    // "no pushable changes" short-circuit in bundle-mode is already
+    // handled by the `diff.hasChanges` check higher up.
+    //
+    // The EQUIVALENT `hasKbChanges` fix for RECORDS-MODE pushes is
+    // applied directly inside `runLegacyPush` — see
+    // commands/legacy/push-records-mode.tsx where the legacy
+    // `pushTasks` short-circuit lives. Keep both in sync if the
+    // hasKbChanges semantics ever change again.
+    // ─── Resolve a draft version to push to ───
+    // The new endpoint enforces `status === draft`; resolve up-front so we
+    // surface a clean error instead of a 422 round-trip.
+    const session = await getValidSession();
+    if (!session) {
+        throw new AuthenticationError("Session expired.");
+    }
+    // `--agent-id` overlay: if the user passed an explicit target agent,
+    // dual-shape resolve it (agent_management_id first, fall back to
+    // network_id on 404) and overlay the resolved IDs onto `projectConfig`.
+    // Downstream (`resolveVersionDraft` → `lookupAgentManagementInfoForPush`)
+    // then picks up the override via the same code path as a normal
+    // `.auirc`-driven push — no special-casing.
+    let resolveProjectConfig = projectConfig;
+    if (options.agentId) {
+        const overlayClient = 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) — still need agent_id on write bodies.
-            // resolvePushAgentManagementId reads from .auirc first (cached by
-            // import-agent / pull-agent), falls back to listAgents lookup + writes
-            // back to .auirc so subsequent pushes skip the lookup.
-            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);
-            agentSettingsParams.agent_id = legacyAgentId;
-            pushSpan.setAttribute("push.agent_management_id", legacyAgentId);
+        const overlayKey = loadAgentSettingsApiKey();
+        if (overlayKey)
+            overlayClient.setAgentSettingsApiKey(overlayKey);
+        const resolved = await resolveExplicitAgentForPush(overlayClient, options.agentId);
+        resolveProjectConfig = {
+            ...projectConfig,
+            agent_id: resolved.networkId ?? projectConfig.agent_id,
+            agent_management_id: resolved.agentManagementId,
+        };
+        pushSpan.setAttribute("push.agent_id_override", options.agentId);
+        pushSpan.setAttribute("push.agent_id_override_resolved_as", resolved.via);
+        pushSpan.setAttribute("push.agent_management_id_overlay", resolved.agentManagementId);
+    }
+    // ─── Pre-flight: resolve agent + detect mode BEFORE draft lookup ──
+    //
+    // We do BOTH the agent-management lookup AND the bundle_mode
+    // dispatch up-front, before kicking off `resolveVersionDraft`.
+    // This catches two cases that otherwise crash later in the flow:
+    //
+    //   A) Pure-legacy agent (no agent_management_id anywhere)
+    //      → `lookupAgentManagementInfoForPush` returns no agentInfo.
+    //        We route directly to `runLegacyPush`, which uses `.auirc`
+    //        scope filters (network_id + account_id + organization_id
+    //        + network_category_id) for the per-entity write calls and
+    //        doesn't need an agent_management_id or version_id at all.
+    //        Sibling of the same fix in `commands/import-agent.tsx:doImport`.
+    //
+    //   B) Records-mode agent without draft versions
+    //      → `lookupAgentManagementInfoForPush` succeeds, but the agent
+    //        is records-mode (`bundle_mode: false`) AND has no draft
+    //        versions. Running `resolveVersionDraft` would throw
+    //        "No draft version found" even though `runLegacyPush` can
+    //        push the same agent without any version at all (legacy
+    //        records-mode never required versions). Repro 2026-05-26:
+    //        `Jaber-Amazon-v3-8` — has agent_management_id, has zero
+    //        versions, was failing to push.
+    //
+    // For bundle-mode agents we continue to require draft-version
+    // resolution (the new `/push` endpoint is keyed on version_id),
+    // which fires as the existing flow below.
+    //
+    // Performance: this folds two upstream lookups (the one I was
+    // already doing pre-flight + the one resolveVersionDraft would do
+    // internally) into ONE — net -1 round-trip on bundle-mode pushes
+    // versus the previous version of this file.
+    const preflightLookup = await lookupAgentManagementInfoForPush(config, resolveProjectConfig, session);
+    // (A) Pure-legacy short-circuit — no agentInfo means no
+    //     agent-management entry → records-mode by definition.
+    if (!preflightLookup.agentInfo) {
+        pushSpan.addEvent("dispatch.records_mode_handoff_pure_legacy", {
+            reason: "no_agent_management_id",
+            network_id: resolveProjectConfig.agent_id ?? "(unknown)",
+            errors: preflightLookup.errors.join("; ") || "(no errors)",
+        });
+        pushSpan.setAttribute("push.dispatch.mode", "records");
+        pushSpan.setAttribute("push.dispatch.mode_source", "no_agent_management_id");
+        if (process.env.AUI_DEBUG) {
+            console.log(`[debug] push: no agent_management_id resolvable for network ${resolveProjectConfig.agent_id ?? "(unknown)"} — routing to runLegacyPush (pure-legacy agent)`);
+        }
+        return runLegacyPush(pushSpan, _agentCode, {
+            force: options.force,
+            skipValidation: options.skipValidation,
+            dryRun: options.dryRun,
+            apiKey: options.apiKey,
+            versionId: options.versionId,
+            scopeLevel: options.scopeLevel,
+        });
+    }
+    // (B) Records-mode short-circuit — agentInfo exists, but the
+    //     agent is bundle_mode=false. Records-mode push doesn't need
+    //     a draft version (legacy per-entity writes operate on scope
+    //     filters + agent_id alone). Route to `runLegacyPush` BEFORE
+    //     `resolveVersionDraft` would throw "No draft version found"
+    //     for agents that legitimately have no drafts.
+    //
+    //     Uses the cached AgentInfo from the pre-flight, so
+    //     `detectAgentBundleMode` doesn't make an extra round-trip.
+    //     The `options.versionId` escape hatch still routes through
+    //     the draft resolution below — if the user EXPLICITLY passed
+    //     a version-id we honor it, even for records-mode (lets
+    //     advanced users target a specific records-mode version).
+    const preflightModeResolution = await detectAgentBundleMode(new AUIClient({
+        baseUrl: config.apiUrl,
+        authToken: config.authToken,
+        accountId: config.accountId,
+        organizationId: config.organizationId,
+        environment: config.environment,
+    }), preflightLookup.agentInfo.id, preflightLookup.agentInfo);
+    if (preflightModeResolution.mode === "records" && !options.versionId) {
+        pushSpan.addEvent("dispatch.records_mode_handoff_no_draft_required", {
+            agent_management_id: preflightLookup.agentInfo.id,
+            bundle_mode: preflightLookup.agentInfo.bundle_mode ?? "(missing)",
+            source: preflightModeResolution.source,
+        });
+        pushSpan.setAttribute("push.dispatch.mode", "records");
+        pushSpan.setAttribute("push.dispatch.mode_source", preflightModeResolution.source);
+        if (process.env.AUI_DEBUG) {
+            console.log(`[debug] push: records-mode agent ${preflightLookup.agentInfo.id} — routing to runLegacyPush directly (skipping draft resolution)`);
+        }
+        return runLegacyPush(pushSpan, _agentCode, {
+            force: options.force,
+            skipValidation: options.skipValidation,
+            dryRun: options.dryRun,
+            apiKey: options.apiKey,
+            versionId: options.versionId,
+            scopeLevel: options.scopeLevel,
+        });
+    }
+    const resolveTracer = getTracer();
+    const 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_explicit_agent_id", !!options.agentId);
+        rSpan.setAttribute("push.preflight.has_auirc_version_id", !!projectConfig.version_id);
+        if (resolveProjectConfig.agent_id) {
+            rSpan.setAttribute("push.preflight.network_id", resolveProjectConfig.agent_id);
         }
-        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);
+        try {
+            const draft = await resolveVersionDraft(config, resolveProjectConfig, 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;
         }
-        // pushKnowledgeHubs runs as a separate step; short-circuiting on
-        // pushTasks alone would silently no-op KB-only pushes.
-        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;
+        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;
         }
-        if (pushTasks.length > 0) {
-            log(_jsx(Box, { paddingX: 1, children: _jsx(StatusLine, { kind: "info", label: `Pushing ${pushTasks.length} change(s)...` }) }));
+        finally {
+            rSpan.end();
         }
-        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,
+    });
+    pushSpan.setAttribute("push.version_id", prePushDraft.versionId);
+    pushSpan.setAttribute("push.version_label", prePushDraft.label);
+    pushSpan.setAttribute("push.agent_management_id", prePushDraft.agentId);
+    // First-push migration: persist agent_management_id back to .auirc so
+    // subsequent pushes skip the listAgents lookup. 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,
             });
-            for (const kbFailure of kbResult.failures) {
-                failed++;
-                pushFailures.push(kbFailure);
+        }
+        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);
             }
         }
-        // 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.",
-                });
+    }
+    // ─── Create API client ───
+    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);
+    }
+    // ─── Mode dispatch: blob (new JSON push/pull) vs records (legacy) ───
+    //
+    // Every agent now carries an `Agent.bundle_mode` boolean (added
+    // 2026-05-24, see Notion "Agent Settings Push/Pull - Integration
+    // Guide" §2). The two surfaces are MUTUALLY EXCLUSIVE on the
+    // server — calling the wrong one returns `422 mode mismatch`. We
+    // detect the mode here (one `getAgent` call against an id we already
+    // have from the draft resolution above) and either continue with
+    // the blob-mode pipeline below OR hand off to the legacy per-entity
+    // pipeline in `./legacy/push-records-mode.tsx`.
+    //
+    // Why the dispatch lives here, not at the top of `_push`:
+    //   - We need `agent_management_id` to look up the AgentInfo, and
+    //     the cheapest way to get it (without an extra listAgents) is
+    //     to wait for `resolveVersionDraft` to do its own lookup —
+    //     `prePushDraft.agentId` is already populated above, and
+    //     `prePushDraft.agentInfo` carries the full AgentInfo so the
+    //     dispatcher can read `bundle_mode` without a second round-trip.
+    //   - The legacy module is fully self-contained (it re-loads
+    //     projectConfig, re-resolves the draft, re-scans files); we're
+    //     paying a small duplication cost on records-mode pushes for a
+    //     much cleaner separation of code paths. Records-mode is the
+    //     fallback for unmigrated agents — almost all new agents are
+    //     blob-mode, so the duplicate cost is rare and bounded.
+    //   - The KB push below is mode-agnostic but the legacy pipeline
+    //     ALREADY does its own KB push as part of its dependency-
+    //     ordered flow. Dispatching BEFORE the KB block here keeps both
+    //     paths' KB handling identical and avoids double-uploads.
+    const modeResolution = await detectAgentBundleMode(client, prePushDraft.agentId, prePushDraft.agentInfo);
+    pushSpan.setAttribute("push.dispatch.mode", modeResolution.mode);
+    pushSpan.setAttribute("push.dispatch.mode_source", modeResolution.source);
+    if (modeResolution.mode === "records") {
+        pushSpan.addEvent("dispatch.records_mode_handoff", {
+            agent_management_id: prePushDraft.agentId,
+            version_id: prePushDraft.versionId,
+            source: modeResolution.source,
+        });
+        // Hand off to the legacy per-entity pipeline. The legacy module
+        // re-derives everything from `options` + `agentCode` + on-disk
+        // `.auirc`, so we just forward the surface options that map
+        // cleanly. Blob-mode-only options (--agent-id, --caller,
+        // --commit-message) are intentionally dropped — they have no
+        // meaning in records-mode.
+        return runLegacyPush(pushSpan, _agentCode, {
+            force: options.force,
+            skipValidation: options.skipValidation,
+            dryRun: options.dryRun,
+            apiKey: options.apiKey,
+            versionId: options.versionId,
+            scopeLevel: options.scopeLevel,
+        });
+    }
+    // ─── Knowledge-base push (separate from .aui.json bundle) ───
+    // KBs are real content assets (PDFs, etc.) under `knowledge-hubs/`,
+    // uploaded via the KB view client. KB failures fold into the same
+    // `pushFailures` array as bundle failures so they hit the JSON
+    // envelope and the non-zero exit code (BFF contract).
+    const pushFailures = [];
+    let kbFailedCount = 0;
+    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) {
+            kbFailedCount++;
+            pushFailures.push(kbFailure);
+        }
+    }
+    // ─── Single Push call ───
+    // The new JSON endpoint expects an ASSEMBLED bundle, not files. We
+    // build the bundle from the in-memory `fileData` (already loaded
+    // and JSON-parsed earlier in this function) using the
+    // `assembleBundleFromFiles` helper, which handles both wrapped and
+    // flat shapes for each canonical file plus tool-file unwrapping.
+    const assembledBundle = assembleBundleFromFiles(fileData, {
+        schemaVersion: 1,
+    });
+    // Diagnostic counts for the spinner and span attrs. The bundle
+    // doesn't carry the raw `.aui.json` count anymore — it's domain-
+    // sliced — so report the per-domain sizes instead.
+    const bundleSummary = {
+        has_general_settings: !!assembledBundle.general_settings,
+        parameters: assembledBundle.parameters?.length ?? 0,
+        entities: assembledBundle.entities?.length ?? 0,
+        integrations: assembledBundle.integrations?.length ?? 0,
+        rules: assembledBundle.rules?.length ?? 0,
+        // `assembleBundleFromFiles` emits the tools array under the
+        // server-canonical `agent_tools` key, but historical callers
+        // may set the legacy `tools` key — count either so the span /
+        // summary doesn't lie about an "empty tools" push when tools
+        // were actually included under the legacy key.
+        tools: (assembledBundle.agent_tools?.length ?? 0) +
+            (assembledBundle.agent_tools ? 0 : assembledBundle.tools?.length ?? 0),
+    };
+    const bundleEntityCount = bundleSummary.parameters +
+        bundleSummary.entities +
+        bundleSummary.integrations +
+        bundleSummary.rules +
+        bundleSummary.tools +
+        (bundleSummary.has_general_settings ? 1 : 0);
+    const PUSH_MAX_ATTEMPTS = 4;
+    const PUSH_RETRY_BASE_MS = 1000;
+    let pushResult = null;
+    let pushAttempts = 0;
+    let lastError;
+    const pushTracer = getTracer();
+    for (let attempt = 1; attempt <= PUSH_MAX_ATTEMPTS; attempt++) {
+        pushAttempts = attempt;
+        const label = attempt === 1
+            ? `Pushing bundle (${bundleEntityCount} item(s)) to draft ${prePushDraft.label}...`
+            : `Retrying push (attempt ${attempt}/${PUSH_MAX_ATTEMPTS})...`;
+        if (json)
+            stderrLog(label);
+        const attemptSpinner = json ? null : startSpinner(label);
+        const attemptOutcome = await pushTracer.startActiveSpan("aui.push.task.bundle", async (pSpan) => {
+            pSpan.setAttribute("push.task.type", "bundle");
+            pSpan.setAttribute("push.task.label", label);
+            pSpan.setAttribute("push.bundle.attempt", attempt);
+            pSpan.setAttribute("push.bundle.max_attempts", PUSH_MAX_ATTEMPTS);
+            pSpan.setAttribute("push.bundle.parameters_count", bundleSummary.parameters);
+            pSpan.setAttribute("push.bundle.entities_count", bundleSummary.entities);
+            pSpan.setAttribute("push.bundle.integrations_count", bundleSummary.integrations);
+            pSpan.setAttribute("push.bundle.rules_count", bundleSummary.rules);
+            pSpan.setAttribute("push.bundle.tools_count", bundleSummary.tools);
+            pSpan.setAttribute("push.bundle.has_general_settings", bundleSummary.has_general_settings);
+            pSpan.setAttribute("push.bundle.agent_id", prePushDraft.agentId);
+            pSpan.setAttribute("push.bundle.version_id", prePushDraft.versionId);
+            if (options.commitMessage) {
+                pSpan.setAttribute("push.bundle.commit_message_len", options.commitMessage.length);
             }
-            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,
+            try {
+                const result = await client.agentManagement.pushVersionBlobs(prePushDraft.agentId, prePushDraft.versionId, {
+                    // `--caller` overrides the default; falls back to `cli`
+                    // when not set. Server enum is strictly
+                    // `agent_builder` | `ui` | `cli` — anything else 422s.
+                    caller: options.caller ?? "cli",
+                    commit_message: options.commitMessage,
+                    // `pushed_by` (added 2026-05-25 per backend team): records
+                    // the user id of the person doing the push on the new
+                    // `agent_version_blob_revisions` row alongside `caller`.
+                    // `caller` tells you WHICH surface invoked /push (cli /
+                    // ui / agent_builder); `pushed_by` tells you WHO. Session
+                    // is guaranteed non-null by the throw on line 585 above,
+                    // so `session.user_id` is always populated here. Omitted
+                    // only if the session somehow lacks a user_id (defensive
+                    // — JWT claim should always carry one).
+                    ...(session.user_id ? { pushed_by: session.user_id } : {}),
+                    bundle: assembledBundle,
                 });
-                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);
+                if (result.success) {
+                    pSpan.setStatus({ code: SpanStatusCode.OK });
+                    pSpan.setAttribute("push.bundle.outcome", "success");
+                    if (result.data?.new_version_tag) {
+                        pSpan.setAttribute("push.bundle.new_version_tag", result.data.new_version_tag);
                     }
-                    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 }));
+                    if (result.data?.revision_id) {
+                        pSpan.setAttribute("push.bundle.revision_id", result.data.revision_id);
                     }
-                }
-            }
-            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 };
+                    if (result.data?.gcs_key) {
+                        pSpan.setAttribute("push.bundle.gcs_key", result.data.gcs_key);
                     }
-                    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 };
+                    if (result.data?.sha256) {
+                        pSpan.setAttribute("push.bundle.sha256", result.data.sha256);
                     }
-                    finally {
-                        snapSpan.end();
+                    if (typeof result.data?.size === "number") {
+                        pSpan.setAttribute("push.bundle.size_bytes", result.data.size);
                     }
-                });
-                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;
+                    return { ok: true, result };
                 }
-                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 errMsg = result.error || "Unknown push error";
+                pSpan.setStatus({ code: SpanStatusCode.ERROR, message: errMsg });
+                pSpan.setAttribute("push.bundle.outcome", "failed");
+                pSpan.setAttribute("push.task.error", errMsg);
+                return { ok: false, error: errMsg, result };
             }
-        }
-        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,
+            catch (error) {
+                const errMsg = error instanceof Error ? error.message : String(error);
+                pSpan.setStatus({ code: SpanStatusCode.ERROR, message: errMsg });
+                pSpan.recordException(error instanceof Error ? error : new Error(errMsg));
+                pSpan.setAttribute("push.bundle.outcome", "exception");
+                pSpan.setAttribute("push.task.error", errMsg);
+                // Server changed the agent's mode mid-flight (rare: usually
+                // an admin flipping `bundle_mode` while a push is in
+                // progress). The 422 is unrecoverable on this surface —
+                // translate to a clear "rerun" hint instead of letting it
+                // look like a transient push error.
+                if (isModeMismatchError(error)) {
+                    pSpan.setAttribute("push.bundle.mode_mismatch", true);
+                    throw new CLIError(`Server reports this agent is now in DB-records mode — the JSON push endpoint rejected the request (422).`, {
+                        suggestion: "Re-run `aui push`. The CLI re-detects the agent's mode on every invocation and will pick the legacy per-entity pipeline on the next run.",
                     });
                 }
+                return { ok: false, error: errMsg, result: null };
             }
-            else if (failed === 0) {
-                commitBaseline(projectRoot, "pushed changes");
-                baselineUpdated = true;
-                pushSpan.addEvent("baseline.full_commit");
+            finally {
+                pSpan.end();
             }
+        });
+        if (attemptOutcome.ok) {
+            const newTag = attemptOutcome.result.data?.new_version_tag ?? prePushDraft.label;
+            const okMsg = attempt === 1
+                ? `Push complete → ${newTag} (bundle: ${bundleEntityCount} item(s))`
+                : `Push complete → ${newTag} (bundle: ${bundleEntityCount} item(s), attempt ${attempt}/${PUSH_MAX_ATTEMPTS})`;
+            if (attemptSpinner)
+                attemptSpinner.succeed(okMsg);
+            else
+                stderrLog(okMsg);
+            pushResult = attemptOutcome.result;
+            lastError = undefined;
+            break;
+        }
+        lastError = attemptOutcome.error;
+        // 4xx are deterministic; only retry 5xx + 409 (lock contention).
+        const shouldRetry = isTransientPushError(attemptOutcome.error) && attempt < PUSH_MAX_ATTEMPTS;
+        const isLast = !shouldRetry;
+        const failMsg = isLast
+            ? `Push failed after ${attempt} attempt(s): ${attemptOutcome.error}`
+            : `Push failed (attempt ${attempt}/${PUSH_MAX_ATTEMPTS}): ${attemptOutcome.error}`;
+        if (attemptSpinner)
+            attemptSpinner.fail(failMsg);
+        else
+            stderrLog(failMsg);
+        if (isLast) {
+            pushResult = attemptOutcome.result;
+            break;
         }
-        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` }));
+        const delayMs = PUSH_RETRY_BASE_MS * Math.pow(2, attempt - 1);
+        if (json)
+            stderrLog(`Waiting ${delayMs}ms before retry...`);
+        await new Promise((resolve) => setTimeout(resolve, delayMs));
+    }
+    const pushSucceeded = !!pushResult && pushResult.success;
+    pushSpan.setAttribute("push.bundle.success", pushSucceeded);
+    pushSpan.setAttribute("push.bundle.attempts", pushAttempts);
+    if (!pushSucceeded && lastError) {
+        pushSpan.setAttribute("push.bundle.error", lastError);
+        pushFailures.push({
+            label: `Push bundle to ${prePushDraft.label}`,
+            error: lastError,
+        });
+    }
+    // ─── Persist new revision tag to .auirc ───
+    // The backend assigns a fresh `version_tag` on every push (e.g.
+    // v8.13 → v8.14). Save it to `version_tag` (NOT `version_label`,
+    // which represents the version document's `version_number` — e.g.
+    // "v8" — and is used for telemetry / version UX). On the next
+    // `aui pull` we use this tag as the default `?version_tag=…` query
+    // param so users re-pull exactly the revision they just pushed.
+    if (pushSucceeded && pushResult?.data) {
+        const newTag = pushResult.data.new_version_tag;
+        if (newTag) {
+            try {
+                saveProjectConfig({ ...projectConfig, version_tag: newTag }, projectRoot);
+                pushSpan.addEvent("auirc.version_tag_persisted", { tag: newTag });
             }
-            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.` }));
+            catch (err) {
+                if (process.env.AUI_DEBUG) {
+                    console.warn("[debug] failed to persist version_tag to .auirc:", err instanceof Error ? err.message : err);
+                }
             }
         }
-        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;
+    // ─── Baseline commit ───
+    // The new endpoint is atomic for the bundle, so we either commit
+    // everything (bundle pushed AND KBs OK) or hold the baseline (so the
+    // user can re-run `aui push` to retry against the same pre-push state).
+    let baselineUpdated = false;
+    if (pushSucceeded && kbFailedCount === 0) {
+        commitBaseline(projectRoot, `pushed bundle → ${pushResult?.data?.new_version_tag ?? prePushDraft.label}`);
+        baselineUpdated = true;
+        pushSpan.addEvent("baseline.full_commit");
+    }
+    else if (pushSucceeded && kbFailedCount > 0) {
+        pushSpan.addEvent("baseline.held_back_due_to_kb_failure", {
+            kb_failed: kbFailedCount,
+        });
+    }
+    else {
+        pushSpan.addEvent("baseline.held_back_due_to_push_failure");
+    }
+    pushSpan.setAttribute("push.baseline_updated", baselineUpdated);
+    // ─── Push memory + final summary ───
+    const logRelPath = path.relative(projectRoot, pushLogDir);
+    const agentCodeStr = projectConfig.agent_code || projectConfig.agent_id || "unknown";
+    const agentIdStr = projectConfig.agent_id || "unknown";
+    const memoryPath = writePushMemory(projectRoot, {
+        agentCode: agentCodeStr,
+        agentId: agentIdStr,
+        versionLabel: prePushDraft.label,
+        newVersionTag: pushResult?.data?.new_version_tag,
+        revisionId: pushResult?.data?.revision_id,
+        commitMessage: pushResult?.data?.commit_message ?? options.commitMessage ?? undefined,
+        fileData,
+        // The new endpoint is bundle-shaped, so there isn't really a
+        // per-file upload list anymore — record the local file paths the
+        // bundle was assembled from instead. Diagnostic only.
+        uploadedFiles: fileData.map((fd) => fd.file),
+        diff,
+        pushSucceeded,
+        bundleError: pushSucceeded ? undefined : lastError,
+        kbFailures: kbResult.failures,
+    });
+    log(_jsx(PushFinalSummary, { succeeded: pushSucceeded ? bundleEntityCount : 0, failed: pushFailures.length, baselineUpdated: baselineUpdated, logDir: logRelPath, memoryPath: memoryPath, snapshotStatus: pushSucceeded ? "succeeded" : "failed", snapshotError: lastError }));
+    if (pushFailures.length > 0) {
+        log(_jsxs(Box, { flexDirection: "column", paddingX: 1, children: [_jsx(StatusLine, { kind: "warning", label: `${pushFailures.length} task(s) failed.` }), 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. Your local files remain the source of truth."] })] })] }));
+    }
+    else if (pushSucceeded) {
+        const newTag = pushResult?.data?.new_version_tag ?? prePushDraft.label;
+        log(_jsx(StatusLine, { kind: "info", label: `All changes pushed to draft ${newTag}. Run: aui version publish → aui version activate` }));
+    }
+    // ─── Telemetry exit reason ───
+    pushSpan.setAttribute("push.exit_reason", pushSucceeded
+        ? kbFailedCount > 0
+            ? "partial_kb_failure"
+            : "completed"
+        : "failed");
+    pushSpan.setAttribute("push.succeeded_count", pushSucceeded ? bundleEntityCount : 0);
+    pushSpan.setAttribute("push.failed_count", pushFailures.length);
+    if (pushFailures.length > 0) {
+        pushSpan.setAttribute("push.failures", JSON.stringify(pushFailures));
+    }
+    // ─── JSON envelope (success path) ───
+    if (json && pushSucceeded && kbFailedCount === 0) {
+        outputJson({
+            agent: { code: agentCodeStr, id: agentIdStr },
+            version: {
+                id: prePushDraft.versionId,
+                label: prePushDraft.label,
+                new_tag: pushResult?.data?.new_version_tag,
+            },
+            bundle: {
+                status: "succeeded",
+                attempts: pushAttempts,
+                // No more per-file upload list — the new endpoint writes one
+                // canonical `bundle.json` and returns its key + hash + size.
+                item_count: bundleEntityCount,
+                item_counts: bundleSummary,
+                new_version_tag: pushResult?.data?.new_version_tag,
+                new_version_revision_number: pushResult?.data?.new_version_revision_number,
+                revision_id: pushResult?.data?.revision_id,
+                commit_message: pushResult?.data?.commit_message,
+                gcs_key: pushResult?.data?.gcs_key,
+                sha256: pushResult?.data?.sha256,
+                size_bytes: pushResult?.data?.size,
+                created_at: pushResult?.data?.created_at,
+            },
+            baseline_updated: baselineUpdated,
+            log_dir: logRelPath,
+            memory_path: memoryPath,
+        });
+    }
+    // ─── Failure throws (loud + non-zero exit + JSON error envelope) ───
+    // CLIError funnels into handleError() which prints the formatted error,
+    // emits the JSON error envelope (in --json mode), and exits non-zero.
+    // The BFF parses both signals (HTTP status + JSON envelope) so a silent
+    // exit-0 here would let `agent-builder-bff` claim a phantom success.
+    if (!pushSucceeded) {
+        throw new CLIError(`Push failed: ${lastError ?? "unknown error"}`, {
+            suggestion: "Fix the errors above and re-run `aui push`. Your local files remain the source of truth.",
+        });
+    }
+    if (kbFailedCount > 0) {
+        const labels = pushFailures.map((f) => f.label).join(", ");
+        throw new CLIError(`${kbFailedCount} knowledge-base task(s) failed: ${labels}`, {
+            suggestion: "Re-run `aui push` to retry KB uploads. The .aui.json bundle has been saved.",
+        });
     }
 }
+// ─── Transient error classifier (retry decision) ───
+//
+// The new push endpoint surfaces failures as `{ success: false, error: "<status>: <msg>" }`
+// or as a thrown error with the same shape. We retry 5xx (network /
+// backend hiccup) and 409 (concurrent push lock contention) — both are
+// expected to resolve on backoff. 4xx (other than 409) are deterministic
+// — validation / auth / missing-resource — and never get retried.
+function isTransientPushError(err) {
+    if (!err)
+        return false;
+    // Errors come back as "<status>: <body>" from the api client, or as
+    // raw fetch errors / timeouts (no leading status). Treat fetch/abort
+    // errors as transient too — they're not the user's fault.
+    const m = err.match(/^(\d{3})/);
+    if (m) {
+        const status = parseInt(m[1], 10);
+        if (status === 409)
+            return true;
+        if (status >= 500 && status <= 599)
+            return true;
+        return false;
+    }
+    // No HTTP status → likely network/timeout. Retry.
+    return /timeout|timed out|fetch failed|network|econnreset|enotfound|eai_again|socket hang up/i.test(err);
+}
 /**
  * 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.
+ * (preferred) or the active session fallback. 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({
@@ -1082,9 +942,24 @@ async function lookupAgentManagementInfoForPush(config, projectConfig, session)
     let agentInfo;
     const errors = [];
     const agentMgmtId = session.agent_management_id;
+    const projectAgentMgmtId = projectConfig.agent_management_id;
     const projectNetworkId = projectConfig.agent_id;
     const fallbackNetworkId = session.network_id;
-    if (projectNetworkId) {
+    // Highest-priority shortcut: if `.auirc` (or the `--agent-id`
+    // overlay in `_push`) already carries an `agent_management_id`,
+    // hit `getAgent` directly. One round-trip, no list scan.
+    if (projectAgentMgmtId) {
+        try {
+            agentInfo = await client.agentManagement.getAgent(projectAgentMgmtId);
+        }
+        catch (err) {
+            errors.push(`getAgent(${projectAgentMgmtId}) threw: ${err instanceof Error ? err.message : String(err)}`);
+            if (process.env.AUI_DEBUG) {
+                console.warn(`[debug] lookupAgentManagementInfoForPush: getAgent(${projectAgentMgmtId}) failed (stale id?):`, err instanceof Error ? err.message : err);
+            }
+        }
+    }
+    if (!agentInfo && 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 ||
@@ -1094,18 +969,14 @@ async function lookupAgentManagementInfoForPush(config, projectConfig, session)
             }
         }
         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.
+    // Direct getAgent call by session's agent_management_id — no list scan,
+    // and gracefully covers the case where listAgents fell through.
     if (!agentInfo && agentMgmtId) {
         try {
             agentInfo = await client.agentManagement.getAgent(agentMgmtId);
@@ -1117,7 +988,9 @@ async function lookupAgentManagementInfoForPush(config, projectConfig, session)
             }
         }
     }
-    if (!agentInfo && fallbackNetworkId && fallbackNetworkId !== projectNetworkId) {
+    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 ||
@@ -1136,37 +1009,83 @@ async function lookupAgentManagementInfoForPush(config, projectConfig, session)
     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`.
+ * Dual-shape resolve for `--agent-id <id>` on `aui push`. Same pattern
+ * as `aui import`'s explicit-id branch: the user might pass either an
+ * `agent_management_id` (preferred, new world) or a legacy `network_id`
+ * (back-compat). Same regex, different document family. Try
+ * `agentManagement.getAgent(id)` first, fall back to
+ * `listAgents(network_id=id)` on 404. Non-404 errors bubble.
  */
-async function resolvePushAgentManagementId(config, projectConfig, session, projectRoot) {
-    if (projectConfig.agent_management_id)
-        return projectConfig.agent_management_id;
-    const { agentInfo, errors } = await lookupAgentManagementInfoForPush(config, projectConfig, session);
-    if (!agentInfo) {
-        const detail = errors.length > 0 ? `\n  - ${errors.join("\n  - ")}` : "";
-        throw new ConfigError(`Could not resolve agent-management id for this project.${detail}`, {
-            suggestion: "Re-run `aui import-agent` (will populate .auirc.agent_management_id) or `aui pull` to back-fill it.",
-        });
+async function resolveExplicitAgentForPush(client, explicitId) {
+    // 1) Treat as agent_management_id.
+    try {
+        const info = await client.agentManagement.getAgent(explicitId);
+        // Bias the client scope toward the agent's own org/account so the
+        // subsequent listVersions / push calls don't 403 against the
+        // session's default scope.
+        const scopeUpdate = {};
+        if (info.scope?.account_id)
+            scopeUpdate.accountId = info.scope.account_id;
+        if (info.scope?.organization_id)
+            scopeUpdate.organizationId = info.scope.organization_id;
+        if (scopeUpdate.accountId || scopeUpdate.organizationId) {
+            client.setScope(scopeUpdate);
+        }
+        return {
+            agentManagementId: info.id,
+            networkId: info.scope?.network_id ?? undefined,
+            via: "agent_management_id",
+        };
     }
-    // Migrate legacy projects: persist back so the next push skips the lookup.
+    catch (err) {
+        const status = err instanceof AUIAPIError
+            ? err.status
+            : (err.statusCode ??
+                err.status);
+        if (status !== 404) {
+            throw new CLIError(`Could not resolve --agent-id ${explicitId} as agent_management_id: ${err instanceof Error ? err.message : String(err)}`, {
+                suggestion: "Check your auth (`aui status`) and the agent id. If the id is a legacy network_id, it will be tried as a fallback only on 404 from agent-management.",
+                cause: err,
+            });
+        }
+        if (process.env.AUI_DEBUG) {
+            console.log(`[debug] resolveExplicitAgentForPush: getAgent(${explicitId}) → 404, trying as network_id`);
+        }
+    }
+    // 2) Fall back: treat as legacy network_id.
     try {
-        saveProjectConfig({ ...projectConfig, agent_management_id: agentInfo.id }, projectRoot);
+        const resp = await client.agentManagement.listAgents(client.getOrganizationId(), 1, 50, { network_id: explicitId });
+        const match = resp.items.find((a) => a.scope.network_id === explicitId || a.id === explicitId);
+        if (!match) {
+            throw new CLIError(`Could not resolve --agent-id ${explicitId} as agent_management_id OR network_id.`, {
+                suggestion: "Verify the agent exists in agent-management. Run `aui agents` to list available agents.",
+            });
+        }
+        const scopeUpdate = {};
+        if (match.scope?.account_id)
+            scopeUpdate.accountId = match.scope.account_id;
+        if (match.scope?.organization_id)
+            scopeUpdate.organizationId = match.scope.organization_id;
+        if (scopeUpdate.accountId || scopeUpdate.organizationId) {
+            client.setScope(scopeUpdate);
+        }
+        return {
+            agentManagementId: match.id,
+            networkId: match.scope?.network_id ?? undefined,
+            via: "network_id",
+        };
     }
-    catch {
-        // .auirc write failure is non-fatal — we already have the id in memory.
+    catch (err) {
+        if (err instanceof CLIError)
+            throw err;
+        throw new CLIError(`Failed to resolve --agent-id ${explicitId} via legacy network_id lookup: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
     }
-    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.
+    // Returning null silently exits with code 0 — the BFF then thinks the
+    // push succeeded 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  - ")}` : "";
@@ -1184,17 +1103,88 @@ async function resolveVersionDraft(config, projectConfig, session, explicitVersi
     const key = loadAgentSettingsApiKey();
     if (key)
         client.setAgentSettingsApiKey(key);
-    // If user passed --version-id, validate it's a draft
+    // If user passed --version-id, validate it's a draft.
     if (explicitVersionId) {
         let ver;
+        let owningAgent = agentInfo;
         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,
-            });
+            const status = error.statusCode ??
+                error.status;
+            if (status !== 404) {
+                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,
+                });
+            }
+            // ─── Multi-agent fallback (same pattern as `selectVersionForAgent`)
+            //
+            // One `network_id` can map to multiple agent-management records
+            // (data-migration duplicates, account-scoped variants, etc.).
+            // We picked the first match from `lookupAgentManagementInfoForPush`
+            // above, but `--version-id` may belong to a SIBLING agent record
+            // for the same network. Paginate every candidate for the
+            // network and try `getVersion` on each — return the first one
+            // that succeeds with the matching version, and use THAT agent's
+            // id when pushing so the bundle lands on the correct revision.
+            const projectNetworkId = projectConfig.agent_id;
+            if (projectNetworkId) {
+                const probeClient = new AUIClient({
+                    baseUrl: config.apiUrl,
+                    authToken: config.authToken,
+                    accountId: config.accountId,
+                    organizationId: config.organizationId,
+                    environment: config.environment,
+                });
+                const probeKey = loadAgentSettingsApiKey();
+                if (probeKey)
+                    probeClient.setAgentSettingsApiKey(probeKey);
+                const candidates = [];
+                try {
+                    let probePage = 1;
+                    let probeHasMore = true;
+                    while (probeHasMore) {
+                        const resp = await probeClient.agentManagement.listAgents(probeClient.getOrganizationId(), probePage, 50, { network_id: projectNetworkId });
+                        candidates.push(...resp.items);
+                        probeHasMore = probePage < resp.pages;
+                        probePage++;
+                    }
+                }
+                catch (probeErr) {
+                    if (process.env.AUI_DEBUG) {
+                        console.warn(`[debug] resolveVersionDraft multi-agent fallback listAgents failed:`, probeErr instanceof Error ? probeErr.message : probeErr);
+                    }
+                }
+                const siblings = candidates.filter((c) => c.id !== agentInfo.id);
+                if (process.env.AUI_DEBUG) {
+                    console.log(`[debug] resolveVersionDraft: probing ${siblings.length} sibling agent(s) for version ${explicitVersionId}`);
+                }
+                for (const sibling of siblings) {
+                    try {
+                        ver = await probeClient.agentManagement.getVersion(sibling.id, explicitVersionId);
+                        owningAgent = sibling;
+                        if (process.env.AUI_DEBUG) {
+                            console.log(`[debug] resolveVersionDraft: version ${explicitVersionId} found on sibling agent ${sibling.id}`);
+                        }
+                        break;
+                    }
+                    catch (siblingErr) {
+                        const sStatus = siblingErr
+                            .statusCode ??
+                            siblingErr.status;
+                        if (sStatus !== 404)
+                            throw siblingErr;
+                    }
+                }
+            }
+            if (!ver) {
+                throw new CLIError(`Could not fetch version "${explicitVersionId}" on any agent record for this network.`, {
+                    suggestion: "Verify the version ID with `aui version list` or from the Playground's `Versions management` dialog. The version may belong to a different account / organization scope.",
+                    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.`, {
@@ -1202,9 +1192,14 @@ async function resolveVersionDraft(config, projectConfig, session, explicitVersi
             });
         }
         const label = `v${ver.version_number}`;
-        return { versionId: ver.id, label, agentId: agentInfo.id };
+        return {
+            versionId: ver.id,
+            label,
+            agentId: owningAgent.id,
+            agentInfo: owningAgent,
+        };
     }
-    // Resolve from .auirc version_id or auto-detect drafts
+    // Resolve from .auirc version_id or auto-detect drafts.
     let allVersions = [];
     try {
         const versionsResp = await client.agentManagement.listVersions(agentInfo.id, 1, 50);
@@ -1216,7 +1211,6 @@ async function resolveVersionDraft(config, projectConfig, session, explicitVersi
             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) {
@@ -1226,10 +1220,15 @@ async function resolveVersionDraft(config, projectConfig, session, explicitVersi
                 });
             }
             const label = `v${configVersion.version_number}`;
-            return { versionId: configVersion.id, label, agentId: agentInfo.id };
+            return {
+                versionId: configVersion.id,
+                label,
+                agentId: agentInfo.id,
+                agentInfo,
+            };
         }
     }
-    // Auto-detect drafts
+    // 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.", {
@@ -1239,139 +1238,27 @@ async function resolveVersionDraft(config, projectConfig, session, explicitVersi
     if (drafts.length === 1) {
         const draft = drafts[0];
         const label = `v${draft.version_number}`;
-        return { versionId: draft.id, label, agentId: agentInfo.id };
+        return {
+            versionId: draft.id,
+            label,
+            agentId: agentInfo.id,
+            agentInfo,
+        };
     }
-    // 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.
+    // Multiple drafts — auto-pick the latest. No interactive prompt
+    // (keeps `aui push` non-blocking). Use --version-id to 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: [] };
-    }
-    const result = await client.agentManagement.pushSnapshot(agentId, versionId, filesToUpload);
     return {
-        success: result.success,
-        failed: result.failed,
-        error: result.error,
-    };
-}
-// ─── 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,
+        versionId: latest.id,
+        label: latestLabel,
+        agentId: agentInfo.id,
+        agentInfo,
     };
-    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");
@@ -1433,7 +1320,7 @@ async function pushKnowledgeHubs(projectRoot, projectConfig) {
                 }
                 // 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.
+                // body — same observability shape as the previous per-entity tasks.
                 const kbDelTracer = getTracer();
                 await kbDelTracer.startActiveSpan("aui.push.task.kb-delete", async (span) => {
                     span.setAttribute("push.task.type", "kb-delete");
@@ -1459,7 +1346,10 @@ async function pushKnowledgeHubs(projectRoot, projectConfig) {
                     }
                     catch (delErr) {
                         // Per-KB error: count it, keep going so partial work shows up.
-                        if (isNotFoundError(delErr)) {
+                        // 404 → already absent (success); other errors → real failure.
+                        const statusCode = delErr
+                            .statusCode ?? delErr.status;
+                        if (statusCode === 404) {
                             span.setStatus({ code: SpanStatusCode.OK });
                             span.addEvent("fallback.delete_404_already_absent");
                             span.setAttribute("push.task.fallback", "delete_404_already_absent");
@@ -1471,8 +1361,8 @@ async function pushKnowledgeHubs(projectRoot, projectConfig) {
                             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);
+                            if (statusCode) {
+                                span.setAttribute("push.task.error_status_code", statusCode);
                             }
                             failures.push({
                                 label: `Delete knowledge base: ${kbName}`,
@@ -1522,9 +1412,6 @@ async function pushKnowledgeHubs(projectRoot, projectConfig) {
                     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");
@@ -1561,8 +1448,6 @@ async function pushKnowledgeHubs(projectRoot, projectConfig) {
                                     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);
@@ -1573,9 +1458,13 @@ async function pushKnowledgeHubs(projectRoot, projectConfig) {
                         }
                         catch (uploadErr) {
                             hadUploadFailure = true;
-                            const errMsg = uploadErr instanceof Error ? uploadErr.message : String(uploadErr);
+                            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.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);
@@ -1701,8 +1590,43 @@ async function pushKnowledgeHubs(projectRoot, projectConfig) {
     }
     return { ok: kbPushSucceeded && failures.length === 0, failures };
 }
-// ─── Array File Info Helper ───
+// ─── Diff helper: read array metadata from a known top-level shape ───
 function getArrayFileInfoForPush(filePath, dir) {
+    // Filename-first detection (same rationale as the classifier in
+    // `_push`'s read loop) — under the new /pull endpoint the canonical
+    // files may or may not be wrapped depending on push origin, but
+    // their filenames are stable. `agent.aui.json` is intentionally
+    // NOT in this map: it's a single general_settings object, not an
+    // array file, so item-level diff doesn't apply.
+    const basename = path.basename(filePath);
+    const FILENAME_ARRAY_INFO = {
+        "parameters.aui.json": {
+            arrayKey: "parameters",
+            itemKey: "code",
+            label: "Parameters",
+        },
+        "entities.aui.json": {
+            arrayKey: "entities",
+            itemKey: "name",
+            label: "Entities",
+        },
+        "integrations.aui.json": {
+            arrayKey: "integrations",
+            itemKey: "code",
+            label: "Integrations",
+        },
+        "rules.aui.json": {
+            arrayKey: "rules",
+            itemKey: "code",
+            label: "Rules",
+        },
+    };
+    if (basename in FILENAME_ARRAY_INFO) {
+        return FILENAME_ARRAY_INFO[basename];
+    }
+    // Fallback to content-based detection for non-canonical filenames
+    // (legacy projects, custom layouts). Tool files are NOT array
+    // files — return null so the per-tool diff stays at file-level.
     try {
         const fullPath = path.join(dir, filePath);
         if (!fs.existsSync(fullPath))
@@ -1729,7 +1653,7 @@ function getArrayFileInfoForPush(filePath, dir) {
         return null;
     }
 }
-function writePushMemory(projectRoot, agentCode, agentId, pushTasks, succeededFiles, pushFailures) {
+function writePushMemory(projectRoot, input) {
     try {
         const memoryDir = path.join(projectRoot, "memory");
         fs.mkdirSync(memoryDir, { recursive: true });
@@ -1737,80 +1661,52 @@ function writePushMemory(projectRoot, agentCode, agentId, pushTasks, succeededFi
         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 overallStatus = input.pushSucceeded
+            ? input.kbFailures.length === 0
+                ? "SUCCESS"
+                : "PARTIAL"
+            : "FAILED";
         const lines = [
             `# Push ${dateStr}`,
             "",
-            `**Agent:** ${agentCode}`,
-            `**Agent ID:** ${agentId}`,
+            `**Agent:** ${input.agentCode}`,
+            `**Agent ID:** ${input.agentId}`,
+            `**Draft:** ${input.versionLabel}`,
+            `**New tag:** ${input.newVersionTag ?? "(none — push did not succeed)"}`,
+            `**Revision ID:** ${input.revisionId ?? "(none)"}`,
             `**Status:** ${overallStatus}`,
-            `**Total:** ${totalSucceeded} succeeded, ${totalFailed} failed`,
-            "",
-            "## Changes",
+            `**Bundle:** ${input.uploadedFiles.length} file(s) uploaded`,
             "",
         ];
-        const tasksByCategory = {};
-        for (const task of pushTasks) {
-            const category = task.type.split("-").slice(1).join(" ");
-            if (!tasksByCategory[category])
-                tasksByCategory[category] = [];
-            tasksByCategory[category].push(task);
+        if (input.commitMessage) {
+            lines.push(`**Commit message:** ${input.commitMessage}`);
+            lines.push("");
         }
-        for (const [category, tasks] of Object.entries(tasksByCategory)) {
-            lines.push(`### ${category.charAt(0).toUpperCase() + category.slice(1)}`);
+        if (!input.pushSucceeded && input.bundleError) {
+            lines.push("## Bundle Error", "");
+            lines.push("```");
+            lines.push(input.bundleError);
+            lines.push("```", "");
+        }
+        lines.push("## Files in bundle", "");
+        for (const fd of input.fileData) {
+            lines.push(`- \`${fd.file}\` _(${fd.type})_`);
+        }
+        lines.push("");
+        if (input.diff && input.diff.changedFiles.length > 0) {
+            lines.push("## Changed since last push", "");
+            for (const change of input.diff.changedFiles) {
+                lines.push(`- **${change.status}** \`${change.file}\``);
+            }
             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("");
+        }
+        if (input.kbFailures.length > 0) {
+            lines.push("## Knowledge-base failures", "");
+            for (const f of input.kbFailures) {
+                lines.push(`- :x: **${f.label}**`);
+                lines.push(`  - Error: ${f.error}`);
+                if (f.file)
+                    lines.push(`  - File: \`${f.file}\``);
             }
             lines.push("");
         }
@@ -1820,673 +1716,10 @@ function writePushMemory(projectRoot, agentCode, agentId, pushTasks, succeededFi
     }
     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 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`, which threads in the real `getFileDiff` and
- * `getItemLevelDiff` from `../utils/git.js`.
- */
-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 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 at
-                // ~L2675 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 users hit: `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.
-                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;
-}
-// NOTE: `buildToolPatchBody` was removed when the tool-modify branch above
-// switched to pushing on any `change.status === "modified"`. Its sole job
-// had been to gate the patch-tool task on a `tool.<field>` diff-path prefix,
-// which silently dropped every edit on flat-shape (no-wrapper) tool files.
-// See the inline comment in the modify branch (~L2688) for the full history.
-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 behavior here so every change reaches the platform.
-        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.js.map