@pasko70/pibo 3.0.0 → 3.0.2

package/README.md

@@ -24,6 +24,19 @@ pibo --help
 
 The current package declares Node.js 24+. Some Linux distributions still ship Node 22 through `apt`, so install a recent Node release first when needed. A user-local Node/npm setup through `nvm`, `fnm`, or a user-writable npm prefix works well.
 
+Package installation has no host-level side effects. For a self-hosted server, choose a supported setup profile after installing the CLI:
+
+```bash
+# Recommended complete workstation
+pibo setup plan --profile batteries-included --domain pibo.example.com
+sudo pibo setup install --profile batteries-included --domain pibo.example.com --apply --yes
+
+# Minimal gateway and Chat Web only
+pibo setup plan --profile vanilla --domain pibo.example.com
+```
+
+See [Installation profiles](./docs/project/installation-profiles.md) for components, resource and security costs, staging, upgrades, and rollback.
+
 For a user-local global npm prefix:
 
 ```bash
@@ -67,17 +80,18 @@ A fresh server install usually needs only three decisions:
 2. Install Node.js 24+ for that user or system-wide.
 3. Install Pibo through npm.
 
-Use the setup planner to keep the first run simple:
+Use an installation profile for the normal first run. Batteries Included is recommended; Vanilla is the minimal controlled base:
 
 ```bash
 pibo setup doctor --domain pibo.example.com --expected-ip <server-ip>
-pibo setup user-host --domain pibo.example.com --print-files
-pibo setup user-host --domain pibo.example.com --write-to /tmp/pibo-setup
+pibo setup plan --profile batteries-included --domain pibo.example.com
+pibo setup install --profile batteries-included --domain pibo.example.com --write-to /tmp/pibo-setup
+sudo pibo setup install --profile batteries-included --domain pibo.example.com --apply --yes
 ```
 
-This is the normal user path: one gateway, one `PIBO_HOME`, no required Docker, no dev gateway, and no GitHub App setup. After reviewing staged files, use `--apply --yes` to write the generated systemd/Caddy files.
+The package install remains side-effect free. The explicit setup command records ownership, checks pinned downloads, configures the selected components, and exposes status, upgrade, and uninstall plans. See [Installation profiles](./docs/project/installation-profiles.md).
 
-Developer hosts are opt-in and add production/dev separation plus Docker compute workers:
+Core developers can still use the topology-specific developer-host planner to add production/dev separation plus Docker compute workers:
 
 ```bash
 pibo setup developer-host \
@@ -159,7 +173,7 @@ pibo mcp          # discover and call configured MCP servers
 pibo tools        # install and inspect curated external CLI tools
 pibo pi-packages  # register Pi Coding Agent packages
 pibo debug        # inspect local Pibo data stores
-pibo setup        # plan user-host installs and developer-host upgrades
+pibo setup        # plan and manage supported host installation profiles
 pibo profile      # inspect runtime profiles
 pibo tui          # start the direct Pi TUI
 pibo tui:routed   # start the routed Pibo TUI

package/dist/agent-runtime/context-build.js

@@ -17,6 +17,7 @@ export function profileWithRuntimeInstance(profile, runtimeInstanceId) {
         parentSessionId: profile.parentSessionId,
         model: undefined,
         mainModel: undefined,
+        mainModelFallbacks: [],
         subagentModel: undefined,
         thinkingLevel: profile.thinkingLevel,
         mainThinkingLevel: profile.mainThinkingLevel,
@@ -30,6 +31,7 @@ export function profileWithRuntimeInstance(profile, runtimeInstanceId) {
         mcpServers: profile.mcpServers,
         piPackages: profile.piPackages,
         contextFiles: profile.contextFiles,
+        diagnostics: profile.diagnostics,
         builtinTools: profile.builtinTools,
         builtinToolNames: profile.builtinToolNames,
         autoContextFiles: profile.autoContextFiles,
@@ -229,6 +231,7 @@ export function buildPortableRuntimeContextSnapshot(input) {
         metadata: {
             activeModel: runtimeManifest.effectiveModel,
             mainModel: profile.mainModel,
+            mainModelFallbacks: profile.mainModelFallbacks,
             subagentModel: profile.subagentModel,
             mainThinkingLevel: profile.mainThinkingLevel ?? profile.thinkingLevel,
             subagentThinkingLevel: profile.subagentThinkingLevel ?? profile.thinkingLevel,
@@ -240,6 +243,21 @@ export function buildPortableRuntimeContextSnapshot(input) {
                 ?? input.runtime.capabilities.nativeSubagents.enabledByDefault,
         },
     });
+    for (const [index, diagnostic] of profile.diagnostics.entries()) {
+        addNode({
+            id: `profile-diagnostic-${index}`,
+            kind: "diagnostic",
+            title: diagnostic.code,
+            source: "profile",
+            state: diagnostic.severity === "error" ? "error" : "warning",
+            badges: [diagnostic.severity.toUpperCase(), "PROFILE"],
+            hydratedText: diagnostic.message,
+            metadata: diagnostic.resourceName ? {
+                resourceKind: diagnostic.resourceKind,
+                resourceName: diagnostic.resourceName,
+            } : undefined,
+        });
+    }
     for (const [index, diagnostic] of input.runtime.diagnostics.entries()) {
         addNode({
             id: `runtime-diagnostic-${index}`,
@@ -265,9 +283,11 @@ export function buildPortableRuntimeContextSnapshot(input) {
         });
     }
     const resourceDiagnostics = input.resources?.diagnostics ?? [];
-    const warnings = input.runtime.diagnostics.filter((diagnostic) => diagnostic.severity === "warning").length
+    const warnings = profile.diagnostics.filter((diagnostic) => diagnostic.severity === "warning").length
+        + input.runtime.diagnostics.filter((diagnostic) => diagnostic.severity === "warning").length
         + resourceDiagnostics.filter((diagnostic) => diagnostic.severity === "warning").length;
-    const errors = input.runtime.diagnostics.filter((diagnostic) => diagnostic.severity === "error").length
+    const errors = profile.diagnostics.filter((diagnostic) => diagnostic.severity === "error").length
+        + input.runtime.diagnostics.filter((diagnostic) => diagnostic.severity === "error").length
         + resourceDiagnostics.filter((diagnostic) => diagnostic.severity === "error").length;
     return {
         version: 1,
@@ -287,6 +307,10 @@ export function buildPortableRuntimeContextSnapshot(input) {
         },
         nodes,
         diagnostics: [
+            ...profile.diagnostics.map((diagnostic) => ({
+                type: diagnostic.severity,
+                message: `[${diagnostic.code}] ${diagnostic.message}`,
+            })),
             ...input.runtime.diagnostics.map((diagnostic) => ({ type: diagnostic.severity, message: diagnostic.message })),
             ...resourceDiagnostics.map((diagnostic) => ({ type: diagnostic.severity, message: diagnostic.message })),
         ],

package/dist/agent-runtime/routed-session.js

@@ -1,5 +1,6 @@
 import { PiboSteeringUnavailableError, } from "../core/events.js";
-import { runtimeSessionErrorDetails } from "../core/session-errors.js";
+import { PIBO_PROVIDER_RECOVERY_PROMPT, isPiboProviderFallbackError } from "../core/provider-recovery.js";
+import { normalizeSessionErrorDetails, runtimeSessionErrorDetails } from "../core/session-errors.js";
 import { isPiboThinkingLevel } from "../core/thinking.js";
 import { AgentRuntimeCapabilityUnavailableError } from "./errors.js";
 const RUN_REMINDER_CAPABILITY_TOOLS = new Set([
@@ -29,6 +30,23 @@ function errorMessage(error) {
 function promptSource(source) {
     return source === "user" || source === "ui" ? "interactive" : "rpc";
 }
+function sameModel(left, right) {
+    return Boolean(left && right && left.provider === right.provider && left.id === right.id);
+}
+function uniqueModels(models) {
+    const seen = new Set();
+    return models.flatMap((model) => {
+        const provider = model.provider.trim();
+        const id = model.id.trim();
+        if (!provider || !id)
+            return [];
+        const key = `${provider}\u0000${id}`;
+        if (seen.has(key))
+            return [];
+        seen.add(key);
+        return [{ provider, id }];
+    });
+}
 function runtimeCapabilityError(session, capability) {
     return new AgentRuntimeCapabilityUnavailableError(capability, session.runtimeInstanceId, `Runtime instance "${session.runtimeInstanceId}" does not support ${capability}.`);
 }
@@ -120,6 +138,10 @@ export class RuntimeRoutedSession {
     nextThinkingIndex = 0;
     sessionIdentityOperationInFlight = false;
     forkCandidatesRequest;
+    primaryModel;
+    modelFallbacks;
+    suppressProviderFailures = false;
+    pendingProviderFailure;
     unsubscribe;
     constructor(piboSessionId, runtimeSession, emit, pluginRegistry, options = {}) {
         this.piboSessionId = piboSessionId;
@@ -128,6 +150,10 @@ export class RuntimeRoutedSession {
         this.pluginRegistry = pluginRegistry;
         this.options = options;
         this.runtime = runtimeSession.getNativeCompatibilityHandle?.() ?? runtimeSession;
+        this.primaryModel = runtimeSession.getStatus().activeModel
+            ? { ...runtimeSession.getStatus().activeModel }
+            : undefined;
+        this.modelFallbacks = uniqueModels(options.modelFallbacks ?? []);
         this.unsubscribe = runtimeSession.subscribe((event) => this.handleRuntimeEvent(event));
     }
     enqueueMessage(event, onAccepted = () => { }) {
@@ -407,7 +433,9 @@ export class RuntimeRoutedSession {
         const setModel = this.runtimeSession.controls?.setModel;
         if (!setModel)
             throw runtimeCapabilityError(this.runtimeSession, "in-session model switching");
-        return await setModel(model);
+        const selected = await setModel(model);
+        this.primaryModel = { ...selected };
+        return selected;
     }
     setThinkingLevel(level) {
         const setReasoning = this.runtimeSession.controls?.setReasoning;
@@ -642,10 +670,10 @@ export class RuntimeRoutedSession {
                 }));
                 return;
             case "error":
-                this.emitRuntimeError(event.message, event.details);
+                this.handleRuntimeFailure(event.message, event.details);
                 return;
             case "turn_failed":
-                this.emitRuntimeError(event.message, event.details);
+                this.handleRuntimeFailure(event.message, event.details);
                 return;
             case "native_event":
                 this.options.onNativeEventTelemetry?.(this.piboSessionId, event.event, {
@@ -661,6 +689,14 @@ export class RuntimeRoutedSession {
                 return;
         }
     }
+    handleRuntimeFailure(message, details) {
+        const normalized = normalizeSessionErrorDetails(message, details);
+        if (this.suppressProviderFailures && isPiboProviderFallbackError(message, normalized)) {
+            this.pendingProviderFailure = { message, details: normalized };
+            return;
+        }
+        this.emitRuntimeError(message, normalized);
+    }
     emitRuntimeError(message, details) {
         if (this.activeMessageFailed)
             return;
@@ -706,6 +742,71 @@ export class RuntimeRoutedSession {
             this.notifyState();
         }
     }
+    async promptWithModelFallbacks(event, inFlight) {
+        const setModel = this.runtimeSession.controls?.setModel;
+        const fallbackModels = this.modelFallbacks.filter((model) => !sameModel(model, this.primaryModel));
+        if (!setModel || fallbackModels.length === 0) {
+            await this.runtimeSession.prompt({
+                text: event.text,
+                source: promptSource(event.source),
+                capabilityScope: event.capabilityScope,
+            });
+            return;
+        }
+        this.suppressProviderFailures = true;
+        let switchedModel = false;
+        let finalFailure;
+        try {
+            for (let attempt = 0; attempt <= fallbackModels.length; attempt += 1) {
+                if (this.disposed || inFlight.cancelled)
+                    return;
+                if (attempt > 0) {
+                    try {
+                        await setModel(fallbackModels[attempt - 1]);
+                        switchedModel = true;
+                    }
+                    catch {
+                        continue;
+                    }
+                }
+                this.pendingProviderFailure = undefined;
+                let promptError;
+                try {
+                    await this.runtimeSession.prompt({
+                        text: attempt === 0 ? event.text : PIBO_PROVIDER_RECOVERY_PROMPT,
+                        source: attempt === 0 ? promptSource(event.source) : "rpc",
+                        capabilityScope: event.capabilityScope,
+                    });
+                }
+                catch (error) {
+                    promptError = error;
+                }
+                if (this.disposed || inFlight.cancelled)
+                    return;
+                const failure = this.pendingProviderFailure;
+                if (!failure) {
+                    if (promptError)
+                        throw promptError;
+                    return;
+                }
+                finalFailure = failure;
+            }
+            if (finalFailure)
+                this.emitRuntimeError(finalFailure.message, finalFailure.details);
+        }
+        finally {
+            this.suppressProviderFailures = false;
+            this.pendingProviderFailure = undefined;
+            if (switchedModel && this.primaryModel && !this.disposed) {
+                try {
+                    await setModel(this.primaryModel);
+                }
+                catch (error) {
+                    console.warn(`Failed to restore primary model for Pibo session "${this.piboSessionId}": ${errorMessage(error)}`);
+                }
+            }
+        }
+    }
     async processQueuedMessage(event) {
         const inFlight = this.beginInFlightMessage(event);
         try {
@@ -743,11 +844,7 @@ export class RuntimeRoutedSession {
             });
             if (inFlight.cancelled)
                 return;
-            await this.runtimeSession.prompt({
-                text: event.text,
-                source: promptSource(event.source),
-                capabilityScope: event.capabilityScope,
-            });
+            await this.promptWithModelFallbacks(event, inFlight);
             if (this.disposed || inFlight.cancelled)
                 return;
             if (!this.activeMessageFailed) {
@@ -776,6 +873,8 @@ export class RuntimeRoutedSession {
             }
         }
         finally {
+            this.suppressProviderFailures = false;
+            this.pendingProviderFailure = undefined;
             this.activeMessage = undefined;
             this.activeMessageFailed = false;
             this.resetContentIndices();

package/dist/agent-runtimes/codex-native/adapter.js

@@ -290,6 +290,7 @@ export class CodexNativeThreadSession {
     recycleProcessAfterInterruptedTurn = false;
     selectedToolNames = new Set();
     observedToolNames = new Set();
+    emittedResourceWarnings = new Set();
     toolInventoryWarning;
     constructor(runtimeInstanceId, process, threads, settings, resourceDelivery, binding, structuredUserInput, reloadProcess, productContext, bindingPersistence, firstUseTestFailpoints) {
         this.runtimeInstanceId = runtimeInstanceId;
@@ -390,6 +391,7 @@ export class CodexNativeThreadSession {
         this.assertActive();
         await this.ensureFreshResourcesForTurn();
         this.assertIdle();
+        this.emitPendingResourceWarnings();
         this.operationInFlight = true;
         let ownedFirstUseAttempt;
         try {
@@ -473,6 +475,7 @@ export class CodexNativeThreadSession {
             contextUsage: this.settings.currentContextUsage,
             warnings: [
                 ...diagnostics.filter((entry) => entry.level === "warning").map((entry) => entry.message),
+                ...this.resourceDelivery.warnings.map((entry) => entry.message),
                 ...(this.resourceWarning ? [this.resourceWarning] : []),
                 ...(this.toolInventoryWarning ? [this.toolInventoryWarning] : []),
             ],
@@ -659,6 +662,15 @@ export class CodexNativeThreadSession {
             throw new Error(`Native Codex portable-resource credential refresh failed while ${phase}; Pibo will retry while the session remains idle.`);
         }
     }
+    emitPendingResourceWarnings() {
+        for (const warning of this.resourceDelivery.warnings) {
+            const key = `${warning.code}\0${warning.message}`;
+            if (this.emittedResourceWarnings.has(key))
+                continue;
+            this.emittedResourceWarnings.add(key);
+            this.emit({ type: "warning", message: warning.message, details: { code: warning.code } });
+        }
+    }
     updateSelectedToolNames(resourceDelivery) {
         const names = [...new Set(resourceDelivery.enabledToolNames)].sort();
         this.selectedToolNames = new Set(names.slice(0, MAX_INSPECTED_SELECTED_TOOL_NAMES));

package/dist/agent-runtimes/codex-native/resource-delivery.js

@@ -256,21 +256,25 @@ export class CodexNativeResourceDelivery {
     skillRoots;
     selectedSkills;
     expectedMcpServers;
+    resources;
     portableTools;
     mcpAccess;
     credentialIssuedAtMs;
     credentialExpiresAtMs;
-    constructor(environment, threadConfig, developerInstructions, skillRoots, selectedSkills, expectedMcpServers, portableTools, mcpAccess, credentialIssuedAtMs, credentialExpiresAtMs) {
+    resourceWarnings;
+    constructor(environment, threadConfig, developerInstructions, skillRoots, selectedSkills, expectedMcpServers, resources, portableTools, mcpAccess, credentialIssuedAtMs, credentialExpiresAtMs, resourceWarnings = []) {
         this.environment = environment;
         this.threadConfig = threadConfig;
         this.developerInstructions = developerInstructions;
         this.skillRoots = skillRoots;
         this.selectedSkills = selectedSkills;
         this.expectedMcpServers = expectedMcpServers;
+        this.resources = resources;
         this.portableTools = portableTools;
         this.mcpAccess = mcpAccess;
         this.credentialIssuedAtMs = credentialIssuedAtMs;
         this.credentialExpiresAtMs = credentialExpiresAtMs;
+        this.resourceWarnings = resourceWarnings;
     }
     static async prepare(input) {
         const resourceEnvironment = { ...(input.resources?.getAdapterEnvironment() ?? {}) };
@@ -323,7 +327,7 @@ export class CodexNativeResourceDelivery {
             const selectedSkills = input.resources
                 ? await Promise.all(input.resources.getInspection().skills.flatMap((skill) => {
                     const path = skill.materializedPath;
-                    return path ? [{ name: skill.name, path }] : [];
+                    return path ? [{ contributionId: skill.contributionId, name: skill.name, path }] : [];
                 }).map(async (skill) => ({ ...skill, path: await realpath(skill.path) })))
                 : [];
             const materializedSkillsRoot = input.resources?.getInspection().paths?.skills;
@@ -339,7 +343,7 @@ export class CodexNativeResourceDelivery {
                     : { multi_agent: false, multi_agent_v2: false };
                 threadConfig.agents = { enabled: input.nativeSubagentsEnabled };
             }
-            return new CodexNativeResourceDelivery(resourceEnvironment, Object.keys(threadConfig).length > 0 ? threadConfig : undefined, buildDeveloperInstructions(input.resources), skillRoots, selectedSkills, expectedMcpServers, input.portableTools, mcpAccess, credentialIssuedAtMs, credentialExpiresAtMs);
+            return new CodexNativeResourceDelivery(resourceEnvironment, Object.keys(threadConfig).length > 0 ? threadConfig : undefined, buildDeveloperInstructions(input.resources), skillRoots, selectedSkills, expectedMcpServers, input.resources, input.portableTools, mcpAccess, credentialIssuedAtMs, credentialExpiresAtMs);
         }
         catch (error) {
             if (mcpAccess && input.portableTools)
@@ -350,6 +354,9 @@ export class CodexNativeResourceDelivery {
     get hasMcpServers() {
         return this.expectedMcpServers.length > 0;
     }
+    get warnings() {
+        return this.resourceWarnings;
+    }
     get enabledToolNames() {
         return this.expectedMcpServers
             .flatMap((server) => server.toolNames.map((toolName) => `${server.name}/${toolName}`))
@@ -379,6 +386,7 @@ export class CodexNativeResourceDelivery {
         this.credentialExpiresAtMs = expiresAt;
     }
     async configureProcess(client, workspace) {
+        this.resourceWarnings = [];
         if (this.skillRoots.length === 0)
             return;
         let response;
@@ -411,15 +419,35 @@ export class CodexNativeResourceDelivery {
                 }
             }
         }
+        const collisions = new Set();
         for (const skill of this.selectedSkills) {
             const sameNamePaths = loadedSkills.get(skill.name) ?? new Set();
             const conflictingPath = [...sameNamePaths].find((path) => path !== skill.path);
-            if (conflictingPath) {
-                throw new Error(`Selected Pibo skill "${skill.name}" conflicts with a native Codex skill; explicit Pibo-skill precedence cannot be guaranteed.`);
-            }
-            if (!loadedPaths.has(skill.path))
+            if (conflictingPath)
+                collisions.add(skill.name);
+            if (!loadedPaths.has(skill.path) && !conflictingPath)
                 throw new Error(`Codex did not load selected Pibo skill "${skill.name}".`);
         }
+        let collisionMessage;
+        if (collisions.size > 0) {
+            const names = [...collisions].sort().map((name) => `"${name}"`).join(", ");
+            collisionMessage = `Codex native skill name collision for ${names}: the selected Pibo skill remains materialized, but precedence is ambiguous. Rename or disable one source to remove the collision.`;
+            this.resourceWarnings = [{
+                    code: "codex_native_skill_name_collision",
+                    message: collisionMessage,
+                }];
+        }
+        this.resources?.recordAdapterDelivery?.(this.selectedSkills.map((skill) => {
+            const collided = collisions.has(skill.name);
+            return {
+                contributionId: skill.contributionId,
+                status: collided ? "degraded" : "delivered",
+                mode: "codex-extra-roots",
+                fidelity: collided ? "lossy" : "exact",
+                target: skill.path,
+                ...(collided && collisionMessage ? { diagnostic: collisionMessage } : {}),
+            };
+        }));
     }
     async verifyThread(client, threadId) {
         if (this.expectedMcpServers.length === 0)

package/dist/agent-runtimes/omp/adapter.js

@@ -631,13 +631,9 @@ class OmpAgentRuntimeAdapter {
         }
         return emptyOmpHistoryPage(this.instanceId);
     }
-    async resolveBinding() {
-        return {
-            piboSessionId: "",
-            runtimeInstanceId: this.instanceId,
-            adapterId: OMP_ADAPTER_ID,
-            state: "unbound",
-        };
+    async resolveBinding(input) {
+        // OMP can verify and resume the transcript only after startup via switch_session.
+        return structuredClone(input.binding);
     }
 }
 export const OMP_AGENT_RUNTIME_DRIVER = {

package/dist/agent-runtimes/pi/adapter.js

@@ -135,6 +135,7 @@ function cloneProfileForPiSession(input) {
         parentSessionId: profile.parentSessionId,
         model: profile.model,
         mainModel: profile.mainModel,
+        mainModelFallbacks: profile.mainModelFallbacks,
         subagentModel: profile.subagentModel,
         thinkingLevel: profile.thinkingLevel,
         mainThinkingLevel: profile.mainThinkingLevel,
@@ -148,6 +149,7 @@ function cloneProfileForPiSession(input) {
         mcpServers: profile.mcpServers,
         piPackages: profile.piPackages,
         contextFiles: profile.contextFiles,
+        diagnostics: profile.diagnostics,
         builtinTools: profile.builtinTools,
         builtinToolNames: profile.builtinToolNames,
         autoContextFiles: profile.autoContextFiles,
@@ -276,7 +278,7 @@ class PiAgentRuntimeSession {
     bindingNativeSessionId;
     nativePresenceExpected;
     disposed = false;
-    constructor(runtimeInstanceId, piboSessionId, runtime, binding, initialFastMode, providerWebSearchEnabled) {
+    constructor(runtimeInstanceId, piboSessionId, runtime, binding, initialFastMode, providerWebSearchEnabled, providerFallbacksEnabled) {
         this.runtimeInstanceId = runtimeInstanceId;
         this.piboSessionId = piboSessionId;
         this.runtime = runtime;
@@ -284,7 +286,7 @@ class PiAgentRuntimeSession {
         this.cwd = runtime.cwd;
         this.bindingNativeSessionId = runtime.session.sessionId;
         this.nativePresenceExpected = runtime.session.sessionManager.buildSessionContext().messages.length > 0;
-        this.routed = new PiRoutedSession(piboSessionId, runtime, (event) => this.handlePiboEvent(event), PiboPluginRegistry.create(), true, undefined, initialFastMode, undefined, undefined, (state) => this.handleEngineState(state));
+        this.routed = new PiRoutedSession(piboSessionId, runtime, (event) => this.handlePiboEvent(event), PiboPluginRegistry.create(), true, undefined, initialFastMode, undefined, undefined, (state) => this.handleEngineState(state), undefined, undefined, providerFallbacksEnabled);
         if (providerWebSearchEnabled)
             this.routed.enableProviderWebSearchObservation();
         this.controls = this.createControls();
@@ -685,7 +687,7 @@ class PiAgentRuntimeAdapter {
                     && runtime.session.sessionManager.buildSessionContext().messages.length > 0,
             },
         };
-        return new PiAgentRuntimeSession(this.instanceId, input.piboSession.id, runtime, binding, compatibility?.initialFastMode ?? false, profile.tools.some((tool) => tool.enabled !== false && isWebSearchProviderTool(tool)));
+        return new PiAgentRuntimeSession(this.instanceId, input.piboSession.id, runtime, binding, compatibility?.initialFastMode ?? false, profile.tools.some((tool) => tool.enabled !== false && isWebSearchProviderTool(tool)), compatibility?.providerFallbacksEnabled ?? false);
     }
     loadModelCatalog() {
         const now = Date.now();

package/dist/agent-runtimes/pi/routed-session.js

@@ -1,3 +1,5 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
 import { SessionManager, shouldCompact } from "@earendil-works/pi-coding-agent";
 import { PiboSteeringUnavailableError } from "../../core/events.js";
 import { getOpenAiCodexProviderUsageForActiveModel } from "../../auth/openai-codex-usage.js";
@@ -18,6 +20,16 @@ const RUN_REMINDER_CAPABILITY_TOOLS = new Set([
     "pibo_run_cancel",
     "pibo_run_ack",
 ]);
+function materializeForkedSession(sessionManager) {
+    const sessionFile = sessionManager.getSessionFile();
+    const header = sessionManager.getHeader();
+    if (!sessionManager.isPersisted() || !sessionFile || !header || existsSync(sessionFile))
+        return;
+    mkdirSync(dirname(sessionFile), { recursive: true });
+    writeFileSync(sessionFile, `${[header, ...sessionManager.getEntries()].map((entry) => JSON.stringify(entry)).join("\n")}\n`, { encoding: "utf8", flag: "wx" });
+    // Reload through the public API so Pi also records that the file is flushed.
+    sessionManager.setSessionFile(sessionFile);
+}
 function modelSupportsFastServiceTier(model) {
     if (!model)
         return false;
@@ -587,6 +599,7 @@ export class RoutedSession {
     onStateChange;
     onMessagesInterrupted;
     messagePreflight;
+    providerFallbacksEnabled;
     queue = [];
     processing = false;
     disposed = false;
@@ -605,6 +618,9 @@ export class RoutedSession {
     nextAssistantIndex = 0;
     activeThinkingIndex;
     nextThinkingIndex = 0;
+    nextUsageIndex = 0;
+    activeCompactionIndex;
+    nextCompactionIndex = 0;
     sessionIdentityOperationInFlight = false;
     pendingAssistantError;
     pendingAssistantErrorRetryable = false;
@@ -616,7 +632,7 @@ export class RoutedSession {
     recoverySession;
     isContinuePatched = false;
     compatibilityAuthController;
-    constructor(piboSessionId, runtime, emit, pluginRegistry, forwardPiEvents, onPiEventTelemetry, initialFastMode, onSessionOperation, onKillChildren, onStateChange, onMessagesInterrupted, messagePreflight) {
+    constructor(piboSessionId, runtime, emit, pluginRegistry, forwardPiEvents, onPiEventTelemetry, initialFastMode, onSessionOperation, onKillChildren, onStateChange, onMessagesInterrupted, messagePreflight, providerFallbacksEnabled = false) {
         this.piboSessionId = piboSessionId;
         this.runtime = runtime;
         this.emit = emit;
@@ -628,6 +644,7 @@ export class RoutedSession {
         this.onStateChange = onStateChange;
         this.onMessagesInterrupted = onMessagesInterrupted;
         this.messagePreflight = messagePreflight;
+        this.providerFallbacksEnabled = providerFallbacksEnabled;
         this.fastMode = initialFastMode && this.fastModeSupported();
         this.bindRuntimeSession();
         this.patchProviderRequest();
@@ -1005,26 +1022,34 @@ export class RoutedSession {
         const candidate = event;
         const eventId = this.activeMessage?.id ?? this.activeExecutionEvent?.id;
         if (candidate.type === "compaction_start") {
+            const compactionIndex = this.activeCompactionIndex ?? this.nextCompactionIndex;
+            if (this.activeCompactionIndex === undefined)
+                this.nextCompactionIndex += 1;
+            this.activeCompactionIndex = compactionIndex;
             this.emit(this.withActiveMessage({
                 type: "compaction_start",
                 piboSessionId: this.piboSessionId,
                 eventId,
+                compactionIndex,
                 reason: typeof candidate.reason === "string" ? candidate.reason : "unknown",
             }));
         }
         if (candidate.type === "compaction_end") {
+            const compactionIndex = this.activeCompactionIndex ?? this.nextCompactionIndex;
+            if (this.activeCompactionIndex === undefined)
+                this.nextCompactionIndex += 1;
+            this.activeCompactionIndex = undefined;
             if (candidate.result && candidate.aborted !== true) {
-                // Reset assistant message indices so the next assistant response starts
-                // fresh after compaction, matching the reduced agent context.
+                // End any open output block, but keep durable part indices monotonic for
+                // the lifetime of the routed event across context-guard continuation.
                 this.activeAssistantIndex = undefined;
-                this.nextAssistantIndex = 0;
                 this.activeThinkingIndex = undefined;
-                this.nextThinkingIndex = 0;
             }
             this.emit(this.withActiveMessage({
                 type: "compaction_end",
                 piboSessionId: this.piboSessionId,
                 eventId,
+                compactionIndex,
                 reason: typeof candidate.reason === "string" ? candidate.reason : "unknown",
                 result: candidate.result,
                 aborted: candidate.aborted === true,
@@ -1213,6 +1238,11 @@ export class RoutedSession {
         this.assertSessionWorkIdle("fork");
         const previous = this.createSessionSnapshot();
         const result = await this.runtime.fork(entryId);
+        if (!result.cancelled) {
+            // Pi defers persistence until an assistant message. Materialize an empty
+            // first-message branch so history readers can use its advertised path.
+            materializeForkedSession(this.runtime.session.sessionManager);
+        }
         return {
             piboSessionId: this.piboSessionId,
             previous,
@@ -1518,6 +1548,9 @@ export class RoutedSession {
             this.nextAssistantIndex = 0;
             this.activeThinkingIndex = undefined;
             this.nextThinkingIndex = 0;
+            this.nextUsageIndex = 0;
+            this.activeCompactionIndex = undefined;
+            this.nextCompactionIndex = 0;
             this.emit({
                 type: "message_started",
                 piboSessionId: this.piboSessionId,
@@ -1539,7 +1572,8 @@ export class RoutedSession {
             await this.resumeContextGuardRecovery(session);
             if (this.disposed || inFlight.cancelled)
                 return;
-            await this.recoverTransientProviderErrors(session);
+            if (!this.providerFallbacksEnabled)
+                await this.recoverTransientProviderErrors(session);
             if (this.disposed || inFlight.cancelled)
                 return;
             this.flushPendingAssistantError();
@@ -1578,6 +1612,9 @@ export class RoutedSession {
             this.nextAssistantIndex = 0;
             this.activeThinkingIndex = undefined;
             this.nextThinkingIndex = 0;
+            this.nextUsageIndex = 0;
+            this.activeCompactionIndex = undefined;
+            this.nextCompactionIndex = 0;
             this.providerWebSearchLifecycle.clear();
             if (this.inFlightMessage === inFlight)
                 this.inFlightMessage = undefined;
@@ -1817,8 +1854,12 @@ export class RoutedSession {
                 this.activeThinkingIndex = undefined;
             return output;
         }
-        if (event.type === "assistant_usage" ||
-            event.type === "compaction_start" ||
+        if (event.type === "assistant_usage") {
+            const usageIndex = this.nextUsageIndex;
+            this.nextUsageIndex += 1;
+            return { ...event, ...correlation, usageIndex };
+        }
+        if (event.type === "compaction_start" ||
             event.type === "compaction_end" ||
             event.type === "tool_call" ||
             event.type === "tool_execution_started" ||