fix(cli): show the background update notice inside the TUI (#379)

## Requirement or Bug

After a background auto-update, the "Pythinker Code updated to vX"
notice never shows in fullscreen mode.

## Bug Reproduction Steps

1. Set `tui_mode = "fullscreen"` and `[upgrade] auto_install = true` in
`tui.toml`.
2. Launch an older native build. The background check installs the new
version with no message.
3. Launch again. `install.json` records `notifiedAt`, but the screen
shows only the welcome banner.

## Root Cause

`showPendingBackgroundInstallNotice` wrote the notice to stdout before
the TUI started. Fullscreen mode enters the alternate screen and clears
it (`\x1b[?1049h` + `\x1b[2J`), so the line was erased right after it
was written, and `notifiedAt` was already set so it never came back.
This is a fundamental fix: the notice now goes through the TUI's
existing startup-notice path.

## Code Changes

```diff
  handleMainCommand (shell mode)
-   runUpdatePreflight(version, { track })            // notice -> stdout
+   runUpdatePreflight(version, { track, onUpdateNotice })  // notice -> variable
+   if result === 'exit': write the notice to stdout, then exit
-   runShell(options, version)
+   runShell(options, version, { updateNotice })
      PythinkerTUI({ startupNotice: combineStartupNotice(updateNotice, configWarning) })
        finishStartup -> showStatus(startupNotice)   // transcript, survives fullscreen
```

- `preflight.ts`: new optional `onUpdateNotice` option. Without it the
notice still goes to stdout.
- `main.ts`: shell mode collects the notice and passes it to `runShell`.
Print mode passes no callback, so it is unchanged.
- `run-shell.ts`: merges the update notice with the existing `tui.toml`
parse warning.

## Behavior Changes and Affected Users

| Behavior | Before | After | Who relies on the old behavior | Escape
hatch |
|---|---|---|---|---|
| Update notice, TUI fullscreen | Written to stdout, then erased by the
alt screen | Shown in the transcript | Nobody (never visible) | n/a |
| Update notice, TUI inline (`tui_mode = "regular"`) | Plain stdout line
above the TUI | Dim status line in the transcript | Users who read it in
scrollback | none; the text is the same |
| Update notice when preflight returns `exit` | stdout | stdout (written
just before exit) | Same population | n/a |
| Update notice, print mode / non-TTY | Not shown (`isTTY: false`) | Not
shown | Headless scripts | n/a |
| `runUpdatePreflight` with no `onUpdateNotice` | stdout | stdout | Any
other caller | n/a |

Affected module: `apps/pythinker-code` CLI startup. Test coverage:
- `preflight.test.ts`: notice goes to `onUpdateNotice` and not stdout;
the existing stdout test still passes.
- `main.test.ts`: shell mode hand-off to `runShell`; the `exit` path
prints the notice; print mode is unchanged.
- `run-shell.test.ts`: `updateNotice` becomes the TUI `startupNotice`.
- `pythinker-tui-startup.test.ts`: in fullscreen, the startup notice
renders in the transcript.
- Live run: `pnpm dev:cli` in fullscreen with a pending `lastSuccess`
shows "Pythinker Code updated to v2.7.0" and the changelog link in the
transcript.

## Checklist

- [x] I have read the
[CONTRIBUTING](https://github.com/PyModel/pythinker-code/blob/main/CONTRIBUTING.md)
document.
- [ ] I have linked a related issue (external PRs: issue must have a
maintainer's `/approve`).
- [x] I have added tests that prove my feature works.
- [x] The behavior-change table above is complete, and every removed
behavior or flipped default is named in the changeset and either has an
escape hatch or was explicitly approved by a maintainer in this PR.
- [x] Ran `gen-changesets` skill, or this PR needs no changeset.
- [x] Ran `gen-docs` skill, or this PR needs no doc update.


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **New Features**
* Background update completion notices now appear in the TUI startup
message. If the app exits before the TUI opens, the notice is shown in
the terminal instead.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: elkaix

.changeset/tui-update-notice.md

@@ -0,0 +1,5 @@
+---
+"@pymodel/pythinker-code": patch
+---
+
+Show the "Pythinker Code updated" notice inside the TUI after a background update, so fullscreen mode no longer hides it.

apps/pythinker-code/src/cli/run-shell.ts

@@ -25,6 +25,7 @@ import type { TuiConfig } from '#/tui/config';
 import { loadTuiConfig, TuiConfigParseError } from '#/tui/config';
 import { CHROME_GUTTER } from '#/tui/constant/rendering';
 import { PythinkerTUI } from '#/tui/index';
+import { combineStartupNotice } from '#/tui/utils/startup';
 import { startupTrace } from '#/utils/startup-trace';
 import { currentTheme, getColorPalette } from '#/tui/theme';
 import { toTerminalHyperlink } from '#/utils/terminal-hyperlink';
@@ -39,7 +40,7 @@ import { createPythinkerCodeHostIdentity } from './version';
 export async function runShell(
   opts: CLIOptions,
   version: string,
-  runOptions: { readonly migrateOnly?: boolean } = {},
+  runOptions: { readonly migrateOnly?: boolean; readonly updateNotice?: string } = {},
 ): Promise<void> {
   const startedAt = Date.now();
   const configStartedAt = startedAt;
@@ -139,7 +140,7 @@ export async function runShell(
     tuiConfig,
     version,
     workDir,
-    startupNotice: configWarning,
+    startupNotice: combineStartupNotice(runOptions.updateNotice, configWarning),
     migrationPlan,
     migrateOnly: runOptions.migrateOnly,
     telemetryDisabled: config.telemetry === false,

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

@@ -48,6 +48,7 @@ export interface RunUpdatePreflightOptions {
   readonly isTTY?: boolean;
   readonly track?: (event: string, properties?: TelemetryProperties) => void;
   readonly logger?: UpdateLogger;
+  readonly onUpdateNotice?: (notice: string) => void;
 }
 
 const AUTO_INSTALL_FAILURE_PROMPT_THRESHOLD = 2;
@@ -434,13 +435,13 @@ async function hasInstallInFlight(
 async function showPendingBackgroundInstallNotice(
   state: UpdateInstallState,
   currentVersion: string,
-  stdout: { write(chunk: string): boolean },
+  emitNotice: (notice: string) => void,
   track: RunUpdatePreflightOptions['track'],
   logger: UpdateLogger,
 ): Promise<UpdateInstallState> {
   const success = state.lastSuccess;
   if (success !== null && success.notifiedAt === null && success.version === currentVersion) {
-    stdout.write(renderBackgroundInstallSuccessNotice(success.version));
+    emitNotice(renderBackgroundInstallSuccessNotice(success.version));
     trackUpdateEvent(track, 'update_success_notice_shown', {
       version: success.version,
       inferred_from_active: false,
@@ -469,7 +470,7 @@ async function showPendingBackgroundInstallNotice(
   }
 
   const notifiedAt = nowIso();
-  stdout.write(renderBackgroundInstallSuccessNotice(active.version));
+  emitNotice(renderBackgroundInstallSuccessNotice(active.version));
   trackUpdateEvent(track, 'update_success_notice_shown', {
     version: active.version,
     inferred_from_active: true,
@@ -804,7 +805,7 @@ export async function runUpdatePreflight(
       installState = await showPendingBackgroundInstallNotice(
         installState,
         currentVersion,
-        stdout,
+        options.onUpdateNotice ?? ((notice) => { stdout.write(notice); }),
         options.track,
         logger,
       );

apps/pythinker-code/src/main.ts

@@ -75,12 +75,18 @@ export async function handleMainCommand(
   }
 
   startupTrace('preflight:begin');
+  // The TUI clears the screen on start, so a notice written to stdout here
+  // would vanish; hand it to the TUI to show in the transcript instead.
+  let updateNotice: string | undefined;
   const preflightResult = await runUpdatePreflight(
     version,
-    validated.uiMode === 'print' ? { track, isTTY: false } : { track },
+    validated.uiMode === 'print'
+      ? { track, isTTY: false }
+      : { track, onUpdateNotice: (notice) => { updateNotice = notice.trimEnd(); } },
   );
   startupTrace('preflight:end');
   if (preflightResult === 'exit') {
+    if (updateNotice !== undefined) process.stdout.write(`${updateNotice}\n`);
     process.exit(0);
   }
 
@@ -90,7 +96,7 @@ export async function handleMainCommand(
   }
 
   startupTrace('runShell:begin');
-  await runShell(validated.options, version);
+  await runShell(validated.options, version, { updateNotice });
   return { headlessCompleted: false };
 }
 

apps/pythinker-code/test/cli/main.test.ts

@@ -252,11 +252,32 @@ describe('main entry command handling', () => {
 
     expect(exitCode).toBeNull();
     expect(validateOptions).toHaveBeenCalledWith(opts);
-    expect(runUpdatePreflight).toHaveBeenCalledWith('0.0.1-alpha.2', { track: expect.any(Function) });
+    expect(runUpdatePreflight).toHaveBeenCalledWith('0.0.1-alpha.2', {
+      track: expect.any(Function),
+      onUpdateNotice: expect.any(Function),
+    });
     expect(mocks.runUpdatePreflight.mock.invocationCallOrder[0]).toBeLessThan(
       mocks.runShell.mock.invocationCallOrder[0]!,
     );
-    expect(runShell).toHaveBeenCalledWith(opts, '0.0.1-alpha.2');
+    expect(runShell).toHaveBeenCalledWith(opts, '0.0.1-alpha.2', { updateNotice: undefined });
+  });
+
+  it('passes the update notice from preflight to the shell', async () => {
+    const opts = defaultOpts();
+    mocks.validateOptions.mockReturnValue({ options: opts, uiMode: 'shell' });
+    mocks.runUpdatePreflight.mockImplementation(
+      async (_version: string, options: { onUpdateNotice?: (notice: string) => void }) => {
+        options.onUpdateNotice?.('Pythinker Code updated to v0.0.2\nChangelog: https://example.test\n');
+        return 'continue';
+      },
+    );
+    mocks.runShell.mockResolvedValue(void 0);
+
+    await runHandleMainCommand(opts);
+
+    expect(runShell).toHaveBeenCalledWith(opts, '0.0.1-alpha.2', {
+      updateNotice: 'Pythinker Code updated to v0.0.2\nChangelog: https://example.test',
+    });
   });
 
   it('runs prompt mode without interactive update preflight', async () => {
@@ -365,8 +386,9 @@ describe('main entry command handling', () => {
     expect(exitCode).toBeNull();
     expect(runUpdatePreflight).toHaveBeenCalledWith('0.0.1-alpha.2', {
       track: expect.any(Function),
+      onUpdateNotice: expect.any(Function),
     });
-    expect(runShell).toHaveBeenCalledWith(opts, '0.0.1-alpha.2');
+    expect(runShell).toHaveBeenCalledWith(opts, '0.0.1-alpha.2', { updateNotice: undefined });
   });
 
   it('installs crash handlers before parsing CLI arguments', async () => {
@@ -433,6 +455,27 @@ describe('main entry command handling', () => {
     expect(runShell).not.toHaveBeenCalled();
   });
 
+  it('prints the update notice to stdout when preflight requests process exit', async () => {
+    const opts = defaultOpts();
+    mocks.validateOptions.mockReturnValue({ options: opts, uiMode: 'shell' });
+    mocks.runUpdatePreflight.mockImplementation(
+      async (_version: string, options: { onUpdateNotice?: (notice: string) => void }) => {
+        options.onUpdateNotice?.('Pythinker Code updated to v0.0.2\n');
+        return 'exit';
+      },
+    );
+    const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+    try {
+      const exitCode = await runHandleMainCommand(opts);
+
+      expect(exitCode).toBe(0);
+      expect(writeSpy).toHaveBeenCalledWith('Pythinker Code updated to v0.0.2\n');
+      expect(runShell).not.toHaveBeenCalled();
+    } finally {
+      writeSpy.mockRestore();
+    }
+  });
+
   it('initializes and flushes telemetry around the upgrade command', async () => {
     const exitCode = await runHandleUpgradeCommand();
 

apps/pythinker-code/test/cli/run-shell.test.ts

@@ -653,6 +653,38 @@ describe('runShell', () => {
     });
   });
 
+  it('passes the update notice to the TUI as a startup notice', async () => {
+    mocks.loadTuiConfig.mockResolvedValue({
+      theme: 'dark',
+      editorCommand: null,
+      notifications: { enabled: true, condition: 'unfocused' },
+    });
+    mocks.tuiStart.mockResolvedValue(undefined);
+
+    await runShell(
+      {
+        session: '',
+        continue: false,
+        yolo: false,
+        auto: false,
+        plan: false,
+        model: undefined,
+        outputFormat: undefined,
+        prompt: undefined,
+        skillsDirs: [],
+        agent: undefined,
+        agentFiles: [],
+      },
+      '1.2.3-test',
+      { updateNotice: 'Pythinker Code updated to v1.2.3-test' },
+    );
+
+    const [, , startupInput] = mocks.pythinkerTuiConstructor.mock.calls[0]!;
+    expect(startupInput).toMatchObject({
+      startupNotice: 'Pythinker Code updated to v1.2.3-test',
+    });
+  });
+
   it('flushes diagnostic logs synchronously before exiting on a runtime crash', async () => {
     mocks.loadTuiConfig.mockResolvedValue({
       theme: 'dark',

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

@@ -975,6 +975,32 @@ describe('runUpdatePreflight', () => {
     expect(detectInstallSource).not.toHaveBeenCalled();
   });
 
+  it('hands the background update success notice to onUpdateNotice instead of stdout', async () => {
+    mocks.readUpdateCache.mockResolvedValue(emptyUpdateCache());
+    mocks.readUpdateInstallState.mockResolvedValue(installState({
+      lastSuccess: {
+        version: '0.5.0',
+        installedAt: '2026-04-23T08:00:00.000Z',
+        notifiedAt: null,
+      },
+    }));
+    mocks.refreshUpdateCache.mockResolvedValue(emptyUpdateCache());
+    const { stdout, options } = captureOutput();
+    const notices: string[] = [];
+
+    await expect(runUpdatePreflight('0.5.0', {
+      ...options,
+      onUpdateNotice: (notice) => { notices.push(notice); },
+    })).resolves.toBe('continue');
+
+    expect(stdout.join('')).toBe('');
+    expect(notices).toHaveLength(1);
+    expect(notices[0]).toContain('Pythinker Code updated to v0.5.0');
+    expect(writeUpdateInstallState).toHaveBeenCalledWith(expect.objectContaining({
+      lastSuccess: expect.objectContaining({ notifiedAt: expect.any(String) }),
+    }));
+  });
+
   it('infers a background update success notice when the active install version is now running', async () => {
     mocks.readUpdateCache.mockResolvedValue(emptyUpdateCache());
     mocks.readUpdateInstallState.mockResolvedValue(installState({

apps/pythinker-code/test/tui/pythinker-tui-startup.test.ts

@@ -327,6 +327,22 @@ describe('PythinkerTUI startup', () => {
     expect(transcript).toContain('No session yet — one will be created on your first message.');
   });
 
+  it('shows the startup update notice in the fullscreen transcript', async () => {
+    const harness = makeHarness(makeSession());
+    const driver = makeDriver(harness, {
+      ...makeStartupInput({}, { tuiMode: 'fullscreen' }),
+      startupNotice: 'Pythinker Code updated to v9.9.9',
+    });
+
+    await expect(driver.init()).resolves.toBe(false);
+    await (
+      driver as unknown as { finishStartup(shouldReplayHistory: boolean): Promise<void> }
+    ).finishStartup(false);
+
+    const transcript = driver.state.transcriptContainer.render(160).join('\n');
+    expect(transcript).toContain('Pythinker Code updated to v9.9.9');
+  });
+
   it('shows config defaults in appState before the lazy session exists (v2)', async () => {
     const harness = makeHarness(makeSession(), {
       getConfig: vi.fn(async () => ({