pilotswarm-sdk 0.5.41 → 0.5.43

package/dist/management-client.js

@@ -12,6 +12,8 @@
  */
 import { RESPONSE_LATEST_KEY, commandResponseKey, stopTurnQueueName, sanitizePromptAttachmentRefs, } from "./types.js";
 import { SYSTEM_USER_PRINCIPAL } from "./cms.js";
+import { ProviderError } from "./provider-store.js";
+import { PROVIDER_BUDGET_WAKE_PROMPT } from "./provider-budgets.js";
 import { LOCAL_DEFAULT_USER_PRINCIPAL } from "./session-owner-utils.js";
 import { normalizeMessageSender } from "./message-sender.js";
 import { isEnhancedFactStore, EnhancedFactsUnsupportedError } from "./facts-store.js";
@@ -19,11 +21,16 @@ import { resolveStorageConfig } from "./storage-config.js";
 import { getDuroxideStorageProvider, getRuntimeStorageProvider } from "./storage-providers.js";
 import { SessionDumper } from "./session-dumper.js";
 import { computeSessionFootprint, FootprintCache } from "./footprint.js";
-import { loadModelProviders } from "./model-providers.js";
+import { loadModelProviders, loadModelProviderTypes } from "./model-providers.js";
+import { bootstrapProviders, resolveProviderCredential, resolveRuntimeModelSelection } from "./provider-catalog.js";
 import { deriveStatusFromCmsAndRuntime, shouldSyncCompletedStatus, shouldSyncFailedStatus } from "./session-status.js";
 import { assertUnambiguousProvider, isWebOptions } from "./web/api-connection.js";
 import { WebPilotSwarmManagementClient } from "./web/web-management-client.js";
 import { loadSystemAgentConfigs, resolveSystemAgentSessionPlans, startSystemAgents, } from "./system-agents.js";
+import { AgentPackageValidationError, deleteAgentPackageEverywhere, fetchAgentPackageTarGz, publishAgentPackageDir, publishPackedAgentPackage, readAgentPackageVersionEntries, resolveAgentPackageVersion, } from "./agent-package-service.js";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
 // duroxide is CommonJS — use createRequire for ESM compatibility
 import { createRequire } from "node:module";
 const require = createRequire(import.meta.url);
@@ -49,6 +56,22 @@ function assertValidDate(value, label) {
         throw new Error(`${label} must be a valid Date`);
     }
 }
+/**
+ * A default is one tuple, saved whole. With no provider there is nothing to
+ * run, so the other three go with it — carrying a model for a provider that
+ * was cleared would leave a half-default nobody can act on.
+ */
+function normalizeDefaultTuple(tuple) {
+    const provider = String(tuple?.provider ?? "").trim() || null;
+    if (!provider)
+        return { provider: null, model: null, reasoning: null, context: null };
+    return {
+        provider,
+        model: String(tuple?.model ?? "").trim() || null,
+        reasoning: String(tuple?.reasoning ?? "").trim() || null,
+        context: String(tuple?.context ?? "").trim() || null,
+    };
+}
 function isTerminalOrchestrationStatus(status) {
     return status === "Completed" || status === "Failed" || status === "Terminated";
 }
@@ -128,7 +151,7 @@ function normalizeSystemRestartDisposition(disposition) {
         return "terminate";
     if (disposition === "hard_delete" || disposition === "hardDelete")
         return "hard_delete";
-    throw new Error(`Unsupported system session restart disposition: ${String(disposition)}`);
+    throw Object.assign(new Error(`Unsupported system session restart disposition: ${String(disposition)}`), { code: "INVALID_REQUEST" });
 }
 function sessionViewFromCmsRow(row) {
     const liveStatus = row.state || "pending";
@@ -152,6 +175,7 @@ function sessionViewFromCmsRow(row) {
         serviceOf: row.serviceOf ?? undefined,
         model: row.model ?? undefined,
         reasoningEffort: row.reasoningEffort ?? undefined,
+        contextTier: row.contextTier ?? undefined,
         shortSummary: row.shortSummary ?? undefined,
         summaryState: row.summaryState ?? undefined,
         summaryUpdatedAt: row.summaryUpdatedAt?.getTime(),
@@ -162,6 +186,7 @@ function sessionViewFromCmsRow(row) {
         rootSessionId: row.rootSessionId ?? row.sessionId,
     };
 }
+export const PROVIDER_USAGE_DIMENSIONS = ["session", "user", "provider", "model", "agent"];
 // ─── Management Client ──────────────────────────────────────────
 function normalizeShareSlot(slot) {
     const n = Math.floor(Number(slot));
@@ -177,6 +202,7 @@ export class PilotSwarmManagementClient {
     _duroxideClient = null;
     _modelProviders = null;
     _systemAgents = [];
+    _artifactStore = null;
     _activeStatusWaitControllers = new Set();
     _activeStatusWaitPromises = new Set();
     _started = false;
@@ -198,6 +224,7 @@ export class PilotSwarmManagementClient {
             return new WebPilotSwarmManagementClient(options);
         }
         this.config = options;
+        this._artifactStore = options.artifactStore ?? null;
     }
     // ─── Lifecycle ───────────────────────────────────────────
     async start() {
@@ -255,7 +282,14 @@ export class PilotSwarmManagementClient {
             }
         }
         // Load model providers
-        this._modelProviders = loadModelProviders(this.config.modelProvidersPath);
+        this._modelProviders = loadModelProviderTypes(this.config.modelProvidersPath);
+        const legacyProviders = loadModelProviders(this.config.modelProvidersPath);
+        if (this._catalog.providers && legacyProviders) {
+            await bootstrapProviders(this._catalog.providers, {
+                providers: legacyProviders.allProviders,
+                defaultModel: legacyProviders.defaultModel,
+            });
+        }
         this._systemAgents = loadSystemAgentConfigs({
             pluginDirs: this.config.pluginDirs,
             disableManagementAgents: this.config.disableManagementAgents,
@@ -354,8 +388,8 @@ export class PilotSwarmManagementClient {
             candidate.sessionId === target ||
             `session-${candidate.sessionId}` === target);
         if (!plan) {
-            throw new Error(`System agent "${target}" is not known to this management client. ` +
-                `Configure pluginDirs/systemAgents so the client can recreate the system session.`);
+            throw Object.assign(new Error(`System agent "${target}" is not known to this management client. ` +
+                `Configure pluginDirs/systemAgents so the client can recreate the system session.`), { code: "NOT_FOUND" });
         }
         return plan;
     }
@@ -672,6 +706,7 @@ export class PilotSwarmManagementClient {
             isSystem: row.isSystem || undefined,
             model: row.model ?? undefined,
             reasoningEffort: row.reasoningEffort ?? undefined,
+            contextTier: row.contextTier ?? undefined,
             shortSummary: row.shortSummary ?? undefined,
             summaryState: row.summaryState ?? undefined,
             summaryUpdatedAt: row.summaryUpdatedAt?.getTime(),
@@ -945,10 +980,42 @@ export class PilotSwarmManagementClient {
         const trimmed = String(model || "").trim();
         if (!trimmed)
             throw new Error("setSessionModel requires a model id");
-        const models = this.listModels();
-        const match = models.find((m) => m.qualifiedName === trimmed);
+        const session = await this.getSession(sessionId).catch(() => null);
+        if (!session)
+            throw new Error(`Session ${sessionId.slice(0, 8)} was not found`);
+        const store = this._requireProviders();
+        if (!this._modelProviders)
+            throw new Error("Provider type catalog is unavailable");
+        const actor = session.owner
+            ? await store.lookupUserId(session.owner)
+            : null;
+        const credentials = await store.allCredentials();
+        let selection;
+        try {
+            selection = resolveRuntimeModelSelection(this._modelProviders, credentials, {
+                requestedModel: trimmed,
+                requestedReasoning: opts?.reasoningEffort,
+                requestedContext: opts?.contextTier,
+                eligible: session.isSystem
+                    ? (provider) => provider.class === "shared" || provider.systemUseEnabled === true
+                    : (provider) => provider.class === "shared" || (actor !== null && provider.ownerUserId === actor),
+            });
+        }
+        catch (error) {
+            if (error?.code === "MODEL_AMBIGUOUS")
+                throw error;
+            if (error?.code === "MODEL_UNRESOLVED") {
+                throw Object.assign(new Error(`Unknown model: ${trimmed}. ${error.message}`), { code: "MODEL_UNRESOLVED" });
+            }
+            throw new Error(`Unknown model: ${trimmed}. ${error?.message || String(error)}`);
+        }
+        const credential = credentials.find((provider) => provider.name === selection.provider);
+        const modelName = selection.model.slice(selection.model.indexOf(":") + 1);
+        const match = this._providerTypeModels(credential.typeId)
+            .find((candidate) => candidate.modelName === modelName);
         if (!match)
-            throw new Error(`Unknown model: ${trimmed}`);
+            throw new Error(`Unknown model: ${selection.model}`);
+        const resolvedModel = selection.model;
         // Reasoning effort is applied ONLY when the caller asked for one.
         // When omitted, the key is left out of the command args entirely so
         // the orchestration's set_model handler PRESERVES the session's
@@ -960,7 +1027,7 @@ export class PilotSwarmManagementClient {
         if (nextReasoningEffort) {
             const supported = match.supportedReasoningEfforts ?? [];
             if (!supported.includes(nextReasoningEffort)) {
-                throw new Error(`Model ${trimmed} does not support reasoning effort '${nextReasoningEffort}'`);
+                throw new Error(`Model ${resolvedModel} does not support reasoning effort '${nextReasoningEffort}'`);
             }
         }
         // Context-window tier follows the same preserve-when-omitted contract.
@@ -969,17 +1036,14 @@ export class PilotSwarmManagementClient {
         if (nextContextTier) {
             const supported = match.supportedContextTiers ?? [];
             if (!supported.includes(nextContextTier)) {
-                throw new Error(`Model ${trimmed} does not support context tier '${nextContextTier}'`);
+                throw new Error(`Model ${resolvedModel} does not support context tier '${nextContextTier}'`);
             }
         }
-        const session = await this.getSession(sessionId).catch(() => null);
-        if (!session)
-            throw new Error(`Session ${sessionId.slice(0, 8)} was not found`);
         await this.sendCommand(sessionId, {
             cmd: "set_model",
             id: buildLifecycleCommandId("set-model"),
             args: {
-                model: trimmed,
+                model: resolvedModel,
                 ...(hasExplicitEffort ? { reasoningEffort: nextReasoningEffort } : {}),
                 ...(hasExplicitContextTier ? { contextTier: nextContextTier } : {}),
                 source: opts?.source ?? "user",
@@ -1000,18 +1064,55 @@ export class PilotSwarmManagementClient {
         if (!session)
             throw new Error(`Session ${sessionId.slice(0, 8)} was not found`);
         if (session.isSystem) {
-            throw new Error("System sessions are excluded from regeneration (use restartSystemSession)");
+            throw Object.assign(new Error("System sessions are excluded from regeneration (use restartSystemSession)"), { code: "REGENERATE_UNSUPPORTED" });
         }
         if (session.serviceKind) {
-            throw new Error("Service sessions are runtime machinery and are excluded from regeneration");
+            throw Object.assign(new Error("Service sessions are runtime machinery and are excluded from regeneration"), { code: "REGENERATE_UNSUPPORTED" });
         }
-        const models = this.listModels();
-        const isKnown = (m) => !!m && models.some((x) => x.qualifiedName === m);
-        if (opts?.distillerModel && !isKnown(opts.distillerModel)) {
-            throw new Error(`Unknown distiller model: ${opts.distillerModel}`);
+        const store = this._requireProviders();
+        if (!this._modelProviders)
+            throw new Error("Provider type catalog is unavailable");
+        const actor = session.owner ? await store.lookupUserId(session.owner) : null;
+        const credentials = await store.allCredentials();
+        const eligible = (provider) => provider.class === "shared" || (actor !== null && provider.ownerUserId === actor);
+        const resolveRequested = (model, reasoning, context) => resolveRuntimeModelSelection(this._modelProviders, credentials, {
+            requestedModel: model,
+            requestedReasoning: reasoning,
+            requestedContext: context,
+            eligible,
+        });
+        let targetModel = opts?.model;
+        let distillerModel = opts?.distillerModel;
+        let distillerReasoningEffort = opts?.distillerReasoningEffort;
+        let distillerContextTier = opts?.distillerContextTier;
+        if (targetModel) {
+            try {
+                targetModel = resolveRequested(targetModel).model;
+            }
+            catch (error) {
+                if (error?.code === "MODEL_AMBIGUOUS")
+                    throw error;
+                if (error?.code === "MODEL_UNRESOLVED") {
+                    throw Object.assign(new Error(`Unknown model: ${opts?.model}. ${error.message}`), { code: "MODEL_UNRESOLVED" });
+                }
+                throw new Error(`Unknown model: ${opts?.model}. ${error?.message || String(error)}`);
+            }
         }
-        if (opts?.model && !isKnown(opts.model)) {
-            throw new Error(`Unknown model: ${opts.model}`);
+        if (distillerModel) {
+            try {
+                const resolved = resolveRequested(distillerModel, distillerReasoningEffort, distillerContextTier);
+                distillerModel = resolved.model;
+                distillerReasoningEffort = resolved.reasoning ?? undefined;
+                distillerContextTier = resolved.context ?? undefined;
+            }
+            catch (error) {
+                if (error?.code === "MODEL_AMBIGUOUS")
+                    throw error;
+                if (error?.code === "MODEL_UNRESOLVED") {
+                    throw Object.assign(new Error(`Unknown distiller model: ${opts?.distillerModel}. ${error.message}`), { code: "MODEL_UNRESOLVED" });
+                }
+                throw new Error(`Unknown distiller model: ${opts?.distillerModel}. ${error?.message || String(error)}`);
+            }
         }
         // Dead-model guard: the reborn session's grounding turn runs on the
         // session's model. If that model no longer resolves (a common regen
@@ -1019,8 +1120,16 @@ export class PilotSwarmManagementClient {
         // discard the transcript and then wedge on the dead model. Require a
         // live replacement rather than making a broken session strictly worse.
         const currentModel = session.model;
-        if (!opts?.model && currentModel && !isKnown(currentModel)) {
-            throw new Error(`Session model '${currentModel}' is no longer available; pass a replacement model to regenerate this session.`);
+        if (!targetModel && currentModel) {
+            try {
+                resolveRequested(currentModel);
+            }
+            catch (error) {
+                if (error?.code === "MODEL_AMBIGUOUS")
+                    throw error;
+                throw Object.assign(new Error(`Session model '${currentModel}' is no longer available; pass a replacement model to regenerate this session. `
+                    + `${error?.message || String(error)}`), { code: "MODEL_UNRESOLVED" });
+            }
         }
         const attemptId = buildLifecycleCommandId("regenerate");
         await this.sendCommand(sessionId, {
@@ -1030,10 +1139,10 @@ export class PilotSwarmManagementClient {
                 ...(opts?.handoff ? { handoff: String(opts.handoff).slice(0, 4_000) } : {}),
                 ...(opts?.instructions ? { instructions: String(opts.instructions).slice(0, 4_000) } : {}),
                 ...(opts?.distillMode === "deterministic" ? { distill_mode: "deterministic" } : {}),
-                ...(opts?.distillerModel ? { distillerModel: opts.distillerModel } : {}),
-                ...(opts?.distillerReasoningEffort ? { distillerReasoningEffort: opts.distillerReasoningEffort } : {}),
-                ...(opts?.distillerContextTier ? { distillerContextTier: opts.distillerContextTier } : {}),
-                ...(opts?.model ? { model: opts.model } : {}),
+                ...(distillerModel ? { distillerModel } : {}),
+                ...(distillerReasoningEffort ? { distillerReasoningEffort } : {}),
+                ...(distillerContextTier ? { distillerContextTier } : {}),
+                ...(targetModel ? { model: targetModel } : {}),
                 ...(opts?.force ? { force: true } : {}),
                 source: opts?.source ?? "operator",
             },
@@ -1107,7 +1216,8 @@ export class PilotSwarmManagementClient {
     async restartSystemSession(agentIdOrSessionId, options) {
         this._ensureStarted();
         if (!options?.disposition) {
-            throw new Error("restartSystemSession requires a disposition: complete, terminate, or hard_delete");
+            throw Object.assign(new Error("restartSystemSession requires a disposition: complete, terminate, or hard_delete "
+                + "(HTTP callers send it inside the options envelope: {\"options\":{\"disposition\":\"complete\"}})"), { code: "INVALID_REQUEST" });
         }
         const disposition = normalizeSystemRestartDisposition(options.disposition);
         const plan = this._resolveSystemAgentPlan(agentIdOrSessionId);
@@ -1115,64 +1225,153 @@ export class PilotSwarmManagementClient {
         const reason = options.reason ?? `Restarting system session ${plan.agent.id}`;
         const existingRow = await this._catalog.getSession(sessionId);
         const previousSessionExisted = Boolean(existingRow);
-        if (existingRow && !existingRow.isSystem) {
-            throw new Error(`Session ${sessionId.slice(0, 8)} exists but is not a system session`);
-        }
-        if (existingRow) {
-            if (disposition === "complete") {
-                const view = await this.getSession(sessionId).catch(() => null);
-                if (view && view.status !== "completed" && view.status !== "failed" && view.status !== "cancelled") {
-                    try {
-                        await this.sendCommand(sessionId, {
-                            cmd: "done",
-                            id: buildLifecycleCommandId("done-system-restart"),
-                            args: { reason },
-                        });
-                        await this._waitForSession(sessionId, (current) => current != null && (current.status === "completed" || current.status === "failed" || current.status === "cancelled"), options.timeoutMs ?? SESSION_COMMAND_SETTLE_TIMEOUT_MS);
-                    }
-                    catch (err) {
-                        if (!isIgnorableRestartCommandError(err))
-                            throw err;
-                    }
-                }
-                await this._deleteSystemOrchestrationInstance(sessionId);
-                await this._archiveSystemSessionForRestart(sessionId, "completed", reason);
+        const providerStore = this._catalog.providers;
+        let persistedRoute = null;
+        let persistedSource = null;
+        if (providerStore) {
+            const [defaults, overrides, credentials] = await Promise.all([
+                providerStore.getDefaults(null),
+                providerStore.listSystemAgentModels(),
+                providerStore.allCredentials(),
+            ]);
+            const override = overrides.find((candidate) => candidate.agentId === plan.agent.id);
+            if (override) {
+                persistedRoute = override;
+                persistedSource = "agent_override";
             }
-            else if (disposition === "terminate") {
-                await this._terminateSystemOrchestrationInstance(sessionId, reason);
-                await this._archiveSystemSessionForRestart(sessionId, "cancelled", `Terminated for restart: ${reason}`);
+            else if (defaults.system.provider && defaults.system.model) {
+                persistedRoute = defaults.system;
+                persistedSource = "system_default";
             }
             else {
-                await this._deleteSystemOrchestrationInstance(sessionId);
-                await this._archiveSystemSessionForRestart(sessionId, "failed", `Hard-deleted for restart: ${reason}`);
+                persistedRoute = this._firstAvailableTuple(credentials, (provider) => provider.class === "shared" || provider.systemUseEnabled === true);
+                persistedSource = persistedRoute ? "first_available" : null;
             }
         }
-        const defaultModel = options.model ?? this._modelProviders?.defaultModel ?? existingRow?.model;
+        let defaultModel = options.model
+            ?? persistedRoute?.model
+            ?? existingRow?.model
+            ?? this._modelProviders?.defaultModel;
         if (!defaultModel) {
             throw new Error("Cannot restart system session without a configured default model");
         }
-        const startResults = await startSystemAgents({
-            catalog: this._catalog,
-            duroxideClient: this._duroxideClient,
-            agents: this._systemAgents,
-            defaultModel,
-            ...(options.reasoningEffort ? { defaultReasoningEffort: options.reasoningEffort } : {}),
-            blobEnabled: this.config.blobEnabled,
-            dehydrateThreshold: this.config.waitThreshold ?? DEFAULT_SYSTEM_AGENT_DEHYDRATE_THRESHOLD,
-            agentId: plan.agent.id,
-        });
-        const newSession = await this.getSession(sessionId).catch(() => null);
-        if (!newSession) {
-            throw new Error(`System session ${plan.agent.id} was not recreated`);
+        let restartReasoning = Object.prototype.hasOwnProperty.call(options, "reasoningEffort")
+            ? options.reasoningEffort ?? null
+            : persistedRoute?.reasoning ?? existingRow?.reasoningEffort ?? null;
+        let restartContext = Object.prototype.hasOwnProperty.call(options, "contextTier")
+            ? options.contextTier ?? null
+            : persistedRoute?.context ?? existingRow?.contextTier ?? null;
+        let restartSource = options.modelResolutionSource ?? persistedSource ?? existingRow?.modelResolutionSource ?? "manual_restart";
+        if (providerStore) {
+            if (!this._modelProviders) {
+                throw new Error("Cannot restart system session without a provider type catalog");
+            }
+            const credentials = await providerStore.allCredentials();
+            const validated = resolveRuntimeModelSelection(this._modelProviders, credentials, {
+                requestedModel: defaultModel,
+                requestedReasoning: restartReasoning,
+                requestedContext: restartContext,
+                eligible: (provider) => provider.class === "shared" || provider.systemUseEnabled === true,
+            });
+            defaultModel = validated.model;
+            restartReasoning = validated.reasoning;
+            restartContext = validated.context;
+            if (!options.modelResolutionSource && !persistedSource)
+                restartSource = validated.source;
+        }
+        const operationId = options.operationId ?? `manual:${buildLifecycleCommandId("system-restart")}`;
+        const claimId = buildLifecycleCommandId("system-restart-claim");
+        if (providerStore) {
+            const claim = await providerStore.claimSystemRestart({
+                agentId: plan.agent.id,
+                operationId,
+                claimId,
+                model: defaultModel,
+                reasoning: restartReasoning,
+                context: restartContext,
+                disposition,
+            });
+            if (claim !== "claimed") {
+                return {
+                    agentId: plan.agent.id,
+                    agentName: plan.agent.name,
+                    sessionId,
+                    disposition,
+                    previousSessionExisted,
+                    startResults: [],
+                    skippedReason: claim,
+                };
+            }
+        }
+        if (existingRow && !existingRow.isSystem) {
+            throw new Error(`Session ${sessionId.slice(0, 8)} exists but is not a system session`);
+        }
+        try {
+            if (existingRow) {
+                if (disposition === "complete") {
+                    const view = await this.getSession(sessionId).catch(() => null);
+                    if (view && view.status !== "completed" && view.status !== "failed" && view.status !== "cancelled") {
+                        try {
+                            await this.sendCommand(sessionId, {
+                                cmd: "done",
+                                id: buildLifecycleCommandId("done-system-restart"),
+                                args: { reason },
+                            });
+                            await this._waitForSession(sessionId, (current) => current != null && (current.status === "completed" || current.status === "failed" || current.status === "cancelled"), options.timeoutMs ?? SESSION_COMMAND_SETTLE_TIMEOUT_MS);
+                        }
+                        catch (err) {
+                            if (!isIgnorableRestartCommandError(err))
+                                throw err;
+                        }
+                    }
+                    await this._deleteSystemOrchestrationInstance(sessionId);
+                    await this._archiveSystemSessionForRestart(sessionId, "completed", reason);
+                }
+                else if (disposition === "terminate") {
+                    await this._terminateSystemOrchestrationInstance(sessionId, reason);
+                    await this._archiveSystemSessionForRestart(sessionId, "cancelled", `Terminated for restart: ${reason}`);
+                }
+                else {
+                    await this._deleteSystemOrchestrationInstance(sessionId);
+                    await this._archiveSystemSessionForRestart(sessionId, "failed", `Hard-deleted for restart: ${reason}`);
+                }
+            }
+            const startResults = await startSystemAgents({
+                catalog: this._catalog,
+                duroxideClient: this._duroxideClient,
+                agents: this._systemAgents,
+                defaultModel,
+                defaultReasoningEffort: restartReasoning,
+                defaultContextTier: restartContext,
+                modelResolutionSource: restartSource,
+                blobEnabled: this.config.blobEnabled,
+                dehydrateThreshold: this.config.waitThreshold ?? DEFAULT_SYSTEM_AGENT_DEHYDRATE_THRESHOLD,
+                agentId: plan.agent.id,
+                // The retained session id already has ledger rows from earlier
+                // lifetimes; advance its ledger base so the new lifetime's
+                // settles land on fresh keys instead of silently colliding.
+                ...(providerStore ? {
+                    prepareRetainedSessionLedger: async (sid) => { await providerStore.bumpLedgerBase(sid); },
+                } : {}),
+            });
+            const newSession = await this.getSession(sessionId).catch(() => null);
+            if (!newSession) {
+                throw new Error(`System session ${plan.agent.id} was not recreated`);
+            }
+            await providerStore?.finishSystemRestart(plan.agent.id, claimId, null);
+            return {
+                agentId: plan.agent.id,
+                agentName: plan.agent.name,
+                sessionId,
+                disposition,
+                previousSessionExisted,
+                startResults,
+            };
+        }
+        catch (error) {
+            await providerStore?.finishSystemRestart(plan.agent.id, claimId, error?.message || String(error));
+            throw error;
         }
-        return {
-            agentId: plan.agent.id,
-            agentName: plan.agent.name,
-            sessionId,
-            disposition,
-            previousSessionExisted,
-            startResults,
-        };
     }
     // ─── Session Events ──────────────────────────────────────
     /**
@@ -2035,6 +2234,956 @@ export class PilotSwarmManagementClient {
         await this._assertOrchestrationLive(orchId, sessionId, "sendCommand");
         await this._duroxideClient.enqueueEvent(orchId, "messages", JSON.stringify({ type: "cmd", ...command }));
     }
+    // ─── Provider budgets ────────────────────────────────────
+    //
+    // The capabilities of docs/proposals/providers-and-budgets-surface.md.
+    // Each one resolves the caller to a user id and hands that number, with
+    // the role they signed in as, to a `cms_provider_*` procedure. Nothing
+    // below asks whether the caller is allowed to do the thing: the procedure
+    // raises PROVIDER_FORBIDDEN / PROVIDER_NOT_FOUND when they are not, and
+    // that refusal is the same on every surface because it is made in one
+    // place. See provider-store.ts.
+    _requireProviders() {
+        this._ensureStarted();
+        const providers = this._catalog.providers;
+        if (!providers)
+            throw new Error("Provider budgets are not available on this deployment.");
+        return providers;
+    }
+    /**
+     * The caller as the procedures want them: a numeric user id and a role.
+     * The id lookup never creates a row, so an unknown caller stays `null`
+     * rather than being minted by a read.
+     */
+    async _providerActor(viewer) {
+        const store = this._requireProviders();
+        return {
+            store,
+            actor: await store.lookupUserId(viewer?.principal ?? null),
+            isAdmin: viewer?.isAdmin === true,
+        };
+    }
+    async _auditProviderMutation(viewer, action, target, details) {
+        await this._catalog.recordAuthzAudit({
+            actor: viewer.principal ? {
+                provider: viewer.principal.provider,
+                subject: viewer.principal.subject,
+                display: viewer.principal.email ?? viewer.principal.displayName ?? null,
+            } : null,
+            action,
+            target,
+            decision: "provider_change",
+            reason: null,
+            details: details ?? null,
+        }).catch(() => { });
+    }
+    _providerTypeModels(typeId) {
+        return this._modelProviders?.getModelsByProvider()
+            .find((group) => group.providerId === typeId)?.models ?? [];
+    }
+    _normalizeProviderTuple(row, tuple) {
+        const provider = String(tuple.provider || "").trim();
+        const requested = String(tuple.model || "").trim();
+        if (!provider || !requested) {
+            throw new ProviderError("PROVIDER_INVALID", "A default needs both a provider and model.");
+        }
+        const prefix = `${provider}:`;
+        const modelName = requested.startsWith(prefix)
+            ? requested.slice(prefix.length)
+            : (requested.includes(":") ? "" : requested);
+        if (!modelName) {
+            throw new ProviderError("PROVIDER_INVALID", `The model must belong to "${provider}": write it as "${provider}:<model>".`);
+        }
+        const descriptor = this._providerTypeModels(row.typeId)
+            .find((model) => model.modelName === modelName);
+        if (this._modelProviders && !descriptor) {
+            throw new ProviderError("PROVIDER_INVALID", `Provider type "${row.typeId}" does not offer model "${modelName}".`);
+        }
+        const reasoning = tuple.reasoning ?? descriptor?.defaultReasoningEffort ?? null;
+        if (reasoning && descriptor?.supportedReasoningEfforts?.length
+            && !descriptor.supportedReasoningEfforts.includes(reasoning)) {
+            throw new ProviderError("PROVIDER_INVALID", `Model ${provider}:${modelName} does not support reasoning effort '${reasoning}'.`);
+        }
+        const context = tuple.context ?? descriptor?.defaultContextTier ?? null;
+        if (context && descriptor?.supportedContextTiers?.length
+            && !descriptor.supportedContextTiers.includes(context)) {
+            throw new ProviderError("PROVIDER_INVALID", `Model ${provider}:${modelName} does not support context tier '${context}'.`);
+        }
+        return { provider, model: `${provider}:${modelName}`, reasoning, context };
+    }
+    async _validatedDefaultTuple(store, actor, isAdmin, tuple, scope) {
+        if (!tuple.provider)
+            return normalizeDefaultTuple(null);
+        const rows = await store.listProviders(actor, isAdmin);
+        const row = rows.find((candidate) => candidate.name === tuple.provider);
+        if (!row)
+            throw new ProviderError("PROVIDER_NOT_FOUND", `There is no provider named "${tuple.provider}".`);
+        if (scope === "user" && !row.usableByMe) {
+            throw new ProviderError("PROVIDER_NOT_FOUND", `There is no provider named "${tuple.provider}".`);
+        }
+        if (scope === "cluster" && row.class !== "shared") {
+            throw new ProviderError("PROVIDER_INVALID", "The cluster default must be a shared provider.");
+        }
+        if (scope === "system" && !row.systemEligible) {
+            throw new ProviderError("PROVIDER_INVALID", `Provider "${row.name}" is not enabled for system sessions.`);
+        }
+        const normalized = this._normalizeProviderTuple(row, tuple);
+        const credential = scope === "system"
+            ? await store.getSystemCredential(row.name)
+            : await store.getCredential(row.name, actor);
+        const modelName = normalized.model.slice(normalized.model.indexOf(":") + 1);
+        if (!credential || !this._modelProviders
+            || !resolveProviderCredential(this._modelProviders, credential, modelName)) {
+            throw new ProviderError("PROVIDER_INVALID", `Provider "${row.name}" does not have a usable credential and endpoint.`);
+        }
+        return normalized;
+    }
+    _firstAvailableTuple(credentials, eligible) {
+        if (!this._modelProviders)
+            return null;
+        for (const credential of credentials) {
+            if (!eligible(credential))
+                continue;
+            const first = this._providerTypeModels(credential.typeId)[0];
+            if (!first)
+                continue;
+            if (!resolveProviderCredential(this._modelProviders, credential, first.modelName))
+                continue;
+            return {
+                provider: credential.name,
+                model: `${credential.name}:${first.modelName}`,
+                reasoning: first.defaultReasoningEffort ?? null,
+                context: first.defaultContextTier ?? null,
+            };
+        }
+        return null;
+    }
+    _resolvedDefault(tuple, source) {
+        if (!tuple?.provider || !tuple.model)
+            return null;
+        return {
+            provider: tuple.provider,
+            model: tuple.model,
+            reasoningEffort: tuple.reasoning,
+            contextTier: tuple.context,
+            source,
+        };
+    }
+    /** Every shared provider plus the caller's own. Admins also see other people's, unusable. */
+    async listProviders(viewer) {
+        const { store, actor, isAdmin } = await this._providerActor(viewer);
+        return { providers: await store.listProviders(actor, isAdmin) };
+    }
+    /** Limits, what has been spent against them, reset times, and the caller's own ceiling. */
+    async getProviderStatus(viewer, names) {
+        const { store, actor, isAdmin } = await this._providerActor(viewer);
+        return { providers: await store.providerStatus(actor, isAdmin, names ?? null) };
+    }
+    /**
+     * Everything the provider table draws, in one read.
+     *
+     * Rows come back in render order — shared providers first, then the
+     * caller's own, each immediately followed by its model-scoped limits — so
+     * a table draws the array as it arrives and never asks a second time per
+     * provider.
+     *
+     * Every period reports a used figure whether or not a limit caps it. That
+     * is the fact `getProviderStatus` cannot carry: it lists limits, and a
+     * period with no limit has no limit to list.
+     */
+    async getProviderUsageGrid(viewer) {
+        const { store, actor, isAdmin } = await this._providerActor(viewer);
+        return { rows: await store.usageGrid(actor, isAdmin) };
+    }
+    /** Create a shared provider: anyone in the cluster may spend from it. */
+    /**
+     * Wake every session waiting on this provider.
+     *
+     * The durable timer a paused session sleeps on is only the BACKSTOP. What
+     * should actually release it is the change itself — a limit raised or
+     * removed, an allowance widened, a hold released, a missing name created
+     * again — and without this that promise was never kept: a session paused
+     * on a monthly limit would sleep out the backstop no matter what an
+     * administrator did.
+     *
+     * The wake is a nudge, not a decision. Each woken session re-enters the
+     * gate on its next turn and pauses again if the reason still holds, so a
+     * raise that is still not enough wakes nobody in the end — and waking
+     * after a change that releases no one costs one cheap re-check, because
+     * the gate runs before the model.
+     *
+     * Best-effort throughout. A failed wake leaves the backstop, which is
+     * exactly what it is for.
+     */
+    async _wakeProvidersPaused(providerName) {
+        const store = this._catalog?.providers;
+        if (!store || !this._duroxideClient)
+            return;
+        try {
+            const sessionIds = await store.pausedFor(providerName);
+            for (const sessionId of sessionIds) {
+                try {
+                    // The orchestration id is DERIVED, not stored: getSession
+                    // builds this same string at its top and then returns a
+                    // view that does not carry it. Reading it back off that
+                    // view gave undefined every time, so `if (!orchId)
+                    // continue` skipped every session and this whole function
+                    // has never woken anything. Releasing a hold, raising a
+                    // limit, widening an allowance, removing a limit and
+                    // creating a provider were all silent no-ops behind the
+                    // catch below, leaving the 6-hour backstop as the only
+                    // real release.
+                    const orchId = `session-${sessionId}`;
+                    await this._catalog.updateSession(sessionId, {
+                        state: "running", waitReason: null, lastActiveAt: new Date(),
+                    }).catch(() => { });
+                    await this._duroxideClient.enqueueEvent(orchId, "messages", JSON.stringify({
+                        prompt: PROVIDER_BUDGET_WAKE_PROMPT,
+                    }));
+                }
+                catch {
+                    // One unreachable session must not stop the others.
+                }
+            }
+        }
+        catch {
+            // The backstop timer still covers every one of them.
+        }
+    }
+    /**
+     * Refuse a provider type this deployment does not describe.
+     *
+     * The database cannot check it: the types live in the model-providers
+     * FILE, which SQL has never read. Without this, a typo created a
+     * provider that listed as an ordinary usable row and could never run a
+     * turn — buildRuntimeRegistry drops an instance whose type it does not
+     * know, silently, so the failure surfaced only as a session that waited
+     * for ever on a name that was right there in the table.
+     */
+    _assertKnownProviderType(typeId) {
+        const wanted = String(typeId ?? "").trim();
+        const known = this.getModelsByProvider().map((g) => g.providerId);
+        // No catalog at all is not evidence of a bad type — a deployment that
+        // has not loaded one yet would refuse everything.
+        if (known.length === 0)
+            return;
+        if (known.includes(wanted))
+            return;
+        throw new ProviderError("PROVIDER_INVALID", `No provider type named "${wanted}" on this deployment. `
+            + `It has ${known.slice(0, 6).join(", ")}${known.length > 6 ? ", …" : ""}.`);
+    }
+    async createProvider(viewer, input) {
+        const { store, actor, isAdmin } = await this._providerActor(viewer);
+        this._assertKnownProviderType(input.type);
+        const created = await store.createProvider({
+            name: input.name,
+            typeId: input.type,
+            class: "shared",
+            secretRef: input.credentials ?? null,
+            baseUrl: input.baseUrl ?? null,
+        }, actor, isAdmin);
+        await this._auditProviderMutation(viewer, "createProvider", created.name, { class: "shared", type: created.typeId });
+        // A name that did not resolve a moment ago now does.
+        await this._wakeProvidersPaused(input.name);
+        return created;
+    }
+    /** Create a provider of the caller's own, on their own credentials. Nobody else sees it. */
+    async createMyProvider(viewer, input) {
+        const { store, actor, isAdmin } = await this._providerActor(viewer);
+        if (actor === null) {
+            throw new ProviderError("PROVIDER_FORBIDDEN", "Sign in to add a personal provider.");
+        }
+        this._assertKnownProviderType(input.type);
+        const created = await store.createProvider({
+            name: input.name,
+            typeId: input.type,
+            class: "personal",
+            ownerUserId: actor,
+            secretRef: input.credentials ?? null,
+            baseUrl: input.baseUrl ?? null,
+        }, actor, isAdmin);
+        await this._wakeProvidersPaused(input.name);
+        await this._auditProviderMutation(viewer, "createMyProvider", created.name, { class: "personal", type: created.typeId });
+        return created;
+    }
+    /**
+     * Remove a shared provider. Its sessions are not moved anywhere: they
+     * wait on a name that no longer resolves, and the count says how many.
+     */
+    async deleteProvider(viewer, name) {
+        const { store, actor, isAdmin } = await this._providerActor(viewer);
+        const result = { name, waitingSessions: await store.deleteProvider(name, actor, isAdmin) };
+        await this._auditProviderMutation(viewer, "deleteProvider", name, { waitingSessions: result.waitingSessions });
+        return result;
+    }
+    /**
+     * Remove one of the caller's own providers. The same call as
+     * `deleteProvider`: `cms_provider_delete` refuses a name the caller may
+     * not touch, so the two differ only in which door offers them.
+     */
+    async deleteMyProvider(viewer, name) {
+        // The /me namespace holds ONLY the caller's own personal providers.
+        // Delegating straight to deleteProvider let an admin delete a SHARED
+        // provider through this route, and answered "forbidden" for shared
+        // names — an existence oracle. Anything that is not the caller's own
+        // personal provider is a name this namespace has never heard of.
+        const { store, actor } = await this._providerActor(viewer);
+        const rows = await store.listProviders(actor, false);
+        const mine = rows.find((row) => row.name === name && row.class === "personal" && row.ownerUserId === actor);
+        if (!mine) {
+            throw new ProviderError("PROVIDER_NOT_FOUND", `there is no provider named "${name}"`);
+        }
+        const result = { name, waitingSessions: await store.deleteProvider(name, actor, false) };
+        await this._auditProviderMutation(viewer, "deleteMyProvider", name, { waitingSessions: result.waitingSessions });
+        return result;
+    }
+    async clearProviderRoutingDependencies(viewer, name) {
+        const { store, actor, isAdmin } = await this._providerActor(viewer);
+        const result = await store.clearRoutingDependencies(name, actor, isAdmin);
+        await this._auditProviderMutation(viewer, "clearProviderRoutingDependencies", name, result);
+        return { name, ...result };
+    }
+    /**
+     * Save one limit. The same (period, scope) replaces what was there.
+     * `seededTokens` is what this period had already spent when the limit
+     * landed — a limit counts from the current window, it never resets it.
+     */
+    async setProviderLimit(viewer, input) {
+        const { store, actor, isAdmin } = await this._providerActor(viewer);
+        // Validate here, not in Postgres: an unparsable or fractional value
+        // used to reach the proc and come back as a raw 22P02 dressed up as
+        // an internal server error.
+        const tokens = Number(input.tokens);
+        if (!Number.isSafeInteger(tokens) || tokens < 0) {
+            throw new ProviderError("PROVIDER_INVALID", "A limit is a whole number of tokens, zero or more.");
+        }
+        const saved = await store.setLimit({
+            name: input.provider,
+            period: input.period,
+            modelQualified: input.model ?? null,
+            limitTokens: tokens,
+        }, actor, isAdmin);
+        await this._wakeProvidersPaused(input.provider);
+        return saved;
+    }
+    /** Drop one limit. `removed` is false when that (period, scope) had none. */
+    async removeProviderLimit(viewer, input) {
+        const { store, actor, isAdmin } = await this._providerActor(viewer);
+        const removed = await store.removeLimit(input.provider, input.period, input.model ?? null, actor, isAdmin);
+        await this._wakeProvidersPaused(input.provider);
+        return { removed };
+    }
+    /** The share of each of a shared provider's limits that one person may use. 100 is full. */
+    async setProviderAllowance(viewer, input) {
+        const { store, actor, isAdmin } = await this._providerActor(viewer);
+        const allowancePct = await store.setAllowance(input.provider, Number(input.pct), actor, isAdmin);
+        await this._wakeProvidersPaused(input.provider);
+        return { name: input.provider, allowancePct };
+    }
+    /**
+     * Pause new turns against a provider, independently of any limit. With
+     * neither an end time nor a release the hold has no end, and only
+     * another call lifts it.
+     */
+    async setProviderHold(viewer, input) {
+        const { store, actor, isAdmin } = await this._providerActor(viewer);
+        const release = input.release === true;
+        const untilUtc = release ? null : (input.untilUtc ?? null);
+        if (untilUtc !== null) {
+            const parsed = Date.parse(untilUtc);
+            if (Number.isNaN(parsed)) {
+                throw new ProviderError("PROVIDER_INVALID", `"${untilUtc}" is not a timestamp.`);
+            }
+            // A hold that has already ended holds nothing; accepting one and
+            // echoing it back as set is the write-path lie the 2026-08-21
+            // audit flagged. The Edit sheet validates too, but the API must
+            // not trust the sheet.
+            if (parsed <= Date.now()) {
+                throw new ProviderError("PROVIDER_INVALID", "A hold must end in the future.");
+            }
+        }
+        const indefinite = !release && !untilUtc;
+        await store.setHold(input.provider, { untilUtc, indefinite }, actor, isAdmin);
+        await this._wakeProvidersPaused(input.provider);
+        return { name: input.provider, holdUntilUtc: untilUtc, holdIndefinite: indefinite };
+    }
+    /** Compatibility read: configured ordinary defaults plus system routing. */
+    async getDefaults(viewer) {
+        const { store, actor, isAdmin } = await this._providerActor(viewer);
+        return store.getDefaults(actor);
+    }
+    /** @deprecated Use setModelDefault({ scope: "cluster", ... }). */
+    async setClusterDefault(viewer, tuple) {
+        return this.setModelDefault(viewer, {
+            scope: "cluster",
+            provider: tuple.provider,
+            model: tuple.model,
+            reasoningEffort: tuple.reasoning,
+            contextTier: tuple.context,
+        });
+    }
+    /** @deprecated Use setModelDefault({ scope: "user", ... }). */
+    async setMyDefault(viewer, tuple) {
+        return this.setModelDefault(viewer, {
+            scope: "user",
+            provider: tuple?.provider ?? null,
+            model: tuple?.model ?? null,
+            reasoningEffort: tuple?.reasoning,
+            contextTier: tuple?.context,
+        });
+    }
+    async setModelDefault(viewer, input) {
+        const { store, actor, isAdmin } = await this._providerActor(viewer);
+        if (input.scope !== "user" && input.scope !== "cluster") {
+            throw new ProviderError("PROVIDER_INVALID", "scope must be user or cluster.");
+        }
+        if (input.scope === "cluster" && !isAdmin) {
+            throw new ProviderError("PROVIDER_FORBIDDEN", "Only an administrator can set the cluster default.");
+        }
+        const requested = normalizeDefaultTuple({
+            provider: input.provider,
+            model: input.model,
+            reasoning: input.reasoningEffort ?? null,
+            context: input.contextTier ?? null,
+        });
+        const next = await this._validatedDefaultTuple(store, actor, isAdmin, requested, input.scope);
+        if (input.scope === "cluster")
+            await store.setClusterDefault(next, isAdmin);
+        else
+            await store.setUserDefault(actor, next);
+        await this._auditProviderMutation(viewer, "setModelDefault", next.provider, {
+            scope: input.scope, model: next.model, cleared: next.provider === null,
+        });
+        return next;
+    }
+    async setProviderSystemUse(viewer, input) {
+        const { store, actor, isAdmin } = await this._providerActor(viewer);
+        const provider = String(input.provider || "").trim();
+        if (!provider)
+            throw new ProviderError("PROVIDER_INVALID", "A provider name is required.");
+        if (input.enabled === true) {
+            const rows = await store.listProviders(actor, isAdmin);
+            const row = rows.find((candidate) => candidate.name === provider);
+            if (!row || row.class !== "personal" || !row.usableByMe) {
+                throw new ProviderError("PROVIDER_NOT_FOUND", `There is no provider named "${provider}".`);
+            }
+            const first = row ? this._providerTypeModels(row.typeId)[0] : null;
+            const credential = await store.getCredential(provider, actor);
+            if (!row || !first || !credential || !this._modelProviders
+                || !resolveProviderCredential(this._modelProviders, credential, first.modelName)) {
+                throw new ProviderError("PROVIDER_INVALID", `Provider "${provider}" does not have a usable credential and endpoint.`);
+            }
+        }
+        const systemUseEnabled = await store.setSystemUse(provider, input.enabled === true, actor, isAdmin);
+        await this._auditProviderMutation(viewer, "setProviderSystemUse", provider, { enabled: systemUseEnabled });
+        return { provider, systemUseEnabled };
+    }
+    async getLegacyProviderMigrationStatus(viewer) {
+        const { store, isAdmin } = await this._providerActor(viewer);
+        if (!isAdmin)
+            throw new ProviderError("PROVIDER_FORBIDDEN", "Only an administrator can read legacy provider migration status.");
+        return store.getLegacyKeyMigrationStatus();
+    }
+    async adoptLegacySystemGitHubCopilotKey(viewer, input) {
+        const { store, actor, isAdmin } = await this._providerActor(viewer);
+        if (!isAdmin)
+            throw new ProviderError("PROVIDER_FORBIDDEN", "Only an administrator can adopt the legacy System key.");
+        const adopted = await store.adoptLegacySystemGitHubKey(String(input.name || "").trim(), actor, isAdmin);
+        await this._auditProviderMutation(viewer, "adoptLegacySystemGitHubCopilotKey", adopted.name, {
+            class: "personal", systemUseEnabled: true,
+        });
+        return { provider: adopted, status: await store.getLegacyKeyMigrationStatus() };
+    }
+    async getModelDefaults(viewer) {
+        const { store, actor, isAdmin } = await this._providerActor(viewer);
+        const [configured, credentials, systemOverrides] = await Promise.all([
+            store.getDefaults(actor),
+            store.allCredentials(),
+            store.listSystemAgentModels(),
+        ]);
+        const clusterFallback = this._firstAvailableTuple(credentials, (credential) => credential.class === "shared");
+        const userFallback = this._firstAvailableTuple(credentials, (credential) => credential.class === "shared" || (actor !== null && credential.ownerUserId === actor));
+        const systemFallback = this._firstAvailableTuple(credentials, (credential) => credential.class === "shared" || credential.systemUseEnabled === true);
+        const resolveConfigured = (candidates, eligible, fallback) => {
+            try {
+                if (candidates.some((candidate) => candidate.tuple.provider || candidate.tuple.model)) {
+                    const resolved = resolveRuntimeModelSelection(this._modelProviders, credentials, {
+                        defaults: candidates,
+                        eligible,
+                    });
+                    return { tuple: resolved, source: resolved.source, error: null };
+                }
+                return { tuple: fallback, source: "first_available", error: null };
+            }
+            catch (error) {
+                return { tuple: null, source: "first_available", error: error?.message || String(error) };
+            }
+        };
+        const clusterResolution = this._modelProviders
+            ? resolveConfigured([{ tuple: configured.cluster, source: "cluster_default" }], (credential) => credential.class === "shared", clusterFallback)
+            : { tuple: null, source: "first_available", error: "Provider type catalog is unavailable." };
+        const userCandidates = configured.mine.provider || configured.mine.model
+            ? [{ tuple: configured.mine, source: "user_default" }]
+            : configured.cluster.provider || configured.cluster.model
+                ? [{ tuple: configured.cluster, source: "cluster_default" }]
+                : [];
+        const userResolution = this._modelProviders
+            ? resolveConfigured(userCandidates, (credential) => credential.class === "shared" || (actor !== null && credential.ownerUserId === actor), userFallback)
+            : { tuple: null, source: "first_available", error: "Provider type catalog is unavailable." };
+        const systemResolution = this._modelProviders
+            ? resolveConfigured([{ tuple: configured.system, source: "system_default" }], (credential) => credential.class === "shared" || credential.systemUseEnabled === true, systemFallback)
+            : { tuple: null, source: "first_available", error: "Provider type catalog is unavailable." };
+        return {
+            userSession: {
+                configured: configured.mine,
+                effective: this._resolvedDefault(userResolution.tuple, userResolution.source),
+                error: userResolution.error,
+            },
+            clusterSession: {
+                configured: configured.cluster,
+                effective: this._resolvedDefault(clusterResolution.tuple, clusterResolution.source),
+                error: clusterResolution.error,
+            },
+            system: {
+                configured: isAdmin ? configured.system : normalizeDefaultTuple(null),
+                effective: isAdmin
+                    ? this._resolvedDefault(systemResolution.tuple, systemResolution.source)
+                    : null,
+                error: isAdmin ? systemResolution.error : null,
+                updatedBy: isAdmin ? configured.systemUpdatedBy : null,
+                updatedAt: isAdmin ? configured.systemUpdatedAt : null,
+            },
+            systemOverrides: isAdmin ? systemOverrides : [],
+        };
+    }
+    async setSystemModelDefault(viewer, input) {
+        const { store, actor, isAdmin } = await this._providerActor(viewer);
+        if (!isAdmin)
+            throw new ProviderError("PROVIDER_FORBIDDEN", "Only an administrator can set the system default.");
+        const requested = normalizeDefaultTuple({
+            provider: input.provider,
+            model: input.model,
+            reasoning: input.reasoningEffort ?? null,
+            context: input.contextTier ?? null,
+        });
+        const configured = await this._validatedDefaultTuple(store, actor, isAdmin, requested, "system");
+        const disposition = input.restartExisting
+            ? normalizeSystemRestartDisposition(input.restartExisting.disposition)
+            : null;
+        await store.setSystemDefault(actor, isAdmin, configured);
+        await this._auditProviderMutation(viewer, "setSystemModelDefault", configured.provider, {
+            model: configured.model,
+            cleared: configured.provider === null,
+            restartDisposition: disposition,
+        });
+        const defaults = await this.getModelDefaults(viewer);
+        if (!input.restartExisting) {
+            return { configured, effective: defaults.system.effective, restart: null };
+        }
+        if (!defaults.system.effective) {
+            throw new ProviderError("PROVIDER_INVALID", "No system-eligible provider is available for restart.");
+        }
+        const operationId = [
+            "system-default",
+            disposition,
+            defaults.system.effective.model,
+            defaults.system.effective.reasoningEffort ?? "",
+            defaults.system.effective.contextTier ?? "",
+        ].join(":");
+        const overridden = new Set(defaults.systemOverrides.map((override) => override.agentId));
+        const candidatePlans = this._getSystemAgentPlans().filter((plan) => !overridden.has(plan.agent.id));
+        const plans = [];
+        for (const plan of candidatePlans) {
+            const row = await this._catalog.getSession(plan.sessionId).catch(() => null);
+            const rollout = await store.getSystemRestart(plan.agent.id);
+            const retryingSameOperation = rollout?.operationId === operationId
+                && rollout.status !== "complete";
+            const live = Boolean(row && !row.deletedAt
+                && !["completed", "failed", "error", "cancelled"].includes(row.state));
+            if (!retryingSameOperation && !live)
+                continue;
+            if (!retryingSameOperation && row.orchestrationId && row.state !== "pending"
+                && row.model === defaults.system.effective.model
+                && (row.reasoningEffort ?? null) === (defaults.system.effective.reasoningEffort ?? null)
+                && (row.contextTier ?? null) === (defaults.system.effective.contextTier ?? null))
+                continue;
+            plans.push(plan);
+        }
+        const failures = [];
+        let restarted = 0;
+        for (const plan of plans) {
+            try {
+                const outcome = await this.restartSystemSession(plan.agent.id, {
+                    disposition: disposition,
+                    model: defaults.system.effective.model,
+                    reasoningEffort: defaults.system.effective.reasoningEffort,
+                    contextTier: defaults.system.effective.contextTier,
+                    modelResolutionSource: defaults.system.effective.source,
+                    operationId,
+                    reason: "Applying the configured system model default",
+                });
+                if (!outcome.skippedReason)
+                    restarted += 1;
+            }
+            catch (error) {
+                failures.push({ agentId: plan.agent.id, error: error?.message || String(error) });
+            }
+        }
+        return {
+            configured,
+            effective: defaults.system.effective,
+            restart: { requested: true, disposition: disposition, affected: plans.length, restarted, failures },
+        };
+    }
+    async setSystemSessionModel(viewer, input) {
+        const { store, actor, isAdmin } = await this._providerActor(viewer);
+        if (!isAdmin)
+            throw new ProviderError("PROVIDER_FORBIDDEN", "Only an administrator can set a system-agent model.");
+        const plan = this._resolveSystemAgentPlan(input.agentId);
+        const next = await this._validatedDefaultTuple(store, actor, isAdmin, normalizeDefaultTuple({
+            provider: input.provider,
+            model: input.model,
+            reasoning: input.reasoningEffort ?? null,
+            context: input.contextTier ?? null,
+        }), "system");
+        await store.setSystemAgentModel(plan.agent.id, actor, isAdmin, next);
+        await this._auditProviderMutation(viewer, "setSystemSessionModel", plan.agent.id, {
+            provider: next.provider, model: next.model,
+        });
+        const row = await this._catalog.getSession(plan.sessionId).catch(() => null);
+        if (row && !row.deletedAt && row.orchestrationId) {
+            await this.sendCommand(plan.sessionId, {
+                cmd: "set_model",
+                id: buildLifecycleCommandId("set-system-model"),
+                args: {
+                    model: next.model,
+                    reasoningEffort: next.reasoning,
+                    contextTier: next.context,
+                    source: "system_default",
+                },
+            });
+        }
+        return (await store.listSystemAgentModels()).find((override) => override.agentId === plan.agent.id);
+    }
+    async clearSystemSessionModel(viewer, agentId) {
+        const { store, actor, isAdmin } = await this._providerActor(viewer);
+        if (!isAdmin)
+            throw new ProviderError("PROVIDER_FORBIDDEN", "Only an administrator can clear a system-agent model.");
+        const plan = this._resolveSystemAgentPlan(agentId);
+        const cleared = await store.clearSystemAgentModel(plan.agent.id, actor, isAdmin);
+        if (cleared)
+            await this._auditProviderMutation(viewer, "clearSystemSessionModel", plan.agent.id, { cleared: true });
+        if (cleared) {
+            const defaults = await this.getModelDefaults(viewer);
+            const row = await this._catalog.getSession(plan.sessionId).catch(() => null);
+            if (row && !row.deletedAt && row.orchestrationId && defaults.system.effective) {
+                await this.sendCommand(plan.sessionId, {
+                    cmd: "set_model",
+                    id: buildLifecycleCommandId("clear-system-model"),
+                    args: {
+                        model: defaults.system.effective.model,
+                        reasoningEffort: defaults.system.effective.reasoningEffort,
+                        contextTier: defaults.system.effective.contextTier,
+                        source: "system_default",
+                    },
+                });
+            }
+        }
+        return { agentId: plan.agent.id, cleared };
+    }
+    /**
+     * Where the tokens went: totals, the daily chart, and one breakdown, over
+     * the same filters. Three reads because they group differently, one
+     * answer because a report that shows a total and a chart from different
+     * filters is a report nobody can act on.
+     *
+     * The breakdown asks for one row more than it returns, so `truncated`
+     * reports the cut rather than guessing at it.
+     */
+    async getProviderUsage(viewer, query = {}) {
+        const { store, actor, isAdmin } = await this._providerActor(viewer);
+        const dimension = PROVIDER_USAGE_DIMENSIONS.includes(query.dimension)
+            ? query.dimension
+            : "provider";
+        const limit = clampInteger(query.limit ?? undefined, 40, 1, 200);
+        const filters = {
+            days: clampInteger(query.days ?? undefined, 7, 1, 365),
+            // `mine` beats a supplied id: it is the one form that cannot name
+            // anybody but the caller.
+            ownerUserId: query.mine === true ? actor : (query.ownerUserId ?? null),
+            provider: query.provider ?? null,
+            model: query.model ?? null,
+            sessionId: query.sessionId ?? null,
+            chargeClass: query.chargeClass ?? null,
+        };
+        const [totals, daily, breakdown] = await Promise.all([
+            store.usageTotals(actor, isAdmin, filters),
+            store.usageDaily(actor, isAdmin, filters),
+            store.usageBreakdown(actor, isAdmin, dimension, filters, limit + 1),
+        ]);
+        return {
+            totals,
+            daily,
+            breakdown: breakdown.slice(0, limit),
+            dimension,
+            truncated: breakdown.length > limit,
+        };
+    }
+    /** Sessions waiting on a limit right now, with what is holding each one. */
+    async listPausedSessions(viewer) {
+        const { store, actor, isAdmin } = await this._providerActor(viewer);
+        return { sessions: await store.listPaused(actor, isAdmin) };
+    }
+    // ─── Agent packages / worker registry ────────────────────
+    _agentPackagePrincipal(owner, isAdmin) {
+        if (owner?.provider && owner?.subject) {
+            return { provider: owner.provider, subject: owner.subject };
+        }
+        if (isAdmin)
+            return null;
+        const error = new Error("agent-package operations require an authenticated principal");
+        error.code = "FORBIDDEN";
+        throw error;
+    }
+    _agentPackageSelector(selector, isAdmin = false) {
+        if (!selector || typeof selector !== "object")
+            return null;
+        const scope = selector.scope === "shared" || selector.scope === "user" ? selector.scope : null;
+        const provider = String(selector.ownerProvider || selector.owner?.provider || "").trim();
+        const subject = String(selector.ownerSubject || selector.owner?.subject || "").trim();
+        const owner = isAdmin && provider && subject ? { provider, subject } : null;
+        if (!scope && !owner)
+            return null;
+        return { ...(scope ? { scope } : {}), ...(owner ? { owner } : {}) };
+    }
+    async _mapAgentPackageErrors(run) {
+        try {
+            return await run();
+        }
+        catch (error) {
+            const message = String(error?.message || "");
+            if (/AGENT_(?:PACKAGE|SOURCE)_[A-Z_]*FORBIDDEN/.test(message))
+                error.code = "FORBIDDEN";
+            else if (/AGENT_(?:PACKAGE|SOURCE)_[A-Z_]*NOT_FOUND/.test(message))
+                error.code = "NOT_FOUND";
+            else if (/AGENT_PACKAGE_(?:SEMVER_CONFLICT|SCOPE_MISMATCH|NAME_TAKEN|AMBIGUOUS)/.test(message))
+                error.code = "CONFLICT";
+            else if (/AGENT_PACKAGE_(?:BAD_(?:SCOPE|NAME)|NO_OWNER|RESERVED_NAME)/.test(message))
+                error.code = "INVALID_REQUEST";
+            throw error;
+        }
+    }
+    _requireAgentPackageArtifacts() {
+        if (!this._artifactStore) {
+            throw new Error("agent-package artifact operations require an artifact store in direct mode");
+        }
+        return this._artifactStore;
+    }
+    async listAgentPackages(owner, isAdmin) {
+        this._ensureStarted();
+        return this._catalog.listAgentPackages(this._agentPackagePrincipal(owner, isAdmin), isAdmin);
+    }
+    async getAgentPackage(name, owner, isAdmin, selector) {
+        this._ensureStarted();
+        return this._catalog.getAgentPackage(name, this._agentPackagePrincipal(owner, isAdmin), isAdmin, this._agentPackageSelector(selector, isAdmin));
+    }
+    async listAgentWorkerState() {
+        this._ensureStarted();
+        return this._catalog.listAgentWorkerState();
+    }
+    async listWorkers() {
+        this._ensureStarted();
+        return this._catalog.listWorkers();
+    }
+    async setAgentPackageScope(name, scope, owner, isAdmin, selector) {
+        this._ensureStarted();
+        const targetScope = scope === "shared" ? "shared" : "user";
+        const principal = this._agentPackagePrincipal(owner, isAdmin);
+        const ownerOverride = this._agentPackageSelector(selector, isAdmin)?.owner ?? null;
+        let sourceSelector = null;
+        if (targetScope === "user")
+            sourceSelector = { scope: "shared", ...(ownerOverride ? { owner: ownerOverride } : {}) };
+        else if (ownerOverride)
+            sourceSelector = { scope: "user", owner: ownerOverride };
+        await this._mapAgentPackageErrors(() => this._catalog.setAgentPackageScope(name, targetScope, principal, isAdmin, sourceSelector));
+        return { ok: true };
+    }
+    async setAgentPackageEnabled(name, enabled, owner, isAdmin, selector) {
+        this._ensureStarted();
+        await this._mapAgentPackageErrors(() => this._catalog.setAgentPackageEnabled(name, Boolean(enabled), this._agentPackagePrincipal(owner, isAdmin), isAdmin, this._agentPackageSelector(selector, isAdmin)));
+        return { ok: true };
+    }
+    async pinAgentPackageVersion(name, semver, owner, isAdmin, selector) {
+        this._ensureStarted();
+        await this._mapAgentPackageErrors(() => this._catalog.pinAgentPackageVersion(name, semver, this._agentPackagePrincipal(owner, isAdmin), isAdmin, this._agentPackageSelector(selector, isAdmin)));
+        return { ok: true };
+    }
+    async deleteAgentPackage(name, owner, isAdmin, selector) {
+        this._ensureStarted();
+        await this._mapAgentPackageErrors(() => deleteAgentPackageEverywhere({ catalog: this._catalog, artifactStore: this._requireAgentPackageArtifacts() }, name, this._agentPackagePrincipal(owner, isAdmin), isAdmin, this._agentPackageSelector(selector, isAdmin)));
+        return { ok: true };
+    }
+    async publishAgentPackageDirectory(dir, scope, owner, isAdmin, opts = {}) {
+        this._ensureStarted();
+        return this._mapAgentPackageErrors(() => publishAgentPackageDir({ catalog: this._catalog, artifactStore: this._requireAgentPackageArtifacts() }, {
+            dir,
+            scope,
+            owner: this._agentPackagePrincipal(owner, isAdmin),
+            createdBy: opts.createdBy ?? null,
+            isAdmin,
+            ...(opts.reservedAgentNames?.length ? { validate: { reservedAgentNames: opts.reservedAgentNames } } : {}),
+        }));
+    }
+    async uploadAgentPackage(files, scope, owner, isAdmin, opts = {}) {
+        const invalid = (message) => Object.assign(new Error(message), { code: "INVALID_REQUEST" });
+        const tooLarge = (message) => Object.assign(new Error(message), { code: "PAYLOAD_TOO_LARGE" });
+        if (!Array.isArray(files) || files.length === 0)
+            throw invalid("upload requires files: [{ path, contentBase64 }]");
+        if (files.length > 2_000)
+            throw tooLarge("upload exceeds 2000 files");
+        const normalizedPaths = files.map((file) => String(file?.path || ""));
+        const pathSet = new Set();
+        for (const rel of normalizedPaths) {
+            if (pathSet.has(rel))
+                throw invalid(`upload contains duplicate file path: ${rel}`);
+            const parts = rel.split("/");
+            for (let index = 1; index < parts.length; index++) {
+                const parent = parts.slice(0, index).join("/");
+                if (pathSet.has(parent))
+                    throw invalid(`upload path conflicts with file path: ${parent} and ${rel}`);
+            }
+            for (const existing of pathSet) {
+                if (existing.startsWith(`${rel}/`))
+                    throw invalid(`upload path conflicts with file path: ${rel} and ${existing}`);
+            }
+            pathSet.add(rel);
+        }
+        const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "ps-agent-upload-"));
+        try {
+            let total = 0;
+            for (const file of files) {
+                const rel = String(file?.path || "");
+                if (!rel || rel.startsWith("/") || rel.includes("\\") || rel.split("/").some((part) => part === "..")) {
+                    throw invalid(`upload file path is not a safe relative path: ${rel}`);
+                }
+                const encoded = String(file?.contentBase64 || "");
+                const remaining = 2 * 1024 * 1024 - total;
+                if (encoded.length > Math.ceil(remaining * 4 / 3) + 4)
+                    throw tooLarge("upload exceeds the 2 MB envelope");
+                const bytes = Buffer.from(encoded, "base64");
+                total += bytes.length;
+                if (total > 2 * 1024 * 1024)
+                    throw tooLarge("upload exceeds the 2 MB envelope");
+                const target = path.resolve(tmp, rel);
+                if (target === tmp || !target.startsWith(tmp + path.sep))
+                    throw invalid(`upload file path escapes the package root: ${rel}`);
+                fs.mkdirSync(path.dirname(target), { recursive: true });
+                fs.writeFileSync(target, bytes);
+            }
+            return await this.publishAgentPackageDirectory(tmp, scope, owner, isAdmin, opts);
+        }
+        catch (error) {
+            if (error instanceof AgentPackageValidationError) {
+                const wrapped = new Error(error.message);
+                wrapped.code = "VALIDATION_FAILED";
+                wrapped.validation = error.validation;
+                throw wrapped;
+            }
+            throw error;
+        }
+        finally {
+            fs.rmSync(tmp, { recursive: true, force: true });
+        }
+    }
+    async _agentPackageVersion(name, semver, owner, isAdmin, selector) {
+        this._ensureStarted();
+        return resolveAgentPackageVersion(this._catalog, name, this._agentPackagePrincipal(owner, isAdmin), isAdmin, this._agentPackageSelector(selector, isAdmin), semver);
+    }
+    async getAgentPackageTree(name, semver, owner, isAdmin, selector) {
+        this._ensureStarted();
+        const { version, entries } = await readAgentPackageVersionEntries({ catalog: this._catalog, artifactStore: this._requireAgentPackageArtifacts() }, name, this._agentPackagePrincipal(owner, isAdmin), isAdmin, this._agentPackageSelector(selector, isAdmin), semver);
+        const dirs = new Set();
+        const files = entries.map((entry) => {
+            const parts = entry.name.split("/");
+            for (let index = 1; index < parts.length; index++)
+                dirs.add(parts.slice(0, index).join("/"));
+            return { path: entry.name, size: entry.body.length };
+        }).sort((left, right) => left.path.localeCompare(right.path));
+        return { name, semver: version.semver, sha256: version.sha256, dirs: [...dirs].sort(), files };
+    }
+    async getAgentPackageFile(name, semver, filePath, owner, isAdmin, selector) {
+        this._ensureStarted();
+        const { version, entries } = await readAgentPackageVersionEntries({ catalog: this._catalog, artifactStore: this._requireAgentPackageArtifacts() }, name, this._agentPackagePrincipal(owner, isAdmin), isAdmin, this._agentPackageSelector(selector, isAdmin), semver);
+        const entry = entries.find((candidate) => candidate.name === filePath);
+        if (!entry)
+            throw Object.assign(new Error(`"${filePath}" is not in ${name}@${version.semver}`), { code: "NOT_FOUND" });
+        const binary = entry.body.includes(0);
+        let body = entry.body.subarray(0, 256 * 1024);
+        let text = "";
+        if (!binary) {
+            const decoder = new TextDecoder("utf-8", { fatal: true });
+            for (let trim = 0; trim <= 4; trim++) {
+                try {
+                    text = decoder.decode(trim ? body.subarray(0, body.length - trim) : body);
+                    if (trim)
+                        body = body.subarray(0, body.length - trim);
+                    break;
+                }
+                catch {
+                    if (trim === 4)
+                        text = body.toString("utf8");
+                }
+            }
+        }
+        return {
+            name, semver: version.semver, path: filePath, size: entry.body.length,
+            truncated: entry.body.length > body.length,
+            binary,
+            encoding: binary ? "base64" : "utf8",
+            content: binary ? body.toString("base64") : text,
+        };
+    }
+    async downloadAgentPackage(name, semver, owner, isAdmin, selector) {
+        this._ensureStarted();
+        const { version } = await this._agentPackageVersion(name, semver, owner, isAdmin, selector);
+        const body = await fetchAgentPackageTarGz(this._requireAgentPackageArtifacts(), version.artifactFilename, version.sha256);
+        return {
+            name,
+            semver: version.semver,
+            sha256: version.sha256,
+            filename: `${name}@${version.semver}.tgz`,
+            contentType: "application/gzip",
+            body,
+        };
+    }
+    async republishAgentPackageVersion(name, semver, targetScope, owner, isAdmin, opts = {}) {
+        this._ensureStarted();
+        const principal = this._agentPackagePrincipal(owner, isAdmin);
+        const target = targetScope === "shared" ? "shared" : "user";
+        const sourceScope = target === "shared" ? "user" : "shared";
+        return this._mapAgentPackageErrors(async () => {
+            const selectedOwner = this._agentPackageSelector(opts.selector, isAdmin)?.owner ?? null;
+            const { detail, version } = await this._agentPackageVersion(name, semver, principal, isAdmin, {
+                scope: sourceScope,
+                ...(selectedOwner ? { owner: selectedOwner } : {}),
+            });
+            const targz = await fetchAgentPackageTarGz(this._requireAgentPackageArtifacts(), version.artifactFilename, version.sha256);
+            const outcome = await publishPackedAgentPackage({ catalog: this._catalog, artifactStore: this._requireAgentPackageArtifacts() }, {
+                manifest: version.manifest,
+                targz,
+                sha256: version.sha256,
+                scope: target,
+                owner: principal,
+                createdBy: `republish of ${sourceScope} ${name}@${version.semver}`
+                    + (opts.createdBy ? ` by ${opts.createdBy}` : ""),
+                isAdmin,
+                sourceId: detail.sourceId ?? null,
+                commitSha: version.commitSha ?? null,
+            });
+            const { manifest: _manifest, ...summary } = outcome;
+            return summary;
+        });
+    }
     // ─── Models ──────────────────────────────────────────────
     /**
      * List all available models across all configured providers.
@@ -2043,6 +3192,7 @@ export class PilotSwarmManagementClient {
         if (!this._modelProviders)
             return [];
         return this._modelProviders.allModels.map((m) => ({
+            catalogKind: "provider_type",
             qualifiedName: m.qualifiedName,
             providerId: m.providerId,
             providerType: m.providerType,
@@ -2057,6 +3207,31 @@ export class PilotSwarmManagementClient {
             credentialAvailable: this.getModelCredentialStatus(m.qualifiedName).credentialAvailable,
         }));
     }
+    async listRuntimeModels(viewer) {
+        const typeModels = this.listModels();
+        const { store, actor, isAdmin } = await this._providerActor(viewer);
+        const [providers, credentials] = await Promise.all([
+            store.listProviders(actor, isAdmin),
+            store.allCredentials(),
+        ]);
+        const credentialByName = new Map(credentials.map((credential) => [credential.name, credential]));
+        const out = [];
+        for (const provider of providers.filter((candidate) => candidate.usableByMe)) {
+            const credential = credentialByName.get(provider.name);
+            for (const model of typeModels.filter((candidate) => candidate.providerId === provider.typeId)) {
+                const credentialAvailable = Boolean(credential && this._modelProviders
+                    && resolveProviderCredential(this._modelProviders, credential, model.modelName));
+                out.push({
+                    ...model,
+                    catalogKind: "runtime_provider",
+                    providerId: provider.name,
+                    qualifiedName: `${provider.name}:${model.modelName}`,
+                    credentialAvailable,
+                });
+            }
+        }
+        return out;
+    }
     /**
      * Get models grouped by provider for display.
      */
@@ -2064,6 +3239,7 @@ export class PilotSwarmManagementClient {
         if (!this._modelProviders)
             return [];
         return this._modelProviders.getModelsByProvider().map(g => ({
+            catalogKind: "provider_type",
             providerId: g.providerId,
             type: g.type,
             models: g.models.map((m) => ({