shortcutxl 0.4.0 → 0.4.2

package/dist/config.d.ts

@@ -14,18 +14,26 @@ export interface UpdateLaunchCommand {
 }
 /** Render a human-readable instruction for updating the shipped package. */
 export declare function getUpdateInstruction(packageName: string): string;
+/** Where and which release an update installs. */
+export interface UpdateTarget {
+    /** Advertised release; pinned so a registry whose `latest` lags cannot install an older one. */
+    version?: string;
+    /** npm global prefix of the running installation, so npm replaces what the user runs. */
+    npmPrefix?: string;
+}
 /**
  * Get the shell command to auto-update the agent package.
  */
-export declare function getUpdateCommand(packageName: string): string;
+export declare function getUpdateCommand(packageName: string, target?: UpdateTarget): string;
 /** Return the update as an executable and arguments for hosts that avoid shell command strings. */
-export declare function getUpdateLaunchCommand(packageName: string): UpdateLaunchCommand;
+export declare function getUpdateLaunchCommand(packageName: string, target?: UpdateTarget): UpdateLaunchCommand;
 /**
- * Get the base directory for resolving package assets (themes, package.json, README.md, CHANGELOG.md).
- * - For Node.js (dist/): returns __dirname (the dist/ directory)
- * - For tsx (src/): returns parent directory (the package root)
+ * Get the base directory for resolving package assets (themes, README.md, CHANGELOG.md).
+ * Defaults to the running package root; SHORTCUT_PACKAGE_DIR can select separate assets.
  */
 export declare function getPackageDir(): string;
+/** Locate the running code independently of an optional asset-directory override. */
+export declare function getRuntimePackageDir(): string;
 /**
  * Returns true when running directly from a source checkout (tsx / repo root),
  * not from an installed package payload.

package/dist/config.js

@@ -41,46 +41,62 @@ function detectInstallMethod() {
 /** Render a human-readable instruction for updating the shipped package. */
 export function getUpdateInstruction(packageName) {
     const method = detectInstallMethod();
+    const suffix = process.platform === 'win32' ? '.cmd' : '';
     switch (method) {
         case 'pnpm':
             return `Run: pnpm add -g ${packageName}`;
         case 'yarn':
             return `Run: yarn global add ${packageName}`;
         case 'npm':
-            return `Run: npm install -g ${packageName}`;
+            return `Run: npm${suffix} install -g ${packageName}`;
         default:
-            return `Run: npm install -g ${packageName}`;
+            return `Run: npm${suffix} install -g ${packageName}`;
     }
 }
 /**
  * Get the shell command to auto-update the agent package.
  */
-export function getUpdateCommand(packageName) {
-    const command = getUpdateLaunchCommand(packageName);
-    return [command.executable, ...command.args].join(' ');
+export function getUpdateCommand(packageName, target = {}) {
+    const command = getUpdateLaunchCommand(packageName, target);
+    return [command.executable, ...command.args.map(quoteShellArgument)].join(' ');
 }
 /** Return the update as an executable and arguments for hosts that avoid shell command strings. */
-export function getUpdateLaunchCommand(packageName) {
+export function getUpdateLaunchCommand(packageName, target = {}) {
+    const spec = target.version ? `${packageName}@${target.version}` : packageName;
     switch (detectInstallMethod()) {
         case 'pnpm':
-            return { executable: 'pnpm', args: ['add', '-g', packageName] };
+            return { executable: 'pnpm', args: ['add', '-g', spec] };
         case 'yarn':
-            return { executable: 'yarn', args: ['global', 'add', packageName] };
+            return { executable: 'yarn', args: ['global', 'add', spec] };
         case 'npm':
         default:
-            return { executable: 'npm', args: ['install', '-g', packageName] };
+            return {
+                executable: 'npm',
+                args: [
+                    'install',
+                    '-g',
+                    // Forward slashes keep Windows paths intact in both Git Bash and cmd.exe.
+                    ...(target.npmPrefix ? ['--prefix', target.npmPrefix.replaceAll('\\', '/')] : []),
+                    spec
+                ]
+            };
     }
 }
+/** Quote an argument for the POSIX shell or cmd.exe that runs the update command. */
+function quoteShellArgument(argument) {
+    return /^[\w@./:=+-]+$/.test(argument) ? argument : `"${argument.replaceAll('"', '')}"`;
+}
 // =============================================================================
 // Package Asset Paths (shipped with executable)
 // =============================================================================
 /**
- * Get the base directory for resolving package assets (themes, package.json, README.md, CHANGELOG.md).
- * - For Node.js (dist/): returns __dirname (the dist/ directory)
- * - For tsx (src/): returns parent directory (the package root)
+ * Get the base directory for resolving package assets (themes, README.md, CHANGELOG.md).
+ * Defaults to the running package root; SHORTCUT_PACKAGE_DIR can select separate assets.
  */
 export function getPackageDir() {
-    // Allow override via environment variable (useful for Nix/Guix where store paths tokenize poorly)
+    return getPackageDirOverride() ?? getRuntimePackageDir();
+}
+function getPackageDirOverride() {
     const envDir = process.env.SHORTCUT_PACKAGE_DIR;
     if (envDir) {
         if (envDir === '~')
@@ -89,7 +105,10 @@ export function getPackageDir() {
             return homedir() + envDir.slice(1);
         return envDir;
     }
-    // Node.js: walk up from __dirname until we find package.json
+    return undefined;
+}
+/** Locate the running code independently of an optional asset-directory override. */
+export function getRuntimePackageDir() {
     let dir = __dirname;
     while (dir !== dirname(dir)) {
         if (existsSync(join(dir, 'package.json'))) {
@@ -97,8 +116,8 @@ export function getPackageDir() {
         }
         dir = dirname(dir);
     }
-    // Fallback (shouldn't happen)
-    return __dirname;
+    // Standalone Nix/Guix layouts can keep their only package metadata with the assets.
+    return getPackageDirOverride() ?? __dirname;
 }
 /**
  * Returns true when running directly from a source checkout (tsx / repo root),
@@ -162,11 +181,6 @@ export function getExportTemplateDir() {
         'src/shell/export-html'
     ]);
 }
-/** Get path to package.json */
-/** Get path to the package.json shipped with the runtime. */
-function getPackageJsonPath() {
-    return join(getPackageDir(), 'package.json');
-}
 /** Get path to agent-docs/docs directory (used for system prompt context) */
 export function getDocsPath() {
     return resolve(join(getPackageDir(), 'agent-docs', 'docs'));
@@ -182,7 +196,7 @@ export function getChangelogPath() {
 // =============================================================================
 // App Config (from package.json shortcutConfig)
 // =============================================================================
-const pkg = JSON.parse(readFileSync(getPackageJsonPath(), 'utf-8'));
+const pkg = JSON.parse(readFileSync(join(getRuntimePackageDir(), 'package.json'), 'utf-8'));
 export const APP_NAME = pkg.shortcutConfig?.name || 'shortcut';
 export const CONFIG_DIR_NAME = pkg.shortcutConfig?.configDir || '.shortcut';
 export const VERSION = pkg.version;
@@ -235,7 +249,7 @@ export const NPM_REGISTRY_URL = process.env.SHORTCUT_NPM_REGISTRY_URL?.trim() ||
  * 3. Global install fallback (bin in PATH) → ['shortcut']
  */
 export function resolveOwnBinary() {
-    const packageDir = getPackageDir();
+    const packageDir = getRuntimePackageDir();
     const currentScript = process.argv[1] ? resolve(process.argv[1]) : '';
     const preferSource = currentScript.endsWith('.ts');
     const candidates = preferSource

package/dist/contracts/model-stream.d.ts

@@ -273,6 +273,11 @@ export interface ShortcutXLModelStreamTool {
     readonly name: string;
     readonly parameters: Record<string, unknown>;
 }
+/** Telemetry-only execution provenance; never a billing or provider identifier. */
+export interface ShortcutXLModelRequestCorrelation {
+    readonly runtimeRunId?: string;
+    readonly originUserMessageId?: string;
+}
 export interface ShortcutXLModelStreamRequest {
     readonly agentMode?: string;
     readonly effortLevel?: ShortcutXLModelStreamEffortLevel;

package/dist/contracts/wire.d.ts

@@ -6,7 +6,7 @@ import type { Api, Context, Model, SimpleStreamOptions } from '../ai/types.js';
 import { type AgentCommand, type AgentEvent } from './agent-api.js';
 import { type HostToolRequest, type HostToolResult, type ToolRegistry } from './host-tool-api.js';
 import type { ShortcutXLUsageLogRequestType } from './model-call.js';
-import { type ShortcutXLLlmOperation, type ShortcutXLModelStreamEvent } from './model-stream.js';
+import { type ShortcutXLLlmOperation, type ShortcutXLModelRequestCorrelation, type ShortcutXLModelStreamEvent } from './model-stream.js';
 export declare const WorkerMessageKind: {
     readonly HostToolRequest: "hostToolRequest";
     readonly HostToolResult: "hostToolResult";
@@ -51,6 +51,7 @@ export interface HostToolResultMessage {
 }
 export type ShortcutXLAiStreamOptions = Pick<SimpleStreamOptions, 'cacheRetention' | 'headers' | 'maxRetryDelayMs' | 'maxTokens' | 'metadata' | 'reasoning' | 'temperature' | 'toolChoice' | 'transport'> & {
     readonly agentMode?: string;
+    readonly requestCorrelation?: ShortcutXLModelRequestCorrelation;
     readonly continuationRunId?: string;
     readonly fileAttachmentIds?: readonly string[];
     readonly fastModeModelIds?: readonly string[];
@@ -61,6 +62,7 @@ export type ShortcutXLAiStreamOptions = Pick<SimpleStreamOptions, 'cacheRetentio
     readonly userMessageId?: string;
 };
 export type ShortcutXLAiInvokeOptions = Pick<SimpleStreamOptions, 'cacheRetention' | 'headers' | 'maxRetryDelayMs' | 'maxTokens' | 'metadata' | 'reasoning' | 'temperature' | 'toolChoice' | 'transport'> & {
+    readonly requestCorrelation?: ShortcutXLModelRequestCorrelation;
     readonly continuationRunId?: string;
     readonly requestType?: ShortcutXLUsageLogRequestType;
     readonly fastModeModelIds?: readonly string[];

package/dist/core/agent-engine.d.ts

@@ -1,7 +1,7 @@
 /** Turn driver: wraps `agentLoop` with per-session config and reduces stream events into AgentState. */
 import type { EventStream } from '../ai/event-stream.js';
 import { type AssistantMessage, type Message, type ToolCall, type Transport } from '../ai/types.js';
-import type { ShortcutXLLlmOperation } from '../contracts/model-stream.js';
+import type { ShortcutXLLlmOperation, ShortcutXLModelRequestCorrelation } from '../contracts/model-stream.js';
 import type { AgentMessageQueue } from './agent-message-queue.js';
 import { type AgentContext, type AgentLoopConfig, type AgentLoopEvent, type AgentMessage, type AgentState, type AgentUserMessageExecutionStart, type InFlightMeta, type InFlightOpKind, type StreamFn, type ToolExecutionContext } from './core-types.js';
 import { type HeartbeatClock } from './heartbeat.js';
@@ -31,6 +31,7 @@ export interface AgentEngineRunOptions {
     onEvent: (event: AgentLoopEvent) => void;
 }
 export interface AgentEngineStreamObservabilityContext {
+    requestCorrelation?: ShortcutXLModelRequestCorrelation;
     agentMode?: string;
     continuationRunId?: string;
     initialFileId?: string;

package/dist/core/agent-engine.js

@@ -186,6 +186,9 @@ export class AgentEngine {
         };
         const config = {
             model,
+            requestCorrelation: this._streamObservabilityContext?.requestCorrelation
+                ? { ...this._streamObservabilityContext.requestCorrelation }
+                : undefined,
             maxTokens: model.maxTokens,
             reasoning,
             sessionId: this._sessionId,

package/dist/core/agent-loop.js

@@ -555,6 +555,10 @@ function emitToolResultMessage(stream, result) {
  * the full response is available.
  */
 export async function streamAssistantResponse(context, config, signal, stream, streamFn, onToolCallReady) {
+    // Capture telemetry provenance before asynchronous transforms; never consult a later run.
+    const requestCorrelation = config.requestCorrelation
+        ? { ...config.requestCorrelation }
+        : undefined;
     // Apply context transform if configured (AgentMessage[] → AgentMessage[])
     let messages = context.messages;
     if (config.transformContext) {
@@ -571,11 +575,13 @@ export async function streamAssistantResponse(context, config, signal, stream, s
         throw new Error('AgentController runtime requires an explicit stream function.');
     }
     const resolvedApiKey = (config.getApiKey ? await config.getApiKey(config.model.provider) : undefined) || config.apiKey;
-    const response = await streamFn(config.model, llmContext, {
+    const requestOptions = {
         ...config,
+        requestCorrelation,
         apiKey: resolvedApiKey,
         signal
-    });
+    };
+    const response = await streamFn(config.model, llmContext, requestOptions);
     let partialMessage = null;
     let addedPartial = false;
     // microtask starvation that blocks TUI rendering on slower machines.

package/dist/core/core-types.d.ts

@@ -6,7 +6,7 @@ import type { EventStream } from '../ai/event-stream.js';
 import type { streamSimple } from '../ai/stream.js';
 import type { AssistantMessage, AssistantMessageEvent, ImageContent, Message, Model, SimpleStreamOptions, TextContent, Tool, ToolCall, ToolResultMessage, UserMessage } from '../ai/types.js';
 import type { RunFailureCause } from '../contracts/agent-failure.js';
-import type { ShortcutXLLlmOperation } from '../contracts/model-stream.js';
+import type { ShortcutXLLlmOperation, ShortcutXLModelRequestCorrelation } from '../contracts/model-stream.js';
 import type { UserMessageUiMetadata } from '../contracts/user-message-ui-metadata.js';
 import type { RuntimeFilesystemApprovalGrant, RuntimePermissionPolicy } from './permission-policy.js';
 import type { SessionState } from './session-state.js';
@@ -100,6 +100,8 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      * Set from `AgentSubmitOptions.speed`.
      */
     speed?: 'fast' | 'standard' | 'ultrafast' | 'flex';
+    /** Immutable main execution provenance for content-free request correlation. */
+    requestCorrelation?: ShortcutXLModelRequestCorrelation;
     /** Host-generated user message identifier forwarded to ShortcutXL's LLM proxy. */
     userMessageId?: string;
     /** Stable billing-continuation scope shared by every model call in the active run. */

package/dist/core/session/compaction/compaction.d.ts

@@ -5,6 +5,7 @@
  * and after compaction the session is reloaded.
  */
 import type { AssistantMessage, Context, Model, SimpleStreamOptions, Usage } from '../../../ai/types.js';
+import type { ShortcutXLModelRequestCorrelation } from '../../../contracts/model-stream.js';
 import type { AgentMessage, StreamFn } from '../../core-types.js';
 import type { SessionEntry } from '../../session-schema.js';
 import { type FileOperations } from './utils.js';
@@ -17,6 +18,7 @@ export type CompactionCompleteFn = (model: Model<any>, context: Context, options
 /** Run compaction summaries through a host's stream function, so they share its transport. */
 export declare function createStreamBackedCompactionComplete(streamFn: StreamFn): CompactionCompleteFn;
 export interface CompactionAttribution {
+    requestCorrelation?: ShortcutXLModelRequestCorrelation;
     agentMode?: string;
     continuationRunId?: string;
     userMessageId?: string;

package/dist/core/session/compaction/compaction.js

@@ -48,6 +48,9 @@ async function completeCompactionSummary(model, promptText, apiKey, errorPrefix,
         apiKey,
         reasoning: 'low',
         llmOperation: 'compaction',
+        ...(attribution?.requestCorrelation
+            ? { requestCorrelation: { ...attribution.requestCorrelation } }
+            : {}),
         ...(attribution?.agentMode ? { agentMode: attribution.agentMode } : {}),
         ...(attribution?.continuationRunId
             ? { continuationRunId: attribution.continuationRunId }

package/dist/core/session/compaction-bridge.d.ts

@@ -4,9 +4,10 @@ import type { AgentModelRegistry } from '../../contracts/agent-model.js';
 import type { AgentSessionContext, AgentSessionEntry } from '../../contracts/agent-session-store.js';
 import type { HeartbeatWrapFn } from '../agent-engine.js';
 import type { AgentController, AgentMessage } from '../index.js';
-import type { CompactionResult } from './compaction/index.js';
+import type { CompactionAttribution, CompactionResult } from './compaction/index.js';
 import { SessionCompaction, type CompactionActions } from './session-compaction.js';
 export interface TriggerCompactionOptions {
+    requestCorrelation?: CompactionAttribution['requestCorrelation'];
     /** Per-turn heartbeat wrap. Captured synchronously by the caller while the
      *  agent loop is still active; outlives the loop's _activeWrap clear. */
     heartbeatWrap?: HeartbeatWrapFn;

package/dist/core/session/compaction-bridge.js

@@ -115,8 +115,11 @@ export async function triggerCompactionIfNeeded(deps, msg, skipAbortedCheck, opt
     }, skipAbortedCheck);
     if (opts?.onlyAction !== undefined && decision.action !== opts.onlyAction)
         return;
-    const attribution = opts?.agentMode || opts?.continuationRunId || opts?.userMessageId
+    const attribution = opts?.requestCorrelation || opts?.agentMode || opts?.continuationRunId || opts?.userMessageId
         ? {
+            ...(opts.requestCorrelation
+                ? { requestCorrelation: { ...opts.requestCorrelation } }
+                : {}),
             ...(opts.agentMode ? { agentMode: opts.agentMode } : {}),
             ...(opts.continuationRunId ? { continuationRunId: opts.continuationRunId } : {}),
             ...(opts.userMessageId ? { userMessageId: opts.userMessageId } : {})

package/dist/embedded-agent/compaction-wiring.js

@@ -54,8 +54,11 @@ export function createEmbeddedCompactionWiring(options) {
         const perTurnUserMessageId = options.getPerTurnOptions().userMessageId;
         const activeUserMessageId = getActiveUserMessageId(options.agent.state.messages);
         const userMessageId = perTurnUserMessageId ?? activeUserMessageId;
-        const attribution = continuationRunId || userMessageId
+        const correlation = options.agent.streamObservabilityContext?.requestCorrelation;
+        const requestCorrelation = correlation ? { ...correlation } : undefined;
+        const attribution = requestCorrelation || continuationRunId || userMessageId
             ? {
+                ...(requestCorrelation ? { requestCorrelation } : {}),
                 ...(continuationRunId ? { continuationRunId } : {}),
                 ...(userMessageId ? { userMessageId } : {})
             }

package/dist/embedded-agent/compose.js

@@ -324,13 +324,14 @@ function appendCancellationBoundaryIfNeeded(agent, funnel) {
     funnel.assertAlignedWith(agent.state.messages.length);
 }
 /** Assemble the per-turn stream-observability context (mode, file ids, interaction mode) for tracing. */
-function buildStreamObservabilityContext(submitOptions, agentMode) {
+function buildStreamObservabilityContext(submitOptions, agentMode, originUserMessageId) {
     const fileAttachmentIds = submitOptions?.fileUploads
         ?.map((file) => file.fileId)
         .filter((fileId) => typeof fileId === 'string' && fileId.length > 0) ?? [];
     const interactionMode = submitOptions?.interactionMode;
     return {
         agentMode,
+        ...(originUserMessageId ? { requestCorrelation: { originUserMessageId } } : {}),
         ...(submitOptions?.continuationRunId
             ? { continuationRunId: submitOptions.continuationRunId }
             : {}),
@@ -1016,6 +1017,13 @@ export async function composeEmbeddedAgentRuntimeInternal(options) {
     });
     const beginGoalAwareRun = () => {
         const runId = runStatsAccumulator.beginRun();
+        agentRuntime.streamObservabilityContext = {
+            ...agentRuntime.streamObservabilityContext,
+            requestCorrelation: {
+                ...agentRuntime.streamObservabilityContext?.requestCorrelation,
+                runtimeRunId: runId
+            }
+        };
         goalRuntime.beginRun({
             executable: isExecutableGoalMode(runtimeAgentMode),
             runId
@@ -1361,7 +1369,7 @@ export async function composeEmbeddedAgentRuntimeInternal(options) {
         const refreshContinuationContext = copyContinuationContext(refreshSubmitOptions, continuationContext.latestUserTaskForRefresh);
         activePerTurnOptions = refreshSubmitOptions;
         activeContinuationContext = refreshContinuationContext;
-        agentRuntime.streamObservabilityContext = buildStreamObservabilityContext(activePerTurnOptions, runtimeAgentMode);
+        agentRuntime.streamObservabilityContext = buildStreamObservabilityContext(activePerTurnOptions, runtimeAgentMode, agentRuntime.streamObservabilityContext?.requestCorrelation?.originUserMessageId);
         agent.speed = selectedSpeed;
         beginGoalAwareRun();
         runStatsAccumulator.refreshRunConfig();
@@ -1411,7 +1419,7 @@ export async function composeEmbeddedAgentRuntimeInternal(options) {
             rangeRestrictions: submitOptions?.rangeRestrictions
         };
         activeContinuationContext = submitOptions ?? latestSubmitContinuationContext;
-        agentRuntime.streamObservabilityContext = buildStreamObservabilityContext(activePerTurnOptions, runtimeAgentMode);
+        agentRuntime.streamObservabilityContext = buildStreamObservabilityContext(activePerTurnOptions, runtimeAgentMode, agentRuntime.streamObservabilityContext?.requestCorrelation?.originUserMessageId);
         agent.speed = selectedSpeed;
         beginGoalAwareRun();
         await compactionWiring.triggerIfNeeded();
@@ -2317,7 +2325,7 @@ export async function composeEmbeddedAgentRuntimeInternal(options) {
             const turnCleanup = registerTurnCleanup(agent, {}, baselineStreamObservabilityContext);
             let runStarted = false;
             try {
-                agentRuntime.streamObservabilityContext = buildStreamObservabilityContext(resolvedSubmitOptions, runtimeAgentMode);
+                agentRuntime.streamObservabilityContext = buildStreamObservabilityContext(resolvedSubmitOptions, runtimeAgentMode, resolvedSubmitOptions.userMessageId);
                 // Mint runId before compaction so the summarizer's usage rolls into
                 // this run AND beats the heartbeat-emit-before-agent_start race.
                 beginGoalAwareRun();

package/dist/main.d.ts

@@ -10,6 +10,7 @@ import { SettingsManager } from './app/settings-manager.js';
 import { type StartupInfoEntry } from './app/startup-info.js';
 import { type Args } from './cli/args.js';
 import { type CreateLocalAgentSessionOptions } from './local/index.js';
+import { type ShortcutDefaultModelPlan } from './shortcut-default-model.js';
 import { StartupProgress } from './startup/startup-progress.js';
 /** Resolve the per-run durable-memory policy without changing the persisted user setting. */
 export declare function shouldEnableDurableMemory(settingsEnabled: boolean, disableMemory: boolean | undefined): boolean;
@@ -30,6 +31,12 @@ export declare function isShortcutModelAllowedForUser(model: {
     readonly id?: string;
 } | undefined, userInfo: UserInfo | null): boolean;
 export declare function applyShortcutModelPolicyForUser(modelRegistry: ModelRegistry, userInfo: UserInfo | null): void;
+/**
+ * The users/me facts that pick the plan default model (signed out: product default). A local
+ * gateway serves the full catalog whatever the plan, as the policy above allows, so its plan
+ * does not make the account Free.
+ */
+export declare function shortcutDefaultModelPlanForUser(userInfo: UserInfo | null, viaGateway?: boolean): ShortcutDefaultModelPlan;
 /** Composition root: dispatch CLI args to print, RPC, or interactive entry points. */
 export declare function main(args: string[]): Promise<void>;
 //# sourceMappingURL=main.d.ts.map

package/dist/main.js

@@ -32,6 +32,7 @@ import { resolveCliModel } from './app/providers/model-resolver.js';
 import { registerShortcutProvider } from './app/providers/register-shortcut-provider.js';
 import { DefaultResourceLoader } from './app/resources/resource-loader.js';
 import { syncInstalledShortcutXLPlugins } from './app/resources/shortcutxl-plugin-sync.js';
+import { alignSessionModelWithAccount } from './app/session/account-default-model.js';
 import { listAllSessions, listSessions } from './app/session/session-catalog.js';
 import { openSessionManager } from './app/session/session-factory.js';
 import { SettingsManager } from './app/settings-manager.js';
@@ -76,9 +77,10 @@ import { SHORTCUT_API_HEADERS } from './endpoints.js';
 import { createLocalAgentSession } from './local/index.js';
 import { appendCliExecutionContract, handleConfigCommand, handleShortcutAuthCommand, handleXllStartupStatus, isTruthyEnvFlag, prepareInitialMessage, readPipedStdin, resolveApiKeyArgument, runInteractiveShell, validateAgentMode } from './main-helpers.js';
 import { getCurrentMode, MODE, setCurrentMode } from './mode-names.js';
-import { isShortcutFableModelId, isShortcutPaidPlanModel, isShortcutPickerGatedModel, setShortcutPaidPlanModelsAllowed, SHORTCUT_FREE_MODEL_ID, SHORTCUT_OPENAI_MODEL_ID, SHORTCUT_PROVIDER_ID } from './model-ids.js';
+import { isShortcutFableModelId, isShortcutPaidPlanModel, isShortcutPickerGatedModel, setShortcutPaidPlanModelsAllowed, SHORTCUT_PROVIDER_ID } from './model-ids.js';
 import { parseShortcutRuntimeModelOverlay } from './runtime-model-overlay.js';
 import { attachSessionUpload, createInteractiveSessionClient, createNetworkPrompt, createPrintModeSessionClient, createSandboxBashTool, createShortySlashCommand, ensureWslSandbox, exportFromFile, getTraceHooks, hasCustomExtensionUI, initTheme, InteractiveMode, isDistroInstalled, isWsl2Available, KeybindingsManager, runPrintMode, SANDBOX_DISTRO, startDurableMemoryStatusUpdater, startLoopStatusPolling, stopThemeWatcher } from './shell/index.js';
+import { setShortcutDefaultModelPlan } from './shortcut-default-model.js';
 import { closeMogCliSessions, initializeMogCli } from './startup/mog-cli.js';
 import { finalizeOutputWorkbook, OUTPUT_WORKBOOK_NOT_CREATED } from './startup/output-workbook.js';
 import { STARTUP_PHASE, StartupProgress } from './startup/startup-progress.js';
@@ -104,6 +106,7 @@ import { createSessionManager } from './startup/session-selection.js';
 import { applyRuntimeApiKeyAndRefreshShortcutLoggerContext, applyShortcutUserInfoToLogger, refreshShortcutUserInfoLoggerContext } from './startup/shortcut-user-logger-context.js';
 import { createSkillSyncRunner } from './startup/skill-sync-commands.js';
 import { runTerminalUpdateFlow } from './startup/terminal-update-flow.js';
+import { reportPendingUpdateAttempts } from './startup/update-diagnostics.js';
 import { refreshUpdateStatus } from './startup/update-manager.js';
 import { runWindowsExcelRuntimeUpgradeIfNeeded } from './startup/windows-excel-runtime-upgrade.js';
 import { createWorkbookPrePromptContext } from './startup/workbook-pre-prompt.js';
@@ -189,6 +192,7 @@ export async function buildSessionOptions(parsed, sessionManager, modelRegistry,
         settingsManager: _settingsManager
     });
     options.model = initialModel.model;
+    options.modelExplicit = initialModel.modelExplicit;
     // API key from CLI - set in authStorage
     // (handled by caller before createLocalAgentSession)
     const buildRuntimeTools = async (warnings, trigger) => {
@@ -459,21 +463,19 @@ export function applyShortcutModelPolicyForUser(modelRegistry, userInfo) {
         (getLocalShortcutRouting()?.state.kind === 'gateway' ||
             isShortcutModelAllowedForUser(model, userInfo)));
     setShortcutPaidPlanModelsAllowed(() => getLocalShortcutRouting()?.state.kind === 'gateway' || userInfo?.plan !== null);
+    setShortcutDefaultModelPlan(() => shortcutDefaultModelPlanForUser(userInfo, getLocalShortcutRouting()?.state.kind === 'gateway'));
 }
-async function moveSessionOffPolicyDeniedModel(session, modelRegistry) {
-    const currentModel = session?.model;
-    if (!session || !currentModel)
-        return;
-    if (modelRegistry.find(currentModel.provider, currentModel.id))
-        return;
-    const availableModels = await modelRegistry.getAvailable();
-    const fallback = availableModels.find((model) => model.provider === SHORTCUT_PROVIDER_ID && model.id === SHORTCUT_OPENAI_MODEL_ID) ??
-        availableModels.find((model) => model.provider === SHORTCUT_PROVIDER_ID && model.id === SHORTCUT_FREE_MODEL_ID) ??
-        availableModels.find((model) => model.provider === SHORTCUT_PROVIDER_ID) ??
-        availableModels[0];
-    if (fallback) {
-        await session.setModel(fallback);
-    }
+/**
+ * The users/me facts that pick the plan default model (signed out: product default). A local
+ * gateway serves the full catalog whatever the plan, as the policy above allows, so its plan
+ * does not make the account Free.
+ */
+export function shortcutDefaultModelPlanForUser(userInfo, viaGateway = false) {
+    return {
+        plan: viaGateway ? undefined : userInfo?.plan,
+        teamId: userInfo?.teamId,
+        defaultModelPickerEntryKey: userInfo?.defaultModelPickerEntryKey
+    };
 }
 async function refreshSessionForMogPolicyChange(session) {
     if (!session)
@@ -997,6 +999,8 @@ export async function main(args) {
             cli_mode: cliMode
         }
     });
+    // Update attempts run before this logger exists; report their receipts on the next start.
+    void reportPendingUpdateAttempts(clientLogger);
     clientLogger.info({
         module: 'session',
         event: 'session_started',
@@ -1157,7 +1161,7 @@ export async function main(args) {
                     return;
                 shortcutUserInfo = await refreshAccount();
                 applyShortcutModelPolicyForUser(modelRegistry, shortcutUserInfo);
-                await moveSessionOffPolicyDeniedModel(session, modelRegistry);
+                await alignSessionModelWithAccount(session, modelRegistry);
             },
             fetchSessionCreditUsageStatus: async () => {
                 const credential = authStorage.get(SHORTCUT_PROVIDER_ID);
@@ -1346,7 +1350,7 @@ export async function main(args) {
                     }
                 });
                 sessionRef?.setFastModeAllowed(isFastModeAllowedForUser(userInfo), getFastModeDisabledReasonForUser(userInfo) ?? 'team');
-                await moveSessionOffPolicyDeniedModel(sessionRef, modelRegistry);
+                await alignSessionModelWithAccount(sessionRef, modelRegistry);
                 setRemoteControlTeamAccount(Boolean(userInfo?.teamId));
                 if (isMogRuntimeEnabledForUser(shortcutUserInfo) !== previousMogRuntimeEnabled) {
                     await refreshSessionForMogPolicyChange(sessionRef);

package/dist/rpc/rpc-host.js

@@ -20,6 +20,7 @@ import { getCurrentMode, isAgentMode, isSelectableAgentMode, onModeChange, SELEC
 import { exportSessionToHtml } from '../shell/export-html/index.js';
 import { openLocalFileLink } from '../shell/links/local-file-opener.js';
 import { readLocalFilePreview } from '../shell/links/local-file-preview.js';
+import { resolveShortcutDefaultModel } from '../shortcut-default-model.js';
 import { RPC_PROTOCOL_VERSION } from './rpc-types.js';
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
@@ -374,7 +375,12 @@ export class RpcSessionHost {
                 .getAvailable()
                 .filter((model) => model.provider === providerId);
             if ((!this.session.model || this.session.model.provider !== providerId) && models[0]) {
-                await this.session.setModel(models[0]);
+                // The runtime picks this model, not the user: the plan default (never catalog
+                // order, which put Claude Opus 5.5 first), and login may re-resolve it later.
+                const loginDefault = resolveShortcutDefaultModel(models) ??
+                    filterInteractiveSelectableModels(models)[0] ??
+                    models[0];
+                await this.session.setModel(loginDefault, { explicit: false });
             }
             this.publish({
                 type: 'notification',

package/dist/shell/interactive/auth-workflow.js

@@ -1,7 +1,9 @@
 /** Interactive-shell auth workflow for login, token storage, and session-bound auth checks. */
 import { getOAuthProviders } from '../../ai/utils/oauth/index.js';
 import { LoginRequiredError } from '../../app/agent-session.js';
+import { filterInteractiveSelectableModels } from '../../app/session/session-models.js';
 import { getAuthPath } from '../../config.js';
+import { resolveShortcutDefaultModel } from '../../shortcut-default-model.js';
 import { LoginDialogComponent } from '../components/selectors/login-dialog.js';
 import { OAuthSelectorComponent } from '../components/selectors/oauth-selector.js';
 export class AuthWorkflow {
@@ -168,7 +170,11 @@ export class AuthWorkflow {
         const currentModel = this.deps.session.model;
         if (!currentModel || currentModel.provider !== providerId) {
             try {
-                await this.deps.session.setModel(providerModels[0]);
+                // The runtime picks this model, not the user, so login can re-resolve it.
+                const loginDefault = resolveShortcutDefaultModel(providerModels) ??
+                    filterInteractiveSelectableModels(providerModels)[0] ??
+                    providerModels[0];
+                await this.deps.session.setModel(loginDefault, { explicit: false });
                 this.deps.onModelChanged();
             }
             catch {

package/dist/shortcut-default-model.d.ts

@@ -0,0 +1,30 @@
+/** The account facts users/me reports that decide the default model. */
+export interface ShortcutDefaultModelPlan {
+    /** users/me `plan`: null means no paid plan (Free); undefined means unknown or signed out. */
+    readonly plan?: string | null;
+    readonly teamId?: string;
+    /** Org-admin-saved picker key from users/me (Team accounts only). */
+    readonly defaultModelPickerEntryKey?: string | null;
+}
+/** Model id behind a picker key, following a retired key to its successor; picker-listed only. */
+export declare function shortcutPickerKeyModelId(key: string | null | undefined): string | undefined;
+/**
+ * The product default picker entry's model (GPT-6 Astra today). If a catalog edit ever makes
+ * `defaults.pickerKey` a model the CLI picker does not list, fall back to the first listed
+ * picker entry rather than failing at import; a unit test pins the catalog value.
+ */
+export declare const SHORTCUT_PRODUCT_DEFAULT_MODEL_ID: string;
+/**
+ * Ordered default candidates for an account. The first one the account can run wins;
+ * every candidate is a picker-listed model.
+ */
+export declare function getShortcutDefaultModelCandidates(plan?: ShortcutDefaultModelPlan): readonly string[];
+/** Pick the plan default from the models the account can run now (Shortcut provider only). */
+export declare function resolveShortcutDefaultModel<M extends {
+    provider: string;
+    id: string;
+}>(availableModels: readonly M[], plan?: ShortcutDefaultModelPlan): M | undefined;
+/** Hosts set this from users/me so startup and login defaults follow the account's plan. */
+export declare function setShortcutDefaultModelPlan(plan: () => ShortcutDefaultModelPlan): void;
+export declare function getShortcutDefaultModelPlan(): ShortcutDefaultModelPlan;
+//# sourceMappingURL=shortcut-default-model.d.ts.map