@timurproko/a1 0.1.8-dev.299 → 0.1.8-dev.332

package/dist/integrations/pi/engine/adapter.js

@@ -7,12 +7,18 @@ import { dirname, join, resolve } from "node:path";
 import { promisify } from "node:util";
 import { PRODUCT_IDENTITY } from "../../../product-identity.js";
 import { configureOwnedHttpDispatcher } from "./http-dispatcher.js";
+import { readPinnedCommandChangelog } from "./changelog.js";
 import { copyToClipboard, CredentialSynchronizationError, DefaultPackageManager, getAgentDir, ProjectTrustStore, SessionManager, VERSION, } from "@earendil-works/pi-coding-agent";
 import { OWNED_UI_EXTENSION_CONTRACT_VERSION, OWNED_UI_EXTENSION_RENDER_CALLBACKS, OWNED_UI_EXTENSION_UI_CALLBACKS, OWNED_UI_EXTENSION_UI_PROPERTIES, CONTEXTUAL_PROMPT_SUGGESTION_INSTRUCTION, assertOwnedUiCommand, assertOwnedUiExtensionUiPort, assertOwnedUiPromptSuggestionRequest, assertOwnedUiPromptSuggestionResult, assertOwnedUiSnapshot, normalizePromptSuggestionCandidate, } from "../../../contracts/owned-ui/index.js";
 import { PINNED_PI_SETTINGS_CALLBACKS, PINNED_PI_WORKFLOW_COMMAND_NAMES, } from "./workflows.js";
 import { createPiRuntimeIntegration } from "./runtime-integration.js";
 import { PiSessionCommandIntegration } from "./session-integration.js";
 import { PiSettingsIntegration } from "./settings-integration.js";
+import { PendingEngineDelivery } from "./pending-delivery.js";
+/** Explicit flush failure when required delivery was interrupted rather than completed. */
+export class EngineDeliveryError extends Error {
+    constructor() { super("Engine delivery did not complete"); this.name = "EngineDeliveryError"; }
+}
 const execFileAsync = promisify(execFile);
 /**
  * Engine events delivered before the queue hands the event loop a turn. Small enough
@@ -23,7 +29,6 @@ const execFileAsync = promisify(execFile);
 // be expensive in long sessions; a larger synchronous batch starves terminal
 // input and makes an in-progress mouse selection appear frozen.
 const EVENT_DELIVERY_BATCH = 1;
-const TOOL_UPDATE_COALESCE_MS = 50;
 const AUTH_REFRESH_TIMEOUT_MS = 15_000;
 // Provenance: Pi 0.84.2 core/model-resolver.ts defaultModelPerProvider.
 const PINNED_DEFAULT_MODEL_BY_PROVIDER = Object.freeze({
@@ -86,7 +91,7 @@ export class PiEngineAdapter {
     #sessionForkPrompt;
     #workflowHost;
     #workflowInteraction;
-    #listeners = new Set();
+    #listeners = new Map();
     #runtime;
     #session;
     #unsubscribe;
@@ -102,6 +107,7 @@ export class PiEngineAdapter {
         submitEnabled: false,
     };
     #sessionGeneration = 0;
+    #sessionBindingGeneration = 0;
     #status = {
         title: "Pi",
         workingMessage: null,
@@ -120,14 +126,20 @@ export class PiEngineAdapter {
     #messageFallbackIds = new Map();
     #toolBlockIds = new Map();
     #transcriptImageAssets = new Map();
-    #pendingToolUpdates = new Map();
-    #toolUpdateFlush = null;
     #usageCache;
     #nextBlockSequence = 0;
     #diagnostics = [];
-    #eventQueue = [];
+    #eventQueue = new PendingEngineDelivery();
     #eventQueueProcessing;
-    #droppedEventCount = 0;
+    #overload;
+    #overloads = 0;
+    #deliveryFailed = false;
+    #admissionStopped = false;
+    #runningCommands = 0;
+    #invalidatedEvents = 0;
+    #pendingCommands = new Map();
+    #reservedOutcomes = new Map();
+    #pendingWorkflows = new Set();
     #agentRunActive = false;
     #agentRunSequence = 0;
     #assistantResponseSequence = 0;
@@ -170,6 +182,8 @@ export class PiEngineAdapter {
     get sessionGeneration() {
         return this.#sessionGeneration;
     }
+    /** Actual session replacements, excluding delivery-only invalidation of callbacks. */
+    get sessionBindingGeneration() { return this.#sessionBindingGeneration; }
     get cwd() {
         return this.#runtime?.cwd ?? this.#cwd;
     }
@@ -208,7 +222,7 @@ export class PiEngineAdapter {
         const session = this.#session;
         const runtime = this.#runtime;
         const activeModel = this.#activeModel;
-        if (this.#disposed || session === undefined || runtime === undefined || request.signal.aborted
+        if (this.#disposed || this.#overload !== undefined || this.#admissionStopped || session === undefined || runtime === undefined || request.signal.aborted
             || identity.sessionId !== this.#sessionId
             || identity.sessionGeneration !== this.#sessionGeneration
             || identity.runSequence !== this.#agentRunSequence
@@ -289,6 +303,8 @@ export class PiEngineAdapter {
             hardwareCursor: runtime.services.settingsManager?.getShowHardwareCursor?.() ?? this.#terminal.hardwareCursor,
         };
         runtime.setRebindSession(async (session) => {
+            if (this.#overload !== undefined || this.#admissionStopped || this.#disposed)
+                return;
             this.#bindSession(session);
             this.#emitView();
         });
@@ -308,14 +324,22 @@ export class PiEngineAdapter {
         if (!settingsManager || typeof settingsManager.getLastChangelogVersion !== "function"
             || typeof settingsManager.setLastChangelogVersion !== "function")
             return;
-        if (settingsManager.getLastChangelogVersion() === VERSION)
+        if ((this.#session?.messages.length ?? 0) > 0)
+            return;
+        const lastVersion = settingsManager.getLastChangelogVersion();
+        if (lastVersion === VERSION)
             return;
-        const markdown = await this.#workflowHost.readChangelog().catch(() => "");
+        if (!lastVersion) {
+            settingsManager.setLastChangelogVersion(VERSION);
+            await settingsManager.flush();
+            return;
+        }
+        const markdown = await this.#workflowHost.readChangelog(lastVersion).catch(() => "");
         if (markdown.trim().length > 0) {
             this.#addDiagnostic("info", settingsManager.getCollapseChangelog() ? "changelog-collapsed" : "changelog-expanded", markdown, true);
+            settingsManager.setLastChangelogVersion(VERSION);
+            await settingsManager.flush();
         }
-        settingsManager.setLastChangelogVersion(VERSION);
-        await settingsManager.flush();
     }
     async #announcePackageUpdates(settingsManager) {
         if (process.env.PI_OFFLINE)
@@ -334,14 +358,24 @@ export class PiEngineAdapter {
         this.#emitView();
     }
     onEvent(listener) {
-        this.#listeners.add(listener);
-        listener(this.#event({ type: "session-view", view: this.view() }));
+        const initial = this.#event({ type: "session-view", view: this.view() });
+        this.#listeners.set(listener, initial.sequence);
+        listener(initial);
         return () => this.#listeners.delete(listener);
     }
+    /** Developer-only pressure evidence; never mirrored into visible diagnostic/status arrays. */
+    deliveryDiagnostics() {
+        return { ...this.#eventQueue.diagnostics(), overloads: this.#overloads, recovering: this.#overload !== undefined,
+            pendingCommands: this.#pendingCommands.size + this.#pendingWorkflows.size, reservedOutcomes: this.#reservedOutcomes.size, invalidatedEvents: this.#invalidatedEvents };
+    }
     async flushEvents() {
-        this.#flushPendingToolUpdates();
+        const failed = this.#deliveryFailed;
         while (this.#eventQueueProcessing)
             await this.#eventQueueProcessing;
+        if (failed || this.#deliveryFailed || this.#disposed && this.#lifecycle !== "stopped") {
+            this.#deliveryFailed = false;
+            throw new EngineDeliveryError();
+        }
     }
     nonVisualResources() {
         const loader = this.#runtime?.services.resourceLoader;
@@ -877,6 +911,17 @@ export class PiEngineAdapter {
         }));
         return { title: `Select authentication method for ${providerName}:`, options };
     }
+    pinnedAmbientAuthentication(selection) {
+        if (!selection.startsWith("api_key:"))
+            return null;
+        const providerId = selection.slice("api_key:".length);
+        const provider = this.#runtime?.services.modelRuntime.getProvider?.(providerId);
+        const method = dynamicObject(dynamicObject(provider, "auth"), "apiKey");
+        if (!method || typeof method.login === "function")
+            return null;
+        const providerName = stringProperty(provider, "name") ?? providerId;
+        return { providerId, providerName, title: `${providerName} setup`, message: `${stringProperty(method, "name") ?? "Authentication"} is configured outside pi.` };
+    }
     pinnedLogoutOptions() {
         return this.#logoutOptions();
     }
@@ -957,9 +1002,16 @@ export class PiEngineAdapter {
     pinnedMessageRenderer(customType) {
         return this.#requireWorkflowSession().extensionRunner?.getMessageRenderer?.(customType);
     }
+    pinnedShortcutDescriptions(bindings) {
+        const shortcuts = this.#requireWorkflowSession().extensionRunner?.getShortcuts?.(bindings);
+        return shortcuts === undefined ? [] : [...shortcuts].map(([key, shortcut]) => ({ key, description: shortcut.description ?? shortcut.extensionPath }));
+    }
     pinnedToolDefinition(toolName) {
         return this.#requireWorkflowSession().extensionRunner?.getToolDefinition?.(toolName);
     }
+    async copyWorkflowText(text) {
+        await this.#workflowHost.copyText(text);
+    }
     clearQueuedWorkflows() {
         const session = this.#requireWorkflowSession();
         const result = session.clearQueue?.();
@@ -992,14 +1044,40 @@ export class PiEngineAdapter {
             return workflowResult("settings", "failed", error instanceof Error ? error.message : String(error));
         }
     }
+    reloadBlockedResult() {
+        const session = this.#requireWorkflowSession();
+        if (session.isStreaming)
+            return workflowResult("reload", "failed", "Wait for the current response to finish before reloading.", undefined, "warning");
+        if (session.isCompacting)
+            return workflowResult("reload", "failed", "Wait for compaction to finish before reloading.", undefined, "warning");
+        return null;
+    }
     async executeWorkflow(request) {
+        const cancelled = workflowResult(request.command, "cancelled", "", undefined, "silent");
+        if (this.#overload !== undefined || this.#admissionStopped || this.#disposed
+            || this.#pendingCommands.size + this.#pendingWorkflows.size >= 32)
+            return cancelled;
+        let cancel;
+        const cancellation = new Promise(resolve => { cancel = () => resolve(cancelled); });
+        const pending = { command: request.command, cancel };
+        this.#pendingWorkflows.add(pending);
+        this.#runningCommands++;
+        const operation = this.#runWorkflow(request).finally(() => { this.#runningCommands--; });
+        try {
+            return await Promise.race([operation, cancellation]);
+        }
+        finally {
+            this.#pendingWorkflows.delete(pending);
+        }
+    }
+    async #runWorkflow(request) {
         try {
             return await this.#performWorkflow(request);
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
             const contextualMessage = request.command === "export"
-                ? `Failed to export session: ${message}`
+                ? `Failed to export session: ${errorMessage(error, "Unknown error")}`
                 : request.command === "import"
                     ? `Failed to import session: ${message}`
                     : request.command === "new"
@@ -1059,6 +1137,9 @@ export class PiEngineAdapter {
         if (this.#disposed || !this.#runtime || !this.#session) {
             return this.#finishCommand(command, "rejected", "engine adapter is not running");
         }
+        // Invariant: the bounded out-of-band cancellation path has one slot per admitted command.
+        if (this.#overload !== undefined || this.#admissionStopped || this.#pendingCommands.size + this.#pendingWorkflows.size >= 32)
+            return { outcome: "rejected", diagnostic: null };
         const existing = this.#completedCommands.get(command.correlationId);
         if (existing)
             return existing;
@@ -1066,33 +1147,64 @@ export class PiEngineAdapter {
             return this.#finishCommand(command, "rejected", "duplicate engine command correlation id");
         }
         this.#activeCommandIds.push(command.correlationId);
-        this.#emitEvent({
-            type: "command-outcome",
-            correlationId: command.correlationId,
-            outcome: "accepted",
-            diagnostic: null,
+        const generation = this.#sessionGeneration;
+        let cancelled = false;
+        const cancellation = new Promise(resolve => {
+            this.#pendingCommands.set(command.correlationId, { type: command.type, cancel: () => {
+                    if (cancelled)
+                        return;
+                    cancelled = true;
+                    resolve(this.#recordCommand(command, "failed", null));
+                } });
         });
+        this.#emitEvent({ type: "command-outcome", correlationId: command.correlationId, outcome: "accepted", diagnostic: null });
+        const operation = async () => {
+            try {
+                if (cancelled)
+                    return { outcome: "failed", diagnostic: null };
+                this.#runningCommands++;
+                try {
+                    await this.#perform(command);
+                }
+                finally {
+                    this.#runningCommands--;
+                }
+                if (cancelled)
+                    return { outcome: "failed", diagnostic: null };
+                if (generation === this.#sessionGeneration)
+                    this.#emitView();
+                if (cancelled)
+                    return { outcome: "failed", diagnostic: null };
+                return this.#recordCommand(command, "completed", null);
+            }
+            catch (error) {
+                if (cancelled)
+                    return { outcome: "failed", diagnostic: null };
+                const diagnostic = error instanceof Error ? error.message : String(error);
+                this.#addDiagnostic("error", "engine-command", diagnostic, true);
+                if (generation === this.#sessionGeneration)
+                    this.#emitView();
+                return this.#recordCommand(command, "failed", diagnostic);
+            }
+        };
         try {
-            await this.#perform(command);
-            this.#emitView();
-            return this.#recordCommand(command, "completed", null);
+            return await Promise.race([operation(), cancellation]);
         }
-        catch (error) {
-            const diagnostic = error instanceof Error ? error.message : String(error);
-            this.#addDiagnostic("error", "engine-command", diagnostic, true);
-            this.#emitView();
-            return this.#recordCommand(command, "failed", diagnostic);
+        finally {
+            this.#pendingCommands.delete(command.correlationId);
         }
     }
     async dispose() {
         if (this.#disposed)
             return;
         this.#disposed = true;
-        if (this.#toolUpdateFlush !== null) {
-            clearTimeout(this.#toolUpdateFlush);
-            this.#toolUpdateFlush = null;
-        }
-        this.#pendingToolUpdates.clear();
+        for (const pending of this.#pendingCommands.values())
+            if (pending.type !== "shutdown")
+                pending.cancel();
+        // Compatibility: /quit owns normal disposal and must report its actual completion, not cancel itself.
+        for (const pending of this.#pendingWorkflows)
+            if (pending.command !== "quit")
+                pending.cancel();
         this.#transcriptImageAssets.clear();
         this.#extensionBound = false;
         this.#extensionUi = undefined;
@@ -1105,7 +1217,13 @@ export class PiEngineAdapter {
         this.#lifecycle = "stopped";
         this.#emitEvent({ type: "session-lifecycle", lifecycle: "stopped", reason: null });
         this.#emitView();
-        await this.flushEvents();
+        try {
+            await this.flushEvents();
+        }
+        catch (error) {
+            if (!(error instanceof EngineDeliveryError))
+                throw error;
+        }
     }
     async #performWorkflow(request) {
         const session = this.#requireWorkflowSession();
@@ -1133,8 +1251,18 @@ export class PiEngineAdapter {
                     : [...(runtime.services.modelRuntime.getAvailableSnapshot?.() ?? [])];
                 let model = findExactWorkflowModel(reference, availableModels);
                 const messages = [];
+                const generation = this.#sessionGeneration;
+                const current = () => !this.#disposed && generation === this.#sessionGeneration;
+                const publish = (message) => {
+                    if (!current())
+                        return;
+                    if (this.#workflowInteraction.publish)
+                        this.#workflowInteraction.publish(message);
+                    else
+                        messages.push(message);
+                };
                 if (model === undefined && scopedModels.length === 0) {
-                    messages.push({ kind: "status", message: "Refreshing model catalogs…" });
+                    publish({ kind: "status", message: "Refreshing model catalogs…" });
                     const controller = new AbortController();
                     let timedOut = false;
                     const timeout = setTimeout(() => {
@@ -1144,14 +1272,14 @@ export class PiEngineAdapter {
                     try {
                         const refreshed = await runtime.services.modelRuntime.refresh?.({ signal: controller.signal });
                         if (isRecord(refreshed) && refreshed.aborted === true && timedOut) {
-                            messages.push({ kind: "warning", message: "Model refresh timed out; searching cached models." });
+                            publish({ kind: "warning", message: "Model refresh timed out; searching cached models." });
                         }
                         else if (isRecord(refreshed) && refreshed.errors instanceof Map && refreshed.errors.size > 0) {
-                            messages.push({ kind: "warning", message: `Could not refresh ${[...refreshed.errors.keys()].join(", ")}; searching cached models.` });
+                            publish({ kind: "warning", message: `Could not refresh ${[...refreshed.errors.keys()].join(", ")}; searching cached models.` });
                         }
                     }
                     catch (error) {
-                        messages.push({
+                        publish({
                             kind: "warning",
                             message: timedOut
                                 ? "Model refresh timed out; searching cached models."
@@ -1164,13 +1292,25 @@ export class PiEngineAdapter {
                     availableModels = [...(runtime.services.modelRuntime.getAvailableSnapshot?.() ?? [])];
                     model = findExactWorkflowModel(reference, availableModels);
                 }
+                if (!current())
+                    return workflowResult(request.command, "cancelled", "Model selection cancelled", undefined, "silent");
                 if (model === undefined) {
                     return {
                         ...workflowResult(request.command, "requires-selection", "Select a model", reference, "silent"),
                         ...(messages.length === 0 ? {} : { messages: Object.freeze(messages) }),
                     };
                 }
-                await session.setModel(model);
+                try {
+                    await session.setModel(model);
+                }
+                catch (error) {
+                    if (!current())
+                        return workflowResult(request.command, "cancelled", "Model selection cancelled", undefined, "silent");
+                    const failure = { kind: "error", message: error instanceof Error ? error.message : String(error) };
+                    return workflowResult(request.command, "failed", failure.message, undefined, "error", messages.length === 0 ? undefined : [...messages, failure]);
+                }
+                if (!current())
+                    return workflowResult(request.command, "cancelled", "Model selection cancelled", undefined, "silent");
                 const providerId = stringProperty(model, "provider") ?? "unknown";
                 const modelId = stringProperty(model, "id") ?? reference;
                 this.#activeModel = { providerId, modelId, displayName: stringProperty(model, "name") ?? modelId };
@@ -1226,9 +1366,8 @@ export class PiEngineAdapter {
                 const signal = request.signal;
                 if (signal?.aborted)
                     return workflowResult(request.command, "cancelled", "Share cancelled", undefined, "status");
-                let auth;
                 try {
-                    auth = await this.#workflowHost.runCommand("gh", ["auth", "status"], signal === undefined ? undefined : { signal });
+                    await this.#workflowHost.runCommand("gh", ["auth", "status"], signal === undefined ? undefined : { signal });
                 }
                 catch (error) {
                     if (signal?.aborted || isAbortError(error))
@@ -1238,9 +1377,6 @@ export class PiEngineAdapter {
                         : "GitHub CLI is not logged in. Run 'gh auth login' first.";
                     return workflowResult(request.command, "failed", message);
                 }
-                if (auth.stderr && !auth.stdout) {
-                    return workflowResult(request.command, "failed", "GitHub CLI is not logged in. Run 'gh auth login' first.");
-                }
                 const temporary = join(tmpdir(), `${PRODUCT_IDENTITY.filesystem.temporaryPrefix}pi-session-${process.pid}.html`);
                 try {
                     try {
@@ -1258,13 +1394,10 @@ export class PiEngineAdapter {
                     catch (error) {
                         if (signal?.aborted || isAbortError(error))
                             return workflowResult(request.command, "cancelled", "Share cancelled", undefined, "status");
-                        return workflowResult(request.command, "failed", `Failed to create gist: ${errorMessage(error, "Unknown error")}`);
+                        return workflowResult(request.command, "failed", `Failed to create gist: ${shareCommandFailureDetail(error)}`);
                     }
                     if (signal?.aborted)
                         return workflowResult(request.command, "cancelled", "Share cancelled", undefined, "status");
-                    if (gist.stderr && !gist.stdout) {
-                        return workflowResult(request.command, "failed", `Failed to create gist: ${gist.stderr.trim() || "Unknown error"}`);
-                    }
                     const gistUrl = gist.stdout.trim();
                     const gistId = gistUrl.split("/").at(-1);
                     if (!gistId)
@@ -1497,13 +1630,17 @@ export class PiEngineAdapter {
                 }
             }
             case "reload": {
-                if (session.isStreaming)
-                    return workflowResult(request.command, "failed", "Wait for the current response to finish before reloading.", undefined, "warning");
-                if (session.isCompacting)
-                    return workflowResult(request.command, "failed", "Wait for compaction to finish before reloading.", undefined, "warning");
+                const blocked = this.reloadBlockedResult();
+                if (blocked)
+                    return blocked;
                 await requireCapability(session.reload, "reload").call(session);
                 await this.#bindExtensionUiToSession();
-                return workflowResult(request.command, "completed", "Reloaded keybindings, extensions, skills, prompts, themes, and context files");
+                const message = "Reloaded keybindings, extensions, skills, prompts, themes, and context files";
+                const modelError = runtime.services.modelRuntime.getError?.();
+                return workflowResult(request.command, "completed", message, undefined, "status", modelError ? [
+                    { kind: "error", message: `models.json error: ${modelError}` },
+                    { kind: "status", message },
+                ] : undefined);
             }
             case "quit": {
                 await this.dispose();
@@ -1767,6 +1904,7 @@ export class PiEngineAdapter {
     async #perform(command) {
         const runtime = this.#runtime;
         const session = this.#session;
+        const generation = this.#sessionGeneration;
         if (!runtime || !session)
             throw new Error("engine session is unavailable");
         switch (command.type) {
@@ -1794,7 +1932,8 @@ export class PiEngineAdapter {
                     throw new Error(`model is unavailable: ${command.model.providerId}/${command.model.modelId}`);
                 }
                 await session.setModel(model);
-                this.#activeModel = { ...command.model };
+                if (generation === this.#sessionGeneration && this.#overload === undefined && !this.#admissionStopped)
+                    this.#activeModel = { ...command.model };
                 return;
             }
             case "set-thinking-level":
@@ -1822,7 +1961,13 @@ export class PiEngineAdapter {
     }
     #bindSession(session) {
         this.#unsubscribe?.();
+        for (const pending of this.#pendingCommands.values()) {
+            if (pending.type !== "new-session" && pending.type !== "resume-session")
+                pending.cancel();
+        }
         this.#sessionGeneration += 1;
+        this.#sessionBindingGeneration += 1;
+        this.#invalidatedEvents += this.#eventQueue.discardObsolete(this.#sessionGeneration);
         this.#session = session;
         this.#activeCommandIds = [];
         this.#completedCommands.clear();
@@ -1845,7 +1990,11 @@ export class PiEngineAdapter {
         this.#thinkingLevel = readThinkingLevel(session.thinkingLevel);
         this.#transcriptImageAssets.clear();
         this.#rebuildTranscript(session.messages, "finalized");
-        this.#unsubscribe = session.subscribe(event => this.#handlePiEvent(event));
+        const generation = this.#sessionGeneration;
+        this.#unsubscribe = session.subscribe(event => {
+            if (generation === this.#sessionGeneration && !this.#disposed)
+                this.#handlePiEvent(event);
+        });
         if (this.#extensionUi !== undefined)
             void this.#bindExtensionUiToSession();
     }
@@ -2005,15 +2154,11 @@ export class PiEngineAdapter {
                 return;
             case "tool_execution_start":
             case "tool_execution_end": {
-                // Concurrency: the end supersedes any update still waiting on the coalescing timer.
-                const toolCallId = stringValue(event.toolCallId);
-                if (toolCallId !== undefined)
-                    this.#pendingToolUpdates.delete(toolCallId);
                 this.#upsertToolExecutionBlock(event);
                 return;
             }
             case "tool_execution_update":
-                this.#coalesceToolExecutionUpdate(event);
+                this.#upsertToolExecutionBlock(event);
                 return;
             case "agent_settled":
             case "agent_end": {
@@ -2025,7 +2170,7 @@ export class PiEngineAdapter {
                 if (finalMessages.length > 0)
                     this.#rebuildTranscript(finalMessages, "finalized");
                 else
-                    this.#setTranscript(this.#transcript.map(block => block.status === "live" ? { ...block, status: "finalized" } : block));
+                    this.#setTranscript(this.#transcript.map(block => block.status === "live" ? { ...block, status: "finalized", revision: block.revision + 1 } : block));
                 // Compatibility: ending a turn leaves the working state, as the recorded pinned baseline does, but
                 // it leaves only that state: a compaction or retry being shown outlives the turn
                 // that ended under it. Settlement ends the run, and with it every state — the
@@ -2347,30 +2492,6 @@ export class PiEngineAdapter {
         }
         return references;
     }
-    // Performance: coalescing each tool to its newest chunk bounds work by frames, not stream events.
-    #coalesceToolExecutionUpdate(event) {
-        const toolCallId = stringValue(event.toolCallId);
-        if (!toolCallId)
-            return;
-        this.#pendingToolUpdates.set(toolCallId, event);
-        this.#toolUpdateFlush ??= setTimeout(() => {
-            this.#toolUpdateFlush = null;
-            if (!this.#disposed)
-                this.#flushPendingToolUpdates();
-        }, TOOL_UPDATE_COALESCE_MS);
-    }
-    #flushPendingToolUpdates() {
-        if (this.#toolUpdateFlush !== null) {
-            clearTimeout(this.#toolUpdateFlush);
-            this.#toolUpdateFlush = null;
-        }
-        if (this.#pendingToolUpdates.size === 0)
-            return;
-        const pending = [...this.#pendingToolUpdates.values()];
-        this.#pendingToolUpdates.clear();
-        for (const update of pending)
-            this.#upsertToolExecutionBlock(update);
-    }
     #upsertToolExecutionBlock(event) {
         const toolCallId = stringValue(event.toolCallId);
         if (!toolCallId)
@@ -2403,6 +2524,9 @@ export class PiEngineAdapter {
         const index = this.#transcriptIndex.get(block.id);
         if (index !== undefined) {
             const existing = this.#transcript[index];
+            // Invariant: an obsolete partial cannot revive finalized content after a completion barrier.
+            if (existing?.status === "finalized" && block.status === "live")
+                return;
             // Performance: nothing is emitted for a block that repeats itself, and keeping the
             // revision keeps the rows it already rendered.
             if (existing !== undefined && sameBlockContent(existing, block))
@@ -2486,52 +2610,118 @@ export class PiEngineAdapter {
         this.#enqueueEvent(event);
     }
     #enqueueEvent(event) {
-        const capacity = 1_024;
-        if (this.#eventQueue.length >= capacity) {
-            const coalescible = this.#eventQueue.findIndex(queued => queued.type === "session-view"
-                || queued.type === "status"
-                || queued.type === "editor-state"
-                || queued.type === "transcript-block");
-            if (coalescible >= 0)
-                this.#eventQueue.splice(coalescible, 1);
-            else
-                this.#eventQueue.shift();
-            this.#droppedEventCount += 1;
-            if (this.#droppedEventCount === 1 || this.#droppedEventCount % 128 === 0) {
-                this.#recordDiagnostic("warning", "event-backpressure", `owned UI coalesced ${this.#droppedEventCount} engine events under backpressure`, true);
+        if (this.#overload !== undefined) {
+            if (event.type === "command-outcome" && event.outcome !== "accepted" && this.#pendingCommands.has(event.correlationId)) {
+                this.#reservedOutcomes.set(event.correlationId, { outcome: event.outcome, diagnostic: event.diagnostic });
+            }
+            return;
+        }
+        if (!this.#eventQueue.push(event, this.#sessionGeneration, event.type === "transcript-block"
+            ? this.#blockReconciliation(event.block.id, event.sequence) : undefined)) {
+            this.#beginOverload();
+            if (event.type === "command-outcome" && event.outcome !== "accepted" && this.#pendingCommands.has(event.correlationId)
+                && !this.#reservedOutcomes.has(event.correlationId)) {
+                this.#reservedOutcomes.set(event.correlationId, { outcome: event.outcome, diagnostic: event.diagnostic });
             }
         }
-        this.#eventQueue.push(event);
         this.#eventQueueProcessing ??= Promise.resolve().then(() => this.#processEventQueue());
     }
+    // Performance: capture only identity, not the complete block/event retained by an earlier revision.
+    #blockReconciliation(id, sequence) {
+        return () => ({ type: "transcript-block", sessionId: this.#sessionId, sequence, block: this.#transcriptBlock(id) });
+    }
+    #beginOverload() {
+        if (this.#overload !== undefined)
+            return;
+        this.#overloads = Math.min(Number.MAX_SAFE_INTEGER, this.#overloads + 1);
+        this.#deliveryFailed = true;
+        // Concurrency: reserve before cancellation; outcomes produced reentrantly must not enter the saturated queue.
+        this.#overload = Promise.resolve(false);
+        for (const pending of this.#pendingCommands.values())
+            pending.cancel();
+        for (const pending of this.#pendingWorkflows)
+            pending.cancel();
+        const session = this.#session;
+        this.#overload = new Promise(resolve => {
+            const timer = setTimeout(() => resolve(false), 2000);
+            void Promise.resolve().then(() => session?.abort()).then(() => {
+                clearTimeout(timer);
+                resolve(true);
+            }, () => { clearTimeout(timer); resolve(false); });
+        });
+    }
+    #deliver(event) {
+        for (const [listener, subscribedAt] of this.#listeners) {
+            if (event.sequence <= subscribedAt)
+                continue;
+            try {
+                listener(event);
+            }
+            catch (error) {
+                this.#deliveryFailed = true;
+                this.#recordDiagnostic("warning", "event-listener", error instanceof Error ? error.message : String(error), true);
+            }
+        }
+    }
+    async #reconcileOverload() {
+        const cancelled = await this.#overload;
+        const canResume = cancelled === true && this.#runningCommands === 0;
+        this.#admissionStopped = !canResume;
+        this.#unsubscribe?.();
+        this.#unsubscribe = undefined;
+        ++this.#sessionGeneration;
+        this.#agentRunActive = false;
+        this.#statusKind = null;
+        this.#status = { ...this.#status, workingMessage: null };
+        this.#lifecycle = this.#disposed ? "stopped" : canResume ? "ready" : "failed";
+        this.#editor = { ...this.#editor, submitEnabled: canResume && !this.#disposed };
+        this.#viewRevision += 1;
+        this.#setTranscript(this.#transcript.map(block => block.status === "live" ? { ...block, status: "finalized", revision: block.revision + 1 } : block));
+        for (const [correlationId, result] of this.#reservedOutcomes) {
+            this.#deliver(this.#event({ type: "command-outcome", correlationId, ...result }));
+            await new Promise(resolve => setImmediate(resolve));
+        }
+        this.#reservedOutcomes.clear();
+        // Invariant: one out-of-band authoritative reconciliation, not an emergency transcript/event log.
+        this.#deliver(this.#event({ type: "session-view", view: this.view() }));
+        if (this.#disposed)
+            this.#deliver(this.#event({ type: "session-lifecycle", lifecycle: "stopped", reason: null }));
+        if (canResume && !this.#disposed && this.#session !== undefined) {
+            const generation = this.#sessionGeneration;
+            this.#unsubscribe = this.#session.subscribe(event => {
+                if (generation === this.#sessionGeneration && !this.#disposed)
+                    this.#handlePiEvent(event);
+            });
+        }
+        this.#overload = undefined;
+    }
     async #processEventQueue() {
         try {
             let deliveredSinceYield = 0;
-            while (this.#eventQueue.length > 0) {
-                const event = this.#eventQueue.shift();
-                if (!event)
+            while (this.#eventQueue.size > 0) {
+                const pending = this.#eventQueue.shift();
+                if (pending === undefined)
+                    continue;
+                if (pending.generation !== this.#sessionGeneration && pending.event.type !== "command-outcome") {
+                    this.#invalidatedEvents = Math.min(Number.MAX_SAFE_INTEGER, this.#invalidatedEvents + 1);
                     continue;
-                for (const listener of this.#listeners) {
-                    try {
-                        listener(event);
-                    }
-                    catch (error) {
-                        this.#recordDiagnostic("warning", "event-listener", error instanceof Error ? error.message : String(error), true);
-                    }
                 }
+                this.#deliver(pending.event);
                 deliveredSinceYield += 1;
                 // Concurrency: a microtask chain runs to exhaustion before the loop turns, so a streaming
                 // burst would hold typed input, pointer reports, and timed indicators until it
                 // drained. Yielding on a macrotask hands those their turn between batches.
-                if (deliveredSinceYield >= EVENT_DELIVERY_BATCH && this.#eventQueue.length > 0) {
+                if (deliveredSinceYield >= EVENT_DELIVERY_BATCH && this.#eventQueue.size > 0) {
                     deliveredSinceYield = 0;
                     await new Promise(resolve => { setImmediate(resolve); });
                 }
             }
+            if (this.#overload !== undefined)
+                await this.#reconcileOverload();
         }
         finally {
             this.#eventQueueProcessing = undefined;
-            if (this.#eventQueue.length > 0) {
+            if (this.#eventQueue.size > 0) {
                 this.#eventQueueProcessing = Promise.resolve().then(() => this.#processEventQueue());
             }
         }
@@ -2698,7 +2888,7 @@ function defaultWorkflowHost() {
             const result = await execFileAsync(command, [...arguments_], { encoding: "utf8", signal: options?.signal });
             return { stdout: result.stdout, stderr: result.stderr };
         },
-        readChangelog: async () => "No changelog entries found.",
+        readChangelog: readPinnedCommandChangelog,
     };
 }
 function workflowLoginNotification(event) {
@@ -2757,6 +2947,13 @@ function workflowConfirmation(command, message, detail) {
 function errorMessage(error, fallback) {
     return error instanceof Error ? error.message : fallback;
 }
+function shareCommandFailureDetail(error) {
+    // Compatibility: Pi reports a failed child's stderr, not execFile's command wrapper.
+    if (isRecord(error) && (typeof error.code === "number" || typeof error.signal === "string") && typeof error.stderr === "string") {
+        return error.stderr.trim() || "Unknown error";
+    }
+    return errorMessage(error, "Unknown error");
+}
 function commandMissing(error) {
     return isRecord(error) && error.code === "ENOENT";
 }