aui-agent-builder 0.3.85 → 0.3.86

package/dist/commands/push.js

@@ -10,6 +10,7 @@ import { AUIClient, applyScopeLevel } from "../api-client/index.js";
 import { findAuiFiles, parseAuiFile } from "../utils/index.js";
 import { validate } from "./validate.js";
 import { getTracer, SpanStatusCode, setUserContext } from "../telemetry.js";
+import { trace } from "@opentelemetry/api";
 import { getItemLevelDiff } from "../utils/git.js";
 import { AuthenticationError, CLIError, ConfigError, ValidationError } from "../errors/index.js";
 import { StatusLine, Spinner, ErrorDisplay, Hint, } from "../ui/components/index.js";
@@ -23,20 +24,54 @@ function log(node) {
 }
 function startSpinner(label) {
     const inst = render(_jsx(Spinner, { label: label }));
+    let unmounted = false;
+    const safeUnmount = () => {
+        if (unmounted)
+            return;
+        unmounted = true;
+        inst.unmount();
+    };
     return {
         succeed(msg) {
-            inst.unmount();
+            safeUnmount();
             log(_jsx(StatusLine, { kind: "success", label: msg }));
         },
         fail(msg) {
-            inst.unmount();
+            safeUnmount();
             log(_jsx(StatusLine, { kind: "error", label: msg }));
         },
         stop() {
-            inst.unmount();
+            safeUnmount();
+        },
+        /**
+         * Internal: unconditionally unmount, no log line. Used by `withSpinner`
+         * to guarantee the spinner stops even when the wrapped body throws an
+         * exception that escapes the surrounding try/catch (which would
+         * otherwise leave a phantom spinner spinning forever).
+         */
+        _forceUnmount() {
+            safeUnmount();
         },
     };
 }
+/**
+ * Wrap a sync- or async-returning callback so the spinner ALWAYS unmounts,
+ * even on uncaught exceptions. The callback can call `.succeed()` / `.fail()`
+ * itself to render a final status line; otherwise the spinner just stops.
+ *
+ * This pattern eliminates the "phantom spinner" foot-gun where an exception
+ * thrown between `startSpinner(...)` and `.succeed/.fail` leaves the Ink
+ * render mounted forever — blocking the chat UI's "Still thinking…" state.
+ */
+async function withSpinner(label, fn) {
+    const spinner = startSpinner(label);
+    try {
+        return await fn(spinner);
+    }
+    finally {
+        spinner._forceUnmount();
+    }
+}
 /**
  * Push local agent configuration to the backend
  */
@@ -90,13 +125,47 @@ async function _push(pushSpan, agentCode, options = {}) {
             log(_jsx(StatusLine, { kind: "info", label: "Validating configuration..." }));
         else
             stderrLog("Validating configuration...");
-        const valid = await validate(projectRoot, { verbose: false });
+        // Wrap the validate call in its own span so a "stuck at validate"
+        // hang shows up clearly in Logfire as `aui.push.preflight.validate`
+        // with status = unset (still running) — instead of the parent
+        // `aui.push` span just sitting there with no clue why.
+        const validateTracer = getTracer();
+        const valid = await validateTracer.startActiveSpan("aui.push.preflight.validate", async (vSpan) => {
+            vSpan.setAttribute("push.preflight.step", "validate");
+            vSpan.setAttribute("push.preflight.skipValidation", false);
+            vSpan.setAttribute("push.preflight.force", options.force === true);
+            try {
+                const ok = await validate(projectRoot, { verbose: false });
+                vSpan.setAttribute("push.preflight.validate.ok", ok);
+                vSpan.setStatus({ code: SpanStatusCode.OK });
+                return ok;
+            }
+            catch (err) {
+                // validate() shouldn't throw under normal conditions, but if a
+                // schema fetch or git call inside it does, surface it here so
+                // we don't lose the error to the parent span's generic handler.
+                const msg = err instanceof Error ? err.message : String(err);
+                vSpan.setStatus({ code: SpanStatusCode.ERROR, message: msg });
+                vSpan.recordException(err instanceof Error ? err : new Error(msg));
+                throw err;
+            }
+            finally {
+                vSpan.end();
+            }
+        });
         if (!valid && !options.force) {
             pushSpan.setAttribute("push.exit_reason", "validation_failed");
+            pushSpan.addEvent("preflight.validation_rejected_push");
             throw new ValidationError("Push aborted due to validation errors.", {
                 suggestion: "Fix the errors above, or use --force to push anyway.",
             });
         }
+        if (!valid && options.force) {
+            pushSpan.addEvent("preflight.validation_failed_but_forced");
+        }
+    }
+    else {
+        pushSpan.addEvent("preflight.validation_skipped");
     }
     if (!json)
         log(_jsx(StatusLine, { kind: "info", label: "Pushing agent changes..." }));
@@ -284,12 +353,49 @@ async function _push(pushSpan, agentCode, options = {}) {
         // If the project has version_id in .auirc or --version-id is passed,
         // we validate it's a draft. If no version context exists, we auto-detect
         // available drafts. Push is rejected if no draft is found.
+        //
+        // Wrapped in an `aui.push.preflight.resolve-version` span so a hang on
+        // listAgents / listVersions / getVersion shows up clearly in Logfire
+        // instead of being lumped under the parent push span. This is the
+        // step that hits agent-management with up to 3 sequential calls.
         let prePushDraft = null;
         if (projectConfig.version_id || options.versionId) {
-            prePushDraft = await resolveVersionDraft(config, projectConfig, session, options.versionId);
+            const resolveTracer = getTracer();
+            prePushDraft = await resolveTracer.startActiveSpan("aui.push.preflight.resolve-version", async (rSpan) => {
+                rSpan.setAttribute("push.preflight.step", "resolve-version");
+                rSpan.setAttribute("push.preflight.has_explicit_version_id", !!options.versionId);
+                rSpan.setAttribute("push.preflight.has_auirc_version_id", !!projectConfig.version_id);
+                if (projectConfig.agent_id) {
+                    rSpan.setAttribute("push.preflight.network_id", projectConfig.agent_id);
+                }
+                try {
+                    const draft = await resolveVersionDraft(config, projectConfig, session, options.versionId);
+                    rSpan.setAttribute("push.preflight.resolved_version_id", draft.versionId);
+                    rSpan.setAttribute("push.preflight.resolved_version_label", draft.label);
+                    rSpan.setAttribute("push.preflight.resolved_agent_id", draft.agentId);
+                    rSpan.setStatus({ code: SpanStatusCode.OK });
+                    return draft;
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    rSpan.setStatus({ code: SpanStatusCode.ERROR, message: msg });
+                    rSpan.recordException(err instanceof Error ? err : new Error(msg));
+                    throw err;
+                }
+                finally {
+                    rSpan.end();
+                }
+            });
             agentSettingsParams.version_id = prePushDraft.versionId;
+            pushSpan.setAttribute("push.version_id", prePushDraft.versionId);
+            pushSpan.setAttribute("push.version_label", prePushDraft.label);
             log(_jsx(StatusLine, { kind: "info", label: `Pushing into draft version: ${prePushDraft.label}` }));
         }
+        else {
+            pushSpan.addEvent("preflight.no_draft_version_required", {
+                reason: "legacy push (no version_id in .auirc or --version-id flag)",
+            });
+        }
         const pushTasks = buildPushTasks(diff, fileData, projectRoot, getFileDiff);
         pushSpan.setAttribute("push.task_count", pushTasks.length);
         if (diff) {
@@ -418,7 +524,12 @@ async function _push(pushSpan, agentCode, options = {}) {
         //    JSON envelope, and the non-zero exit code (BFF contract: zero silent
         //    errors anywhere in the push pipeline).
         const kbResult = await pushKnowledgeHubs(projectRoot, projectConfig);
+        pushSpan.setAttribute("push.kb.ok", kbResult.ok);
+        pushSpan.setAttribute("push.kb.failures", kbResult.failures.length);
         if (!kbResult.ok) {
+            pushSpan.addEvent("kb.failures_folded_into_pushFailures", {
+                count: kbResult.failures.length,
+            });
             for (const kbFailure of kbResult.failures) {
                 failed++;
                 pushFailures.push(kbFailure);
@@ -450,10 +561,16 @@ async function _push(pushSpan, agentCode, options = {}) {
                 process.stdout.isTTY === true;
             if (!isInteractive) {
                 failed += authFailedTasks.length;
+                pushSpan.addEvent("auth.fallback.non_interactive_rejected", {
+                    failed_task_count: authFailedTasks.length,
+                });
                 throw new AuthenticationError(`Authentication failed for ${authFailedTasks.length} push task(s); cannot prompt for an API key (non-interactive session).`, {
                     suggestion: "Pass --api-key <key>, set AUI_AGENT_TOOLS_API_KEY, or run `aui login` to refresh credentials.",
                 });
             }
+            pushSpan.addEvent("auth.fallback.api_key_prompted", {
+                failed_task_count: authFailedTasks.length,
+            });
             log(_jsxs(Box, { flexDirection: "column", paddingX: 1, children: [_jsx(StatusLine, { kind: "warning", label: "Authentication failed. Your access token may not have permission." }), _jsx(Hint, { message: "You can provide an API key as a fallback. It will be saved to ~/.aui/agent-settings-key" })] }));
             const { key } = await inquirer.prompt([
                 {
@@ -466,6 +583,9 @@ async function _push(pushSpan, agentCode, options = {}) {
             if (key && key.trim()) {
                 saveAgentSettingsApiKey(key.trim());
                 client.setAgentSettingsApiKey(key.trim());
+                pushSpan.addEvent("auth.fallback.api_key_provided", {
+                    retrying_task_count: authFailedTasks.length,
+                });
                 log(_jsx(StatusLine, { kind: "success", label: "Key saved." }));
                 log(_jsx(Box, { paddingX: 1, children: _jsx(StatusLine, { kind: "info", label: `Retrying ${authFailedTasks.length} change(s) with API key...` }) }));
                 authFailed = false;
@@ -495,10 +615,16 @@ async function _push(pushSpan, agentCode, options = {}) {
             }
             else {
                 failed += authFailedTasks.length;
+                pushSpan.addEvent("auth.fallback.api_key_skipped", {
+                    uncovered_task_count: authFailedTasks.length,
+                });
             }
         }
         else if (authFailed && authFailedTasks.length > 0) {
             failed += authFailedTasks.length;
+            pushSpan.addEvent("auth.fallback.saved_key_still_failed", {
+                failed_task_count: authFailedTasks.length,
+            });
             log(_jsx(ErrorDisplay, { error: new AuthenticationError("Auth failed even with saved API key.", {
                     suggestion: "Try: rm ~/.aui/agent-settings-key",
                 }) }));
@@ -532,6 +658,7 @@ async function _push(pushSpan, agentCode, options = {}) {
         if (prePushDraft) {
             const SNAPSHOT_MAX_ATTEMPTS = 4;
             const SNAPSHOT_RETRY_BASE_MS = 1000;
+            const snapshotTracer = getTracer();
             for (let attempt = 1; attempt <= SNAPSHOT_MAX_ATTEMPTS; attempt++) {
                 snapshotAttempts = attempt;
                 const label = attempt === 1
@@ -540,26 +667,65 @@ async function _push(pushSpan, agentCode, options = {}) {
                 if (json)
                     stderrLog(label);
                 const snapshotSpinner = json ? null : startSpinner(label);
+                // Per-attempt span — each snapshot upload is a network call that can
+                // hang for minutes (large multipart upload). Surfacing each attempt
+                // separately in Logfire lets us see retry behavior, attempt latency,
+                // and which attempt finally succeeded. Logfire query:
+                //   `name:"aui.push.task.snapshot" AND attributes."snapshot.attempt":3`
+                // finds every push that needed a third try.
                 let attemptError;
-                try {
-                    const snapshotResult = await pushSnapshot(client, prePushDraft.agentId, prePushDraft.versionId, projectRoot, fileData);
-                    if (snapshotResult.success) {
-                        const okMsg = attempt === 1
-                            ? `Snapshot pushed (${fileData.length} file(s))`
-                            : `Snapshot pushed (${fileData.length} file(s), attempt ${attempt}/${SNAPSHOT_MAX_ATTEMPTS})`;
-                        if (snapshotSpinner)
-                            snapshotSpinner.succeed(okMsg);
-                        else
-                            stderrLog(okMsg);
-                        snapshotSucceeded = true;
-                        snapshotError = undefined;
-                        break;
+                const attemptResolved = await snapshotTracer.startActiveSpan("aui.push.task.snapshot", async (snapSpan) => {
+                    snapSpan.setAttribute("push.task.type", "snapshot");
+                    snapSpan.setAttribute("push.task.label", label);
+                    snapSpan.setAttribute("snapshot.attempt", attempt);
+                    snapSpan.setAttribute("snapshot.max_attempts", SNAPSHOT_MAX_ATTEMPTS);
+                    snapSpan.setAttribute("snapshot.file_count", fileData.length);
+                    snapSpan.setAttribute("snapshot.agent_id", prePushDraft.agentId);
+                    snapSpan.setAttribute("snapshot.version_id", prePushDraft.versionId);
+                    try {
+                        const snapshotResult = await pushSnapshot(client, prePushDraft.agentId, prePushDraft.versionId, projectRoot, fileData);
+                        if (snapshotResult.success) {
+                            snapSpan.setStatus({ code: SpanStatusCode.OK });
+                            snapSpan.setAttribute("snapshot.outcome", "success");
+                            return { ok: true, error: undefined };
+                        }
+                        const errMsg = snapshotResult.error || "Unknown snapshot error";
+                        snapSpan.setStatus({ code: SpanStatusCode.ERROR, message: errMsg });
+                        snapSpan.setAttribute("snapshot.outcome", "failed");
+                        snapSpan.setAttribute("push.task.error", errMsg);
+                        if (attempt < SNAPSHOT_MAX_ATTEMPTS) {
+                            snapSpan.addEvent("snapshot.retry_will_follow", {
+                                next_attempt: attempt + 1,
+                                backoff_ms: SNAPSHOT_RETRY_BASE_MS * Math.pow(2, attempt - 1),
+                            });
+                        }
+                        return { ok: false, error: errMsg };
                     }
-                    attemptError = snapshotResult.error || "Unknown snapshot error";
-                }
-                catch (error) {
-                    attemptError = error instanceof Error ? error.message : String(error);
+                    catch (error) {
+                        const errMsg = error instanceof Error ? error.message : String(error);
+                        snapSpan.setStatus({ code: SpanStatusCode.ERROR, message: errMsg });
+                        snapSpan.recordException(error instanceof Error ? error : new Error(errMsg));
+                        snapSpan.setAttribute("snapshot.outcome", "exception");
+                        snapSpan.setAttribute("push.task.error", errMsg);
+                        return { ok: false, error: errMsg };
+                    }
+                    finally {
+                        snapSpan.end();
+                    }
+                });
+                if (attemptResolved.ok) {
+                    const okMsg = attempt === 1
+                        ? `Snapshot pushed (${fileData.length} file(s))`
+                        : `Snapshot pushed (${fileData.length} file(s), attempt ${attempt}/${SNAPSHOT_MAX_ATTEMPTS})`;
+                    if (snapshotSpinner)
+                        snapshotSpinner.succeed(okMsg);
+                    else
+                        stderrLog(okMsg);
+                    snapshotSucceeded = true;
+                    snapshotError = undefined;
+                    break;
                 }
+                attemptError = attemptResolved.error;
                 snapshotError = attemptError;
                 const isLast = attempt === SNAPSHOT_MAX_ATTEMPTS;
                 const failMsg = isLast
@@ -617,13 +783,27 @@ async function _push(pushSpan, agentCode, options = {}) {
                 if (filesSafeToCommit.length > 0) {
                     commitBaselineFiles(projectRoot, filesSafeToCommit, `pushed ${succeeded} change(s) (${failedFiles.size} file(s) held back due to per-task failures)`);
                     baselineUpdated = true;
+                    pushSpan.addEvent("baseline.partial_commit", {
+                        committed_files: filesSafeToCommit.length,
+                        held_back_files: failedFiles.size,
+                    });
+                }
+                else {
+                    pushSpan.addEvent("baseline.fully_held_back", {
+                        failed_files: failedFiles.size,
+                    });
                 }
             }
             else if (failed === 0) {
                 commitBaseline(projectRoot, "pushed changes");
                 baselineUpdated = true;
+                pushSpan.addEvent("baseline.full_commit");
             }
         }
+        else {
+            pushSpan.addEvent("baseline.skipped_due_to_snapshot_failure");
+        }
+        pushSpan.setAttribute("push.baseline_updated", baselineUpdated);
         log(_jsx(PushFinalSummary, { succeeded: succeeded, failed: failed, baselineUpdated: baselineUpdated, logDir: logRelPath, memoryPath: memoryPath, snapshotStatus: snapshotStatus, snapshotError: snapshotError }));
         if (failed > 0) {
             log(_jsxs(Box, { flexDirection: "column", paddingX: 1, children: [_jsx(StatusLine, { kind: "warning", label: `${failed} entity change(s) failed to push to DB.` }), pushFailures.map((f) => (_jsxs(Box, { flexDirection: "column", marginLeft: 2, children: [_jsxs(Text, { color: "red", children: ["  ", icons.error, " ", f.label] }), _jsxs(Text, { color: colors.muted, children: ["    Error: ", f.error] }), f.file && _jsxs(Text, { color: colors.muted, children: ["    File: ", f.file] })] }, f.label))), _jsxs(Box, { marginTop: 1, children: [_jsx(Text, { color: colors.info, bold: true, children: "What to do next: " }), _jsxs(Text, { color: colors.muted, children: ["Fix the issues above and re-run ", _jsx(Text, { bold: true, children: "aui push" }), " to retry the failed changes."] })] })] }));
@@ -1029,26 +1209,50 @@ async function pushKnowledgeHubs(projectRoot, projectConfig) {
                     log(_jsx(Box, { paddingX: 1, children: _jsx(StatusLine, { kind: "warning", label: `Cannot delete "${kbName}" — no knowledge_base_id stored. Push the KB first, then delete.` }) }));
                     continue;
                 }
-                try {
-                    await kbViewClient.deleteKnowledgeBase(kbId, scope, kbName);
-                    log(_jsx(Box, { paddingX: 1, children: _jsx(StatusLine, { kind: "success", label: `Deleted: ${kbName}` }) }));
-                }
-                catch (delErr) {
-                    // Per-KB error: count it, keep going so partial work shows up.
-                    if (isNotFoundError(delErr)) {
-                        log(_jsx(Box, { paddingX: 1, children: _jsx(StatusLine, { kind: "success", label: `Deleted: ${kbName} (already absent)` }) }));
+                // Per-KB delete in its own span so each one shows up in Logfire as
+                // `aui.push.task.kb-delete` with status, kb name, kb id, and error
+                // body. Same observability shape as agent-settings entity tasks.
+                const kbDelTracer = getTracer();
+                await kbDelTracer.startActiveSpan("aui.push.task.kb-delete", async (span) => {
+                    span.setAttribute("push.task.type", "kb-delete");
+                    span.setAttribute("push.task.label", `Delete knowledge base: ${kbName}`);
+                    span.setAttribute("push.task.file", `knowledge-hubs/${kbDirName}/kb.json`);
+                    span.setAttribute("push.task.kb_id", kbId);
+                    span.setAttribute("push.task.kb_name", kbName);
+                    try {
+                        await kbViewClient.deleteKnowledgeBase(kbId, scope, kbName);
+                        span.setStatus({ code: SpanStatusCode.OK });
+                        log(_jsx(Box, { paddingX: 1, children: _jsx(StatusLine, { kind: "success", label: `Deleted: ${kbName}` }) }));
                     }
-                    else {
-                        kbDeleteSucceeded = false;
-                        const errMsg = delErr instanceof Error ? delErr.message : String(delErr);
-                        failures.push({
-                            label: `Delete knowledge base: ${kbName}`,
-                            file: `knowledge-hubs/${kbDirName}/kb.json`,
-                            error: errMsg,
-                        });
-                        log(_jsx(Box, { paddingX: 1, children: _jsx(StatusLine, { kind: "error", label: `Failed to delete "${kbName}": ${errMsg}` }) }));
+                    catch (delErr) {
+                        // Per-KB error: count it, keep going so partial work shows up.
+                        if (isNotFoundError(delErr)) {
+                            span.setStatus({ code: SpanStatusCode.OK });
+                            span.addEvent("fallback.delete_404_already_absent");
+                            span.setAttribute("push.task.fallback", "delete_404_already_absent");
+                            log(_jsx(Box, { paddingX: 1, children: _jsx(StatusLine, { kind: "success", label: `Deleted: ${kbName} (already absent)` }) }));
+                        }
+                        else {
+                            kbDeleteSucceeded = false;
+                            const errMsg = delErr instanceof Error ? delErr.message : String(delErr);
+                            span.setStatus({ code: SpanStatusCode.ERROR, message: errMsg });
+                            span.recordException(delErr instanceof Error ? delErr : new Error(errMsg));
+                            span.setAttribute("push.task.error", errMsg);
+                            if (delErr.statusCode) {
+                                span.setAttribute("push.task.error_status_code", delErr.statusCode);
+                            }
+                            failures.push({
+                                label: `Delete knowledge base: ${kbName}`,
+                                file: `knowledge-hubs/${kbDirName}/kb.json`,
+                                error: errMsg,
+                            });
+                            log(_jsx(Box, { paddingX: 1, children: _jsx(StatusLine, { kind: "error", label: `Failed to delete "${kbName}": ${errMsg}` }) }));
+                        }
                     }
-                }
+                    finally {
+                        span.end();
+                    }
+                });
             }
             if (kbDeleteSucceeded) {
                 deleteSpinner.succeed(`${deletedKBDirs.length} knowledge base(s) deleted`);
@@ -1085,41 +1289,64 @@ 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) {
-                    try {
-                        const importResult = await kbViewClient.importFiles({
-                            files: supportedFiles,
-                            scope,
-                            created_by: userId,
-                            knowledge_base_name: kbData.name,
-                            knowledge_base_description: kbData.description,
-                        });
-                        if (importResult.knowledge_base_id) {
-                            const kbJsonPath = path.join(kbDir, "kb.json");
-                            try {
-                                const raw = JSON.parse(fs.readFileSync(kbJsonPath, "utf-8"));
-                                raw.knowledge_base_id = importResult.knowledge_base_id;
-                                fs.writeFileSync(kbJsonPath, JSON.stringify(raw, null, 2) + "\n");
-                            }
-                            catch (writeErr) {
-                                // kb.json id write fail is non-fatal but tell the user so the
-                                // next push doesn't surprise them with "no knowledge_base_id stored".
-                                if (process.env.AUI_DEBUG) {
-                                    console.warn(`[debug] failed to write knowledge_base_id back to ${kbJsonPath}:`, writeErr);
+                    // Per-KB upload in its own span — Logfire query
+                    // `name:"aui.push.task.kb-upload" AND status_code:ERROR` finds
+                    // every KB push failure across all agents.
+                    const kbUpTracer = getTracer();
+                    await kbUpTracer.startActiveSpan("aui.push.task.kb-upload", async (span) => {
+                        span.setAttribute("push.task.type", "kb-upload");
+                        span.setAttribute("push.task.label", `Push knowledge base: ${kbData.name || kbDirName}`);
+                        span.setAttribute("push.task.file", `knowledge-hubs/${kbDirName}/kb.json`);
+                        span.setAttribute("push.task.kb_name", kbData.name || kbDirName);
+                        span.setAttribute("push.task.file_count", supportedFiles.length);
+                        try {
+                            const importResult = await kbViewClient.importFiles({
+                                files: supportedFiles,
+                                scope,
+                                created_by: userId,
+                                knowledge_base_name: kbData.name,
+                                knowledge_base_description: kbData.description,
+                            });
+                            span.setStatus({ code: SpanStatusCode.OK });
+                            if (importResult.knowledge_base_id) {
+                                span.setAttribute("push.task.kb_id", importResult.knowledge_base_id);
+                                const kbJsonPath = path.join(kbDir, "kb.json");
+                                try {
+                                    const raw = JSON.parse(fs.readFileSync(kbJsonPath, "utf-8"));
+                                    raw.knowledge_base_id = importResult.knowledge_base_id;
+                                    fs.writeFileSync(kbJsonPath, JSON.stringify(raw, null, 2) + "\n");
+                                }
+                                catch (writeErr) {
+                                    // kb.json id write fail is non-fatal but tell the user so the
+                                    // next push doesn't surprise them with "no knowledge_base_id stored".
+                                    span.addEvent("kb_id_writeback_failed");
+                                    if (process.env.AUI_DEBUG) {
+                                        console.warn(`[debug] failed to write knowledge_base_id back to ${kbJsonPath}:`, writeErr);
+                                    }
+                                    log(_jsx(Box, { paddingX: 1, children: _jsx(StatusLine, { kind: "warning", label: `Could not persist knowledge_base_id back to ${path.basename(kbJsonPath)} — re-import or run \`aui pull\` to recover.` }) }));
                                 }
-                                log(_jsx(Box, { paddingX: 1, children: _jsx(StatusLine, { kind: "warning", label: `Could not persist knowledge_base_id back to ${path.basename(kbJsonPath)} — re-import or run \`aui pull\` to recover.` }) }));
                             }
                         }
-                    }
-                    catch (uploadErr) {
-                        hadUploadFailure = true;
-                        const errMsg = uploadErr instanceof Error ? uploadErr.message : String(uploadErr);
-                        failures.push({
-                            label: `Push knowledge base: ${kbData.name || kbDirName}`,
-                            file: `knowledge-hubs/${kbDirName}/kb.json`,
-                            error: errMsg,
-                        });
-                        log(_jsx(Box, { paddingX: 1, children: _jsx(StatusLine, { kind: "error", label: `Failed to push "${kbData.name || kbDirName}": ${errMsg}` }) }));
-                    }
+                        catch (uploadErr) {
+                            hadUploadFailure = true;
+                            const errMsg = uploadErr instanceof Error ? uploadErr.message : String(uploadErr);
+                            span.setStatus({ code: SpanStatusCode.ERROR, message: errMsg });
+                            span.recordException(uploadErr instanceof Error ? uploadErr : new Error(errMsg));
+                            span.setAttribute("push.task.error", errMsg);
+                            if (uploadErr.statusCode) {
+                                span.setAttribute("push.task.error_status_code", uploadErr.statusCode);
+                            }
+                            failures.push({
+                                label: `Push knowledge base: ${kbData.name || kbDirName}`,
+                                file: `knowledge-hubs/${kbDirName}/kb.json`,
+                                error: errMsg,
+                            });
+                            log(_jsx(Box, { paddingX: 1, children: _jsx(StatusLine, { kind: "error", label: `Failed to push "${kbData.name || kbDirName}": ${errMsg}` }) }));
+                        }
+                        finally {
+                            span.end();
+                        }
+                    });
                 }
             }
             if (hadUploadFailure) {
@@ -1622,6 +1849,32 @@ function isTransient5xx(err) {
         ?? 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
@@ -1640,6 +1893,11 @@ async function withTransientRetry(label, fn) {
         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();
     }
@@ -1671,6 +1929,7 @@ async function _executePushTask(client, params, task) {
                         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;
@@ -1689,6 +1948,7 @@ async function _executePushTask(client, params, task) {
                         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;
@@ -1704,6 +1964,7 @@ async function _executePushTask(client, params, task) {
                         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;
@@ -1727,6 +1988,7 @@ async function _executePushTask(client, params, task) {
                         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;
@@ -1742,6 +2004,7 @@ async function _executePushTask(client, params, task) {
                         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;
@@ -1757,6 +2020,7 @@ async function _executePushTask(client, params, task) {
                         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;
@@ -1772,6 +2036,7 @@ async function _executePushTask(client, params, task) {
                         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;
@@ -1787,6 +2052,7 @@ async function _executePushTask(client, params, task) {
                         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;
@@ -1802,6 +2068,7 @@ async function _executePushTask(client, params, task) {
                         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;
@@ -1817,6 +2084,7 @@ async function _executePushTask(client, params, task) {
                         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;
@@ -1832,6 +2100,7 @@ async function _executePushTask(client, params, task) {
                         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;
@@ -1847,6 +2116,7 @@ async function _executePushTask(client, params, task) {
                         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;