shortcutxl 0.4.0 → 0.4.2

package/dist/shortcut-default-model.js

@@ -0,0 +1,86 @@
+/**
+ * Plan-aware default model for the Shortcut provider.
+ *
+ * Mirrors the web app's `getPlanDefaultPickerEntry` (client/shared context-size.ts):
+ * Team accounts use the org-admin-saved picker key (retired keys follow their
+ * successor) and fall back to the product default picker entry; unpaid personal
+ * accounts use the Free model; everyone else, including a signed-out runtime,
+ * uses the product default picker entry (`defaults.pickerKey`).
+ *
+ * Candidates are only models the CLI/desktop picker can list (`product.cli`), so
+ * a default can never land on a model the user cannot see or pick again.
+ * `defaults.runtime` / `SHORTCUT_OPENAI_MODEL_ID` are deliberately not used here:
+ * they identify the OpenAI reasoning model for fast mode and BYOK providers.
+ */
+import { CATALOG_FREE_MODEL_ID, MODEL_CATALOG } from './supported-models.generated.js';
+import { getSupportedModel, getSupportedModelByPickerKey, SUPPORTED_MODELS } from './supported-models.js';
+const SHORTCUT_PROVIDER = 'shortcut';
+function isPickerListedModelId(modelId) {
+    return getSupportedModel(modelId)?.product.cli === true;
+}
+/** Model id behind a picker key, following a retired key to its successor; picker-listed only. */
+export function shortcutPickerKeyModelId(key) {
+    if (!key)
+        return undefined;
+    const direct = getSupportedModelByPickerKey(key);
+    if (direct && isPickerListedModelId(direct.id))
+        return direct.id;
+    const successor = MODEL_CATALOG.retiredPickerKeys[key];
+    const replacement = successor ? getSupportedModelByPickerKey(successor) : undefined;
+    return replacement && isPickerListedModelId(replacement.id) ? replacement.id : undefined;
+}
+/** Picker-listed models in product picker order, used after the plan default. */
+const PICKER_ORDER_MODEL_IDS = SUPPORTED_MODELS.flatMap((model) => model.product.pickerOrder !== undefined && model.product.cli
+    ? [{ id: model.id, order: model.product.pickerOrder }]
+    : [])
+    .sort((a, b) => a.order - b.order)
+    .map((model) => model.id);
+/**
+ * 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 const SHORTCUT_PRODUCT_DEFAULT_MODEL_ID = shortcutPickerKeyModelId(MODEL_CATALOG.defaults.pickerKey) ??
+    PICKER_ORDER_MODEL_IDS[0] ??
+    CATALOG_FREE_MODEL_ID;
+/** True when the account is Free: users/me reported no paid plan and no team. */
+function isFreePlan(plan) {
+    return !plan.teamId && plan.plan === null;
+}
+/**
+ * Ordered default candidates for an account. The first one the account can run wins;
+ * every candidate is a picker-listed model.
+ */
+export function getShortcutDefaultModelCandidates(plan = {}) {
+    const preferred = [];
+    if (plan.teamId) {
+        preferred.push(shortcutPickerKeyModelId(plan.defaultModelPickerEntryKey));
+        preferred.push(SHORTCUT_PRODUCT_DEFAULT_MODEL_ID);
+    }
+    else if (isFreePlan(plan)) {
+        preferred.push(CATALOG_FREE_MODEL_ID);
+    }
+    else {
+        preferred.push(SHORTCUT_PRODUCT_DEFAULT_MODEL_ID);
+    }
+    const ordered = [...preferred, ...PICKER_ORDER_MODEL_IDS, CATALOG_FREE_MODEL_ID];
+    return [...new Set(ordered.filter(isPickerListedModelId))];
+}
+/** Pick the plan default from the models the account can run now (Shortcut provider only). */
+export function resolveShortcutDefaultModel(availableModels, plan = getShortcutDefaultModelPlan()) {
+    for (const id of getShortcutDefaultModelCandidates(plan)) {
+        const match = availableModels.find((model) => model.provider === SHORTCUT_PROVIDER && model.id === id);
+        if (match)
+            return match;
+    }
+    return undefined;
+}
+let currentPlan = () => ({});
+/** Hosts set this from users/me so startup and login defaults follow the account's plan. */
+export function setShortcutDefaultModelPlan(plan) {
+    currentPlan = plan;
+}
+export function getShortcutDefaultModelPlan() {
+    return currentPlan();
+}
+//# sourceMappingURL=shortcut-default-model.js.map

package/dist/startup/terminal-update-flow.js

@@ -8,6 +8,9 @@ export async function runTerminalUpdateFlow(options, deps = {}) {
     const result = await (deps.executeUpdate ?? executeStartupUpdate)(outcome.update);
     if (result.kind === 'success')
         return { kind: 'updated' };
-    return { kind: 'update-failed', exitCode: result.exitCode ?? 1 };
+    // An unverified update exited 0 but did not take effect; it must not exit 0 or launch.
+    if (result.kind === 'unverified')
+        return { kind: 'update-failed', exitCode: 1 };
+    return { kind: 'update-failed', exitCode: result.exitCode || 1 };
 }
 //# sourceMappingURL=terminal-update-flow.js.map

package/dist/startup/update-action.d.ts

@@ -7,14 +7,23 @@
  * streamed directly into the user's terminal.
  */
 import { spawn } from 'child_process';
+import { type UpdateFailureDiagnostics } from './update-diagnostics.js';
 export interface UpdateLaunchRequest {
     command: string;
     cwd?: string;
+    /** Resolve npm's original global config before rebinding its install prefix. */
+    preserveNpmConfig?: boolean;
+    /** Joins the debug-log section to the attempt's receipt. */
+    attemptId?: string;
 }
-export interface ForegroundUpdateResult {
-    kind: 'success' | 'failed';
+export interface ForegroundUpdateResult extends UpdateFailureDiagnostics {
+    /** `unverified`: the installer exited 0 but the next `shortcut` would not run the target. */
+    kind: 'success' | 'failed' | 'unverified';
     exitCode: number | null;
     signal: NodeJS.Signals | null;
+    /** Sanitized installer stdout/stderr, kept on success too so warnings are not lost. */
+    output?: string;
+    outputTruncated?: boolean;
     message?: string;
     logPath?: string;
 }
@@ -26,7 +35,13 @@ interface UpdateActionDeps {
     };
     resolveEnv?: () => NodeJS.ProcessEnv;
     resolveLogPath?: () => string;
+    readNpmGlobalConfig?: typeof readNpmGlobalConfig;
 }
 export declare function runForegroundUpdate(request: UpdateLaunchRequest, deps?: UpdateActionDeps): Promise<ForegroundUpdateResult>;
+/** Read only the path, never registry credentials or the contents of an npmrc. */
+declare function readNpmGlobalConfig(shell: {
+    shell: string;
+    args: string[];
+}, env: NodeJS.ProcessEnv, cwd: string): Promise<string>;
 export {};
 //# sourceMappingURL=update-action.d.ts.map

package/dist/startup/update-action.js

@@ -6,11 +6,12 @@
  * half-deleted, so stdout/stderr are captured and summarized instead of being
  * streamed directly into the user's terminal.
  */
-import { spawn } from 'child_process';
-import { appendFileSync, mkdirSync } from 'fs';
-import { dirname } from 'path';
+import { execFile, spawn } from 'child_process';
+import { isAbsolute } from 'path';
+import { promisify } from 'util';
 import { getShellConfig, getShellEnv } from '../app/tools/bash-runtime.js';
 import { getDebugLogPath } from '../config.js';
+import { appendUpdateLog, sanitizeInstallerOutput } from './update-diagnostics.js';
 const MAX_CAPTURED_OUTPUT_BYTES = 1024 * 1024;
 export async function runForegroundUpdate(request, deps = {}) {
     const resolveShell = deps.resolveShell ?? getShellConfig;
@@ -18,13 +19,57 @@ export async function runForegroundUpdate(request, deps = {}) {
     const spawnProcess = deps.spawnProcess ?? spawn;
     const resolveLogPath = deps.resolveLogPath ?? getDebugLogPath;
     const shellConfig = resolveShell();
+    const cwd = request.cwd ?? process.cwd();
+    const env = { ...resolveEnv() };
+    if (request.preserveNpmConfig) {
+        let invalidPath = false;
+        try {
+            // Query with the same shell/environment as the installer, before --prefix changes
+            // npm's default globalconfig. --global excludes a project .npmrc just as install -g does.
+            const globalConfig = await (deps.readNpmGlobalConfig ?? readNpmGlobalConfig)(shellConfig, env, cwd);
+            if (!isAbsolute(globalConfig) || /[\r\n\0]/.test(globalConfig)) {
+                invalidPath = true;
+                throw new Error('Invalid npm global configuration path');
+            }
+            // Windows environment names are case-insensitive. Do not leave competing spellings.
+            for (const key of Object.keys(env)) {
+                if (key.toLowerCase() === 'npm_config_globalconfig')
+                    delete env[key];
+            }
+            env.npm_config_globalconfig = globalConfig;
+        }
+        catch (cause) {
+            const diagnostics = {
+                failure_stage: 'npm_config',
+                ...classifyConfigProbeFailure(cause, invalidPath)
+            };
+            const logPath = appendUpdateLog({
+                title: 'ShortcutXL update configuration failure',
+                fields: {
+                    attemptId: request.attemptId,
+                    command: request.command,
+                    failure: 'npm-globalconfig-probe-failed',
+                    ...diagnostics
+                }
+            }, 'The original npm global configuration could not be resolved. No installer was started.', resolveLogPath);
+            return {
+                kind: 'failed',
+                ...diagnostics,
+                logPath,
+                exitCode: null,
+                signal: null,
+                message: 'ShortcutXL could not read your npm global configuration, so no update was attempted. ' +
+                    'Run `npm config get globalconfig --global` in this terminal, resolve any npm configuration error, and retry.'
+            };
+        }
+    }
     return await new Promise((resolve, reject) => {
         const output = [];
         let outputBytes = 0;
         let outputTruncated = false;
         const child = spawnProcess(shellConfig.shell, [...shellConfig.args, request.command], {
-            cwd: request.cwd ?? process.cwd(),
-            env: resolveEnv(),
+            cwd,
+            env,
             stdio: ['ignore', 'pipe', 'pipe']
         });
         const capture = (chunk) => {
@@ -42,70 +87,99 @@ export async function runForegroundUpdate(request, deps = {}) {
         child.stderr?.on('data', capture);
         child.once('error', reject);
         child.once('close', (exitCode, signal) => {
+            const capturedOutput = sanitizeInstallerOutput(Buffer.concat(output).toString('utf-8'));
             if (exitCode === 0) {
                 resolve({
                     kind: 'success',
                     exitCode,
-                    signal
+                    signal,
+                    output: capturedOutput,
+                    outputTruncated
                 });
                 return;
             }
-            const capturedOutput = Buffer.concat(output).toString('utf-8');
-            const logPath = writeUpdateFailureLog({
-                command: request.command,
-                exitCode,
-                signal,
-                output: capturedOutput,
-                truncated: outputTruncated,
-                resolveLogPath
-            });
+            const logPath = appendUpdateLog({
+                title: 'ShortcutXL update failure',
+                fields: {
+                    attemptId: request.attemptId,
+                    command: request.command,
+                    exitCode: String(exitCode),
+                    signal: String(signal),
+                    outputTruncatedAfterBytes: outputTruncated ? MAX_CAPTURED_OUTPUT_BYTES : undefined
+                }
+            }, capturedOutput, resolveLogPath);
             resolve({
                 kind: 'failed',
                 exitCode,
                 signal,
-                message: summarizeUpdateFailure(capturedOutput, request.command),
+                output: capturedOutput,
+                outputTruncated,
+                message: summarizeUpdateFailure(capturedOutput, request.command, request.preserveNpmConfig),
                 logPath
             });
         });
     });
 }
-function summarizeUpdateFailure(output, updateCommand) {
+function summarizeUpdateFailure(output, updateCommand, preserveNpmConfig = false) {
+    const retry = preserveNpmConfig
+        ? 'Restart Shortcut and select Update now to retry with your npm configuration.'
+        : `Retry with \`${updateCommand}\`.`;
     if (/EEXIST[\s\S]*shortcut\.cmd/i.test(output) ||
         /File exists:[\s\S]*shortcut\.cmd/i.test(output)) {
         return [
             'ShortcutXL could not update because an existing global `shortcut` command blocked npm from replacing it.',
-            `Close any running ShortcutXL terminals, remove the existing global ShortcutXL package, then retry \`${updateCommand}\`.`
+            'Close any running ShortcutXL terminals and remove the existing global ShortcutXL package.',
+            retry
         ].join(' ');
     }
     if (/EPERM|ENOTEMPTY|ENOENT/i.test(output) &&
         /AppData[\\/]+Roaming[\\/]+npm[\\/]+node_modules[\\/]+shortcutxl/i.test(output)) {
         return [
             'ShortcutXL could not update because npm could not clean up the previous global install.',
-            `Close ShortcutXL terminals and retry \`${updateCommand}\`.`
+            'Close ShortcutXL terminals.',
+            retry
         ].join(' ');
     }
-    return `ShortcutXL could not update automatically. Retry with \`${updateCommand}\`.`;
-}
-function writeUpdateFailureLog({ command, exitCode, signal, output, truncated, resolveLogPath }) {
-    try {
-        const logPath = resolveLogPath();
-        mkdirSync(dirname(logPath), { recursive: true });
-        appendFileSync(logPath, [
-            '',
-            '--- ShortcutXL update failure ---',
-            `time=${new Date().toISOString()}`,
-            `command=${command}`,
-            `exitCode=${String(exitCode)}`,
-            `signal=${String(signal)}`,
-            truncated ? `outputTruncatedAfterBytes=${MAX_CAPTURED_OUTPUT_BYTES}` : undefined,
-            output
-        ]
-            .filter((line) => line !== undefined)
-            .join('\n'), 'utf-8');
-        return logPath;
+    if (/ETARGET|No matching version found for shortcutxl@/i.test(output)) {
+        return [
+            'ShortcutXL could not update because your configured package registry does not have this release yet.',
+            `Check the registry with \`${process.platform === 'win32' ? 'npm.cmd' : 'npm'} config get registry\` and ask your administrator to sync ShortcutXL.`,
+            retry
+        ].join(' ');
     }
-    catch {
-        return undefined;
+    return `ShortcutXL could not update automatically. ${retry}`;
+}
+/** Read only the path, never registry credentials or the contents of an npmrc. */
+async function readNpmGlobalConfig(shell, env, cwd) {
+    const { stdout } = await promisify(execFile)(shell.shell, [...shell.args, 'npm config get globalconfig --global'], {
+        cwd,
+        env,
+        encoding: 'utf8',
+        timeout: 15_000,
+        maxBuffer: 64 * 1024,
+        windowsHide: true
+    });
+    return stdout.trim();
+}
+/** Only inspect process metadata. Probe messages/output can contain private npm configuration. */
+function classifyConfigProbeFailure(cause, invalidPath) {
+    if (invalidPath)
+        return { failure_class: 'invalid_config_path' };
+    const error = cause && typeof cause === 'object'
+        ? cause
+        : {};
+    if (error.code === 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER')
+        return { failure_class: 'probe_output_limit' };
+    if (error.code === 'ENOENT')
+        return { failure_class: 'probe_not_found' };
+    if (error.code === 'EACCES' || error.code === 'EPERM')
+        return { failure_class: 'probe_access_denied' };
+    // Node uses killed/signal for timeout as well as termination; do not claim which caused it.
+    if (error.killed === true || typeof error.signal === 'string')
+        return { failure_class: 'probe_terminated' };
+    if (typeof error.code === 'number' && Number.isSafeInteger(error.code)) {
+        return { failure_class: 'probe_exit', config_probe_exit_code: error.code };
     }
+    return { failure_class: 'probe_error' };
 }
 //# sourceMappingURL=update-action.js.map

package/dist/startup/update-diagnostics.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Durable diagnostics for startup package updates.
+ *
+ * The update gate runs before the runtime's client logger exists (`shortcut app` exits before
+ * main starts), so every attempt leaves two local records: a debug-log section with sanitized
+ * installer output, and a bounded receipt that the next runtime start reports through the client
+ * logger. A receipt still `started` at that point means the attempt never recorded an outcome.
+ */
+import type { ShortcutClientLogger } from '../app/observability/client-logging/client-logger.js';
+export type UpdateAttemptOutcome = 'verified' | 'failed' | 'not_installed' | 'shadowed' | 'unconfirmed' | 'error' | 'missing_terminal';
+export interface UpdateFailureDiagnostics {
+    failure_stage?: 'npm_config' | 'installer';
+    /** Allowlisted classification; never a raw exception code or message. */
+    failure_class?: string;
+    /** Probe status is separate from the installer status: no installer ran on probe failure. */
+    config_probe_exit_code?: number;
+}
+/** Content-free record of one accepted update. Never holds paths, output or account data. */
+export interface UpdateAttemptReceipt extends UpdateFailureDiagnostics {
+    attempt_id: string;
+    started_at: string;
+    from_version: string;
+    target_version: string;
+    package_manager: string;
+    /** Whether npm was bound to the running installation's prefix. */
+    prefix_bound: boolean;
+    phase: 'started' | 'finished';
+    outcome?: UpdateAttemptOutcome;
+    exit_code?: number | null;
+    signal?: string | null;
+    duration_ms?: number;
+    /** Version read back from the running installation's package.json after the install. */
+    installed_version?: string;
+    /** Version a fresh `shortcut` on PATH runs after the install. */
+    resolved_version?: string;
+    resolved_command_found?: boolean;
+    /** Whether that fresh `shortcut` runs the installation that was updated. */
+    resolved_matches_installation?: boolean;
+    /** `package`: read from the package the shim names; `probe`: from running it with --version. */
+    resolved_version_source?: 'package' | 'probe';
+    warning_count?: number;
+    output_truncated?: boolean;
+    reported?: boolean;
+}
+export declare function getUpdateAttemptsPath(): string;
+/** Strip terminal escapes and credentials from installer output before it is stored or shown. */
+export declare function sanitizeInstallerOutput(output: string): string;
+/** Warnings to show in the terminal, and the distinct count kept for the receipt. */
+export declare function boundedInstallerWarnings(sanitizedOutput: string): {
+    shown: string[];
+    count: number;
+};
+/** Bounded failure class from installer output; never raw text. */
+export declare function classifyInstallerFailure(sanitizedOutput: string): string | undefined;
+/** Append one update section, with sanitized installer output, to the CLI debug log. */
+export declare function appendUpdateLog(section: {
+    title: string;
+    fields: Record<string, string | number | boolean | null | undefined>;
+}, output: string | undefined, resolveLogPath?: () => string): string | undefined;
+export interface UpdateAttemptRecorder {
+    readonly attemptId: string;
+    finish(result: Omit<UpdateAttemptReceipt, keyof StartedFields | 'phase' | 'reported'>): void;
+}
+type StartedFields = Pick<UpdateAttemptReceipt, 'attempt_id' | 'started_at' | 'from_version' | 'target_version' | 'package_manager' | 'prefix_bound'>;
+/**
+ * Persist a `started` receipt before the installer runs, so an attempt killed mid-install is
+ * still visible to the next runtime start. Recording never blocks or fails the update.
+ */
+export declare function startUpdateAttempt(input: Omit<StartedFields, 'attempt_id' | 'started_at'>, options?: {
+    path?: string;
+    now?: () => Date;
+}): UpdateAttemptRecorder;
+/**
+ * Report unreported update receipts through the runtime logger. `running_version` is the version
+ * this start runs, which shows whether the previous attempt actually took effect. Receipts are
+ * marked reported only after the logger confirms delivery; a start that exits first (or a policy
+ * that keeps usage logs local) leaves them for the next start. Rows may repeat: join on
+ * `attempt_id`.
+ */
+export declare function reportPendingUpdateAttempts(logger: Pick<ShortcutClientLogger, 'info' | 'warn' | 'flush'>, options?: {
+    path?: string;
+    runningVersion?: string;
+}): Promise<number>;
+export {};
+//# sourceMappingURL=update-diagnostics.d.ts.map

package/dist/startup/update-diagnostics.js

@@ -0,0 +1,188 @@
+/**
+ * Durable diagnostics for startup package updates.
+ *
+ * The update gate runs before the runtime's client logger exists (`shortcut app` exits before
+ * main starts), so every attempt leaves two local records: a debug-log section with sanitized
+ * installer output, and a bounded receipt that the next runtime start reports through the client
+ * logger. A receipt still `started` at that point means the attempt never recorded an outcome.
+ */
+import { randomUUID } from 'crypto';
+import { appendFileSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { getAgentDir, getDebugLogPath, VERSION } from '../config.js';
+const MAX_RECEIPTS = 20;
+const MAX_WARNING_LINES = 5;
+const MAX_WARNING_LENGTH = 240;
+export function getUpdateAttemptsPath() {
+    return join(getAgentDir(), 'update-attempts.json');
+}
+const REDACTIONS = [
+    // .npmrc-style credentials echoed by npm config errors.
+    [/(_authToken|_auth|_password|password|token)(\s*[=:]\s*)\S+/gi, '$1$2[redacted]'],
+    [/(authorization:\s*)(bearer|basic)?\s*\S+/gi, '$1[redacted]'],
+    [/\bbearer\s+[\w.~+/-]+=*/gi, 'Bearer [redacted]'],
+    // Credentials embedded in registry URLs.
+    [/(\b[a-z][\w+.-]*:\/\/)[^\s/@:]+(?::[^\s/@]*)?@/gi, '$1[redacted]@'],
+    // npm and GitHub token formats.
+    [/\bnpm_[A-Za-z0-9]{20,}\b/g, '[redacted]'],
+    [/\bgh[pousr]_[A-Za-z0-9]{20,}\b/g, '[redacted]']
+];
+/** Strip terminal escapes and credentials from installer output before it is stored or shown. */
+export function sanitizeInstallerOutput(output) {
+    let sanitized = output.replace(/\x1b\[[0-9;?]*[ -/]*[@-~]/g, '').replace(/\r(?!\n)/g, '\n');
+    for (const [pattern, replacement] of REDACTIONS) {
+        sanitized = sanitized.replace(pattern, replacement);
+    }
+    return sanitized;
+}
+/** Warning lines npm, pnpm and yarn print, deduplicated. */
+function installerWarnings(sanitizedOutput) {
+    const warnings = [];
+    for (const raw of sanitizedOutput.split('\n')) {
+        const line = raw.trim();
+        if (!/^(npm\s+warn(ing)?\b|warn\b|warning\b)/i.test(line))
+            continue;
+        const bounded = line.length > MAX_WARNING_LENGTH ? `${line.slice(0, MAX_WARNING_LENGTH)}…` : line;
+        if (!warnings.includes(bounded))
+            warnings.push(bounded);
+    }
+    return warnings;
+}
+/** Warnings to show in the terminal, and the distinct count kept for the receipt. */
+export function boundedInstallerWarnings(sanitizedOutput) {
+    const warnings = installerWarnings(sanitizedOutput);
+    return { shown: warnings.slice(0, MAX_WARNING_LINES), count: warnings.length };
+}
+/** Bounded failure class from installer output; never raw text. */
+export function classifyInstallerFailure(sanitizedOutput) {
+    const codes = ['ETARGET', 'E404', 'EEXIST', 'EPERM', 'EACCES', 'EBUSY', 'ENOTEMPTY', 'ENOENT'];
+    const code = codes.find((candidate) => new RegExp(`\\b${candidate}\\b`).test(sanitizedOutput));
+    if (code)
+        return code.toLowerCase();
+    if (/\b(E401|E403|ENEEDAUTH|EAUTH)\b/i.test(sanitizedOutput))
+        return 'authentication';
+    if (/\b(SELF_SIGNED_CERT_IN_CHAIN|DEPTH_ZERO_SELF_SIGNED_CERT|UNABLE_TO_VERIFY_LEAF_SIGNATURE|CERT_HAS_EXPIRED|UNABLE_TO_GET_ISSUER_CERT_LOCALLY|ERR_TLS_CERT_ALTNAME_INVALID)\b/i.test(sanitizedOutput))
+        return 'certificate';
+    if (/ECONNREFUSED|ECONNRESET|ETIMEDOUT|ENOTFOUND|EAI_AGAIN|network/i.test(sanitizedOutput))
+        return 'network';
+    if (/integrity|EINTEGRITY|TAR_BAD_ARCHIVE|unexpected end/i.test(sanitizedOutput))
+        return 'integrity';
+    return undefined;
+}
+/** Append one update section, with sanitized installer output, to the CLI debug log. */
+export function appendUpdateLog(section, output, resolveLogPath = getDebugLogPath) {
+    try {
+        const logPath = resolveLogPath();
+        mkdirSync(dirname(logPath), { recursive: true });
+        const lines = [
+            '',
+            `--- ${section.title} ---`,
+            `time=${new Date().toISOString()}`,
+            ...Object.entries(section.fields)
+                .filter(([, value]) => value !== undefined)
+                .map(([key, value]) => `${key}=${String(value)}`),
+            ...(output ? [sanitizeInstallerOutput(output)] : [])
+        ];
+        appendFileSync(logPath, `${lines.join('\n')}\n`, 'utf-8');
+        return logPath;
+    }
+    catch {
+        return undefined;
+    }
+}
+function readReceipts(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+        return Array.isArray(parsed)
+            ? parsed.filter((entry) => typeof entry === 'object' &&
+                entry !== null &&
+                typeof entry.attempt_id === 'string')
+            : [];
+    }
+    catch {
+        return [];
+    }
+}
+function writeReceipts(path, receipts) {
+    mkdirSync(dirname(path), { recursive: true });
+    const temporary = `${path}.${process.pid}.tmp`;
+    writeFileSync(temporary, `${JSON.stringify(receipts.slice(-MAX_RECEIPTS), null, 2)}\n`, 'utf-8');
+    renameSync(temporary, path);
+}
+/**
+ * Persist a `started` receipt before the installer runs, so an attempt killed mid-install is
+ * still visible to the next runtime start. Recording never blocks or fails the update.
+ */
+export function startUpdateAttempt(input, options = {}) {
+    const path = options.path ?? getUpdateAttemptsPath();
+    const now = options.now ?? (() => new Date());
+    const started = now();
+    const receipt = {
+        ...input,
+        attempt_id: randomUUID(),
+        started_at: started.toISOString(),
+        phase: 'started'
+    };
+    const save = (next) => {
+        try {
+            const receipts = readReceipts(path).filter((entry) => entry.attempt_id !== next.attempt_id);
+            writeReceipts(path, [...receipts, next]);
+        }
+        catch {
+            // Diagnostics are best effort; the terminal and debug log still report the result.
+        }
+    };
+    save(receipt);
+    return {
+        attemptId: receipt.attempt_id,
+        finish(result) {
+            save({
+                ...receipt,
+                ...result,
+                phase: 'finished',
+                duration_ms: result.duration_ms ?? now().getTime() - started.getTime()
+            });
+        }
+    };
+}
+/**
+ * Report unreported update receipts through the runtime logger. `running_version` is the version
+ * this start runs, which shows whether the previous attempt actually took effect. Receipts are
+ * marked reported only after the logger confirms delivery; a start that exits first (or a policy
+ * that keeps usage logs local) leaves them for the next start. Rows may repeat: join on
+ * `attempt_id`.
+ */
+export async function reportPendingUpdateAttempts(logger, options = {}) {
+    const path = options.path ?? getUpdateAttemptsPath();
+    const pending = readReceipts(path).filter((receipt) => !receipt.reported);
+    if (pending.length === 0)
+        return 0;
+    const runningVersion = options.runningVersion ?? VERSION;
+    for (const receipt of pending) {
+        const { reported: _reported, phase, ...fields } = receipt;
+        const outcome = phase === 'started' ? 'missing_terminal' : (receipt.outcome ?? 'missing_terminal');
+        const emit = outcome === 'verified' ? logger.info : logger.warn;
+        emit.call(logger, {
+            module: 'lifecycle',
+            event: 'cli_update_attempt',
+            data: {
+                ...fields,
+                outcome,
+                running_version: runningVersion,
+                running_target_version: runningVersion === receipt.target_version
+            }
+        });
+    }
+    if (!(await logger.flush()))
+        return 0;
+    const delivered = new Set(pending.map((receipt) => receipt.attempt_id));
+    try {
+        // Re-read so attempts recorded meanwhile are kept as they are.
+        writeReceipts(path, readReceipts(path).map((receipt) => delivered.has(receipt.attempt_id) ? { ...receipt, reported: true } : receipt));
+    }
+    catch {
+        // An unwritable agent dir reports the same receipts again next start.
+    }
+    return pending.length;
+}
+//# sourceMappingURL=update-diagnostics.js.map

package/dist/startup/update-execution.d.ts

@@ -1,11 +1,23 @@
 import { type ForegroundUpdateResult, type UpdateLaunchRequest } from './update-action.js';
+import { appendUpdateLog, startUpdateAttempt } from './update-diagnostics.js';
 import type { AvailableUpdate } from './update-manager.js';
+import { type UpdateVerification } from './update-verification.js';
 interface StartupUpdateExecutionOptions {
     runUpdate?: (request: UpdateLaunchRequest) => Promise<ForegroundUpdateResult>;
+    verify?: (update: AvailableUpdate) => Promise<UpdateVerification>;
+    startAttempt?: typeof startUpdateAttempt;
+    appendLog?: typeof appendUpdateLog;
+    platform?: NodeJS.Platform;
     log?: (message: string) => void;
     error?: (message: string) => void;
 }
-/** Execute an accepted package update and print the shared terminal result. */
+/**
+ * Execute an accepted package update and print the shared terminal result.
+ *
+ * Exit code 0 is not enough (#14571): success is reported only after the installed package and
+ * the `shortcut` each shell runs next read back as the advertised release; otherwise the user
+ * gets the mismatch and how to recover, and the update exits 1.
+ */
 export declare function executeStartupUpdate(update: AvailableUpdate, options?: StartupUpdateExecutionOptions): Promise<ForegroundUpdateResult>;
 export {};
 //# sourceMappingURL=update-execution.d.ts.map