fix: surface why an automatic update failed

A background install that failed left no trace of why. The installer was
spawned with stdio: 'ignore', so its error output was discarded and lastFailure
recorded only an exit code; the TUI then told the user to restart and, on the
next launch, showed the ordinary update prompt with no sign that two attempts
had already failed. Diagnosing a broken installer meant reproducing the spawn by
hand.

- Pipe the installer's stderr and store its tail in lastFailure.message.
- Show that message on the update prompt when it belongs to the offered version.
- Pin the target version for native installs on macOS and Linux with
  '-s -- --version', the guarantee PYTHINKER_VERSION already gave on Windows;
  unpinned, the script installed whatever the CDN called latest.
- Tell the user to open a new terminal, which is what actually applies a native
  update, rather than to restart the CLI.

Author: elkaix

.changeset/surface-update-install-failures.md

@@ -0,0 +1,5 @@
+---
+"@pythoughts/pythinker-code": patch
+---
+
+Report why an automatic update failed instead of failing silently: the installer's error output is now recorded and shown on the next update prompt, native installs on macOS and Linux pin the version the rollout picked, and update messages tell you to open a new terminal to apply the update.

apps/pythinker-code/src/cli/update/preflight.ts

@@ -1,6 +1,7 @@
 import { spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import { homedir } from 'node:os';
+import type { Readable } from 'node:stream';
 
 import { gte, valid } from 'semver';
 
@@ -10,6 +11,7 @@ import type { TelemetryProperties } from '@pythoughts/pythinker-telemetry';
 import {
   NATIVE_INSTALL_COMMAND_UNIX,
   NATIVE_INSTALL_COMMAND_WIN,
+  PYTHINKER_CODE_INSTALL_SH_URL,
 } from '#/constant/app';
 import { loadTuiConfig } from '#/tui/config';
 
@@ -163,7 +165,18 @@ export function spawnForSource(
       // would look like a successful update. `pipefail` makes the pipeline
       // surface curl's non-zero status so installUpdate() rejects and we warn
       // instead of printing "Updated …".
-      return { cmd: 'bash', args: ['-c', `set -o pipefail; ${NATIVE_INSTALL_COMMAND_UNIX}`] };
+      //
+      // `-s -- --version` pins the install to the version this preflight
+      // decided on, the same guarantee PYTHINKER_VERSION gives on Windows.
+      // Without it the script installs whatever the CDN currently calls
+      // latest, which can differ from the rollout's target.
+      return {
+        cmd: 'bash',
+        args: [
+          '-c',
+          `set -o pipefail; curl -fsSL ${PYTHINKER_CODE_INSTALL_SH_URL} | bash -s -- --version ${version}`,
+        ],
+      };
     case 'unsupported':
       throw new Error('unsupported install source cannot be auto-installed');
   }
@@ -207,7 +220,10 @@ export function renderManualUpdateMessage(
 }
 
 export function renderInstallSuccessMessage(target: UpdateTarget): string {
-  return `Updated ${NPM_PACKAGE_NAME} to ${target.version}. Restart the CLI to use the new version.\n`;
+  return (
+    `Updated ${NPM_PACKAGE_NAME} to ${target.version}. ` +
+    'Close this terminal and open a new one to use the new version.\n'
+  );
 }
 
 function renderBackgroundInstallSuccessNotice(version: string): string {
@@ -548,16 +564,31 @@ async function promptInstall(
   target: UpdateTarget,
   source: InstallSource,
   installCommand: string,
+  previousFailure: string | undefined,
 ): Promise<InstallPromptChoiceValue> {
   const options: InstallPromptOptions = {
     currentVersion,
     target,
     installSource: source,
     installCommand,
+    previousFailure,
   };
   return promptForInstallChoice(options);
 }
 
+/**
+ * A recorded failure is only worth showing when it is about the version the
+ * prompt is offering — an older version's failure is stale noise.
+ */
+function failureMessageFor(
+  state: UpdateInstallState,
+  target: UpdateTarget,
+): string | undefined {
+  const failure = state.lastFailure;
+  if (failure === null || failure.version !== target.version) return undefined;
+  return failure.message;
+}
+
 export async function installUpdate(
   source: InstallSource,
   version: string,
@@ -581,6 +612,41 @@ export async function installUpdate(
   });
 }
 
+/** Keep the tail only: installers can be chatty, and the state file is small. */
+const INSTALLER_STDERR_TAIL_CHARS = 2000;
+
+/**
+ * Buffer the installer's stderr so a failed background install records why it
+ * failed. Discarding it (the previous `stdio: 'ignore'`) left `lastFailure`
+ * with nothing but an exit code, which made a broken installer script
+ * impossible to diagnose without reproducing the spawn by hand.
+ */
+function captureStderrTail(child: ReturnType<typeof spawn>): () => string | undefined {
+  // Typed `Readable | null`, but absent entirely when stderr was not piped.
+  const stream: Readable | null | undefined = child.stderr;
+  if (stream === null || stream === undefined) return () => undefined;
+  let tail = '';
+  stream.setEncoding('utf8');
+  stream.on('data', (chunk: string) => {
+    tail = (tail + chunk).slice(-INSTALLER_STDERR_TAIL_CHARS);
+  });
+  // A detached installer outliving this process must not crash it, and the
+  // pipe must not hold the event loop open on the way out. `child.stderr` is
+  // typed as a plain Readable, but the pipe is a Socket at runtime and that is
+  // where unref lives.
+  stream.on('error', () => {});
+  (stream as Readable & { unref?: () => void }).unref?.();
+  return () => {
+    const trimmed = tail.trim();
+    return trimmed.length === 0 ? undefined : trimmed;
+  };
+}
+
+function describeChildExit(cmd: string, code: number | null, signal: NodeJS.Signals | null): string {
+  const detail = signal !== null ? `signal ${signal}` : `code ${String(code)}`;
+  return `${cmd} exited with ${detail}`;
+}
+
 async function waitForChildSpawn(child: ReturnType<typeof spawn>): Promise<void> {
   await new Promise<void>((resolve, reject) => {
     const onSpawn = (): void => {
@@ -750,16 +816,18 @@ async function startBackgroundInstall(
     // the terminal outcome until the handler is "ready".
     let ready = false;
     let settled = false;
-    let pendingOutcome: boolean | undefined;
+    let pendingOutcome: { succeeded: boolean; reason: string } | undefined;
 
-    const finish = async (succeeded: boolean): Promise<void> => {
+    const finish = async (succeeded: boolean, reason: string): Promise<void> => {
       if (!ready) {
-        pendingOutcome ??= succeeded;
+        pendingOutcome ??= { succeeded, reason };
         return;
       }
       if (settled) return;
       settled = true;
       const attempts = failureAttemptsFor(startedState, target, 'install') + 1;
+      const stderrTail = readStderrTail();
+      const message = stderrTail === undefined ? reason : `${reason}: ${stderrTail}`;
 
       const nextState: UpdateInstallState = succeeded
         ? {
@@ -780,6 +848,7 @@ async function startBackgroundInstall(
             failedAt: nowIso(),
             attempts,
             operation: 'install',
+            message,
           },
         };
       try {
@@ -804,6 +873,7 @@ async function startBackgroundInstall(
           targetVersion: target.version,
           source,
           attempts,
+          message,
         });
       } finally {
         await lock.release().catch(() => {});
@@ -815,11 +885,16 @@ async function startBackgroundInstall(
       // A detached child gets its own console window on Windows regardless
       // of stdio; stdio: 'ignore' alone does not suppress it.
       windowsHide: platform === 'win32',
-      stdio: 'ignore',
+      // stdout stays discarded (install progress is noise); stderr is piped so
+      // a failure records the installer's own error text.
+      stdio: ['ignore', 'ignore', 'pipe'],
       env: env === undefined ? undefined : { ...process.env, ...env },
     });
-    child.once('error', () => { void finish(false); });
-    child.once('exit', (code) => { void finish(code === 0); });
+    const readStderrTail = captureStderrTail(child);
+    child.once('error', (error) => { void finish(false, formatErrorMessage(error)); });
+    child.once('exit', (code, signal) => {
+      void finish(code === 0, describeChildExit(cmd, code, signal));
+    });
     if (child.pid !== undefined && child.pid > 0) {
       const stateWithPid: UpdateInstallState = {
         ...startedState,
@@ -841,7 +916,7 @@ async function startBackgroundInstall(
     child.unref();
     finalizerOwnsLock = true;
     ready = true;
-    if (pendingOutcome !== undefined) void finish(pendingOutcome);
+    if (pendingOutcome !== undefined) void finish(pendingOutcome.succeeded, pendingOutcome.reason);
     return true;
   // When startup failed before handoff, release the lock here; the
   // finalizer releases it once the terminal state write completes.
@@ -1196,7 +1271,13 @@ export async function runUpdatePreflight(
       return 'continue';
     }
 
-    const choice = await promptInstall(currentVersion, userVisibleTarget, source, installCommand);
+    const choice = await promptInstall(
+      currentVersion,
+      userVisibleTarget,
+      source,
+      installCommand,
+      failureMessageFor(installState, userVisibleTarget),
+    );
     if (choice === 'skip') return 'continue';
 
     try {

apps/pythinker-code/src/cli/update/prompt.ts

@@ -28,10 +28,30 @@ export interface InstallPromptOptions {
   readonly target: UpdateTarget;
   readonly installCommand: string;
   readonly installSource: InstallSource;
+  /**
+   * Why the last automatic install of this same version failed. A silently
+   * failed background install otherwise looks identical to one that never
+   * started, and the prompt is where the user decides what to do about it.
+   */
+  readonly previousFailure?: string;
   readonly input?: NodeJS.ReadStream;
   readonly output?: NodeJS.WriteStream;
 }
 
+/** Keep the prompt readable: one line, the first line of the recorded error. */
+const FAILURE_SUMMARY_MAX_CHARS = 120;
+
+export function summarizeInstallFailure(message: string): string | undefined {
+  const firstLine = message
+    .split('\n')
+    .map((line) => line.trim())
+    .find((line) => line.length > 0);
+  if (firstLine === undefined) return undefined;
+  return firstLine.length > FAILURE_SUMMARY_MAX_CHARS
+    ? `${firstLine.slice(0, FAILURE_SUMMARY_MAX_CHARS - 1)}…`
+    : firstLine;
+}
+
 const INSTALL_HINT = 'Install update now';
 const SKIP_HINT = 'Continue with current version';
 
@@ -78,10 +98,25 @@ function renderInstallPrompt(
     `${label('Target ')}  ${targetVersion}`,
     `${label('Source ')}  ${sourceLabel}`,
     `${label('Command')}  ${command}`,
+  ];
+
+  const failureSummary =
+    options.previousFailure === undefined
+      ? undefined
+      : summarizeInstallFailure(options.previousFailure);
+  if (failureSummary !== undefined) {
+    lines.push(
+      '',
+      chalk.hex(UPDATE_PROMPT_WARNING).bold('The last automatic update failed'),
+      chalk.hex(UPDATE_PROMPT_MUTED)(failureSummary),
+    );
+  }
+
+  lines.push(
     '',
     chalk.hex(UPDATE_PROMPT_MUTED)('↑↓ choose · Enter confirm · Esc continue'),
     '',
-  ];
+  );
 
   for (let i = 0; i < choices.length; i++) {
     const choice = choices[i];

apps/pythinker-code/src/tui/commands/info.ts

@@ -314,18 +314,18 @@ export async function handleUpdateCommand(
       host.showNotice(
         `Updating to v${result.version}`,
         result.installOnRestart
-          ? 'Preparing with Homebrew in the background. Once ready, restart the CLI to install it.'
-          : 'Installing in the background — restart the CLI when it completes.',
+          ? 'Preparing with Homebrew in the background. Once ready, close this terminal and open a new one to install it.'
+          : 'Installing in the background — close this terminal and open a new one to apply the update.',
       );
       return;
     case 'in-progress':
       host.showNotice(
         `Update to v${result.version} already in progress`,
         result.installOnRestart
           ? result.readyToInstall
-            ? 'Restart the CLI to install it.'
-            : 'Restart after the current update operation finishes.'
-          : 'Restart the CLI once it completes.',
+            ? 'Close this terminal and open a new one to install it.'
+            : 'Close this terminal and open a new one after the current update operation finishes.'
+          : 'Close this terminal and open a new one once it completes.',
       );
       return;
     case 'manual':