@pellux/goodvibes-tui 0.25.0 → 0.27.0

package/src/panels/wrfc-panel.ts

@@ -10,6 +10,7 @@ import {
   buildPanelWorkspace,
   resolveScrollablePanelSection,
   DEFAULT_PANEL_PALETTE,
+  extendPalette,
   type PanelWorkspaceSection,
   buildSelectablePanelLine,
   buildStyledPanelLine,
@@ -20,6 +21,7 @@ import {
   type ConfirmState,
   handleConfirmInput,
 } from './confirm-state.ts';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -31,14 +33,22 @@ const STALL_THRESHOLD_MS = 5 * 60 * 1000;
 /** Terminal states — chains in these states cannot be resumed or cancelled. */
 const TERMINAL_STATES: readonly WrfcState[] = ['passed', 'failed'];
 
-/** States from which resume is permitted (pending = chain is awaiting retry). */
-const RESUMABLE_STATES: readonly WrfcState[] = ['pending'];
+/**
+ * States from which resume is permitted. These mirror the states
+ * WrfcController.resumeChain() actually recovers from: 'pending' (awaiting
+ * retry / start engineering), 'reviewing' and 'fixing' (re-spawn the
+ * interrupted child), and 'awaiting_gates' (re-run gates). resumeChain no-ops
+ * safely when a child is still running, so offering resume for these states is
+ * always safe — it is exactly the set an operator needs after a restart or a
+ * STALLED chain.
+ */
+const RESUMABLE_STATES: readonly WrfcState[] = ['pending', 'reviewing', 'fixing', 'awaiting_gates'];
 
 // ---------------------------------------------------------------------------
 // Colour palette
 // ---------------------------------------------------------------------------
-const C = {
-  // states
+const C = extendPalette(DEFAULT_PANEL_PALETTE, {
+  // WRFC state-machine colours (domain status -- no shared equivalent)
   passed:     '#22c55e', // green
   failed:     '#ef4444', // red
   reviewing:  '#eab308', // yellow
@@ -47,31 +57,19 @@ const C = {
   pending:    '#6b7280', // grey
   gating:     '#a78bfa', // violet
   committing: '#38bdf8', // sky
+  integrating:'#818cf8', // indigo
 
-  // UI chrome
-  header:     '#94a3b8',
-  headerBold: '#e2e8f0',
-  dim:        '#4b5563',
-  label:      '#64748b',
-  value:      '#cbd5e1',
-  selected:   '#1e40af', // selection bg
-  selectedFg: '#f8fafc',
-  border:     '#334155',
-  spark:      '#38bdf8',
-  sparkLow:   '#ef4444',
-  sparkHigh:  '#22c55e',
+  // Issue-severity ramp (domain -- no shared equivalent)
   issueCrit:  '#ef4444',
   issueMaj:   '#f97316',
   issueMin:   '#eab308',
   issueSug:   '#6b7280',
-  gatePass:   '#22c55e',
-  gateFail:   '#ef4444',
-  // constraint status
-  constraintSat:  '#22c55e', // green — satisfied
-  constraintUnsat:'#ef4444', // red — unsatisfied
-  constraintUnv:  '#4b5563', // grey — unverified (no finding yet)
-  stalled:        '#f59e0b', // amber — stalled / no recent event
-} as const;
+
+  // Selection + divider chrome with no shared equivalent
+  selected:   '#1e40af', // selection bg
+  selectedFg: '#f8fafc',
+  border:     '#334155',
+});
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -99,6 +97,7 @@ export function stateColor(state: WrfcState): string {
     case 'gating':
     case 'awaiting_gates':  return C.gating;
     case 'committing':      return C.committing;
+    case 'integrating':     return C.integrating;
     default:                return C.pending;
   }
 }
@@ -111,6 +110,7 @@ export function stateLabel(state: WrfcState): string {
     case 'gating':         return 'GATE';
     case 'awaiting_gates': return 'WAIT';
     case 'committing':     return 'COMMIT';
+    case 'integrating':    return 'INTG';
     case 'passed':         return 'PASS';
     case 'failed':         return 'FAIL';
     default:               return 'PEND';
@@ -154,10 +154,10 @@ export function constraintStatusMarker(
 ): { tag: string; fg: string; dim: boolean } {
   const finding = findings?.find(f => f.constraintId === constraint.id);
   if (!finding) {
-    return { tag: '[UNV]', fg: C.constraintUnv, dim: true };
+    return { tag: '[UNV]', fg: C.dim, dim: true };
   }
   if (finding.satisfied) {
-    return { tag: '[SAT]', fg: C.constraintSat, dim: false };
+    return { tag: '[SAT]', fg: C.good, dim: false };
   }
   // Unsatisfied — use severity to pick colour and tag text
   const sev = finding.severity ?? 'major';
@@ -334,7 +334,7 @@ export class WrfcPanel extends BasePanel {
               const satisfied = findings ? findings.filter(f => f.satisfied).length : 0;
               const satFg = !findings || findings.length === 0
                 ? DEFAULT_PANEL_PALETTE.dim
-                : satisfied === total ? C.constraintSat : C.constraintUnsat;
+                : satisfied === total ? C.good : C.bad;
               return [
                 [' Constraints ', DEFAULT_PANEL_PALETTE.label],
                 [`${satisfied} sat / ${total} total`, satFg],
@@ -450,7 +450,7 @@ export class WrfcPanel extends BasePanel {
     fg: string,
     stalled = false,
   ): Line[] {
-    const stateCol   = stalled ? C.stalled : stateColor(chain.state);
+    const stateCol   = stalled ? C.warn : stateColor(chain.state);
     const stateTag   = stalled
       ? ` STALLED`
       : ` ${stateLabel(chain.state).padEnd(6)}`;
@@ -483,7 +483,7 @@ export class WrfcPanel extends BasePanel {
     const remaining  = width - usedWidth;
 
     const segments = [
-      { text: prefix,   fg: isSelected ? fg : C.header },
+      { text: prefix,   fg: isSelected ? fg : C.label },
       { text: stateTag, fg: stateCol, bold: true },
       { text: ' ',      fg: '' },
       { text: taskText, fg: isSelected ? fg : C.value },
@@ -498,11 +498,11 @@ export class WrfcPanel extends BasePanel {
         // Determine badge colour
         let badgeFg: string;
         if (!findings || findings.length === 0) {
-          badgeFg = C.constraintUnv;
+          badgeFg = C.dim;
         } else if (satisfied === total) {
-          badgeFg = C.constraintSat;
+          badgeFg = C.good;
         } else if (findings.some(f => !f.satisfied)) {
-          badgeFg = C.constraintUnsat;
+          badgeFg = C.bad;
         } else {
           badgeFg = C.reviewing; // some unverified but none failed
         }
@@ -536,7 +536,7 @@ export class WrfcPanel extends BasePanel {
     if (chain.reviewScores.length > 0) {
       const spark = sparkline(chain.reviewScores);
       const latestScore = chain.reviewScores[chain.reviewScores.length - 1];
-      const sparkColor  = latestScore >= 8 ? C.sparkHigh : latestScore >= 5 ? C.spark : C.sparkLow;
+      const sparkColor  = latestScore >= 8 ? C.good : latestScore >= 5 ? C.info : C.bad;
       lines.push(buildStyledPanelLine(width, [
         { text: `${indent}Scores  `, fg: C.label },
         { text: spark,               fg: sparkColor },
@@ -648,7 +648,7 @@ export class WrfcPanel extends BasePanel {
 
   private renderGateResult(gate: QualityGateResult, width: number, indent: string): Line {
     const icon   = gate.passed ? '✓' : '✕';
-    const iconFg = gate.passed ? C.gatePass : C.gateFail;
+    const iconFg = gate.passed ? C.good : C.bad;
     const dur    = `${gate.durationMs}ms`;
     const nameMax = width - indent.length - 2 - dur.length - 4;
     const name   = truncate(gate.gate, Math.max(8, nameMax));
@@ -740,7 +740,7 @@ export class WrfcPanel extends BasePanel {
       if (hadChains) {
         // Post-init error: the controller was working and now throws.  Surface
         // a faint diagnostic rather than silently preserving stale state.
-        const msg = err instanceof Error ? err.message : String(err);
+        const msg = summarizeError(err);
         this.controllerError = msg;
         console.debug('[WrfcPanel] controller.listChains() error post-init:', msg);
       }
@@ -773,6 +773,8 @@ export class WrfcPanel extends BasePanel {
     if (!chain) return;
     if (!RESUMABLE_STATES.includes(chain.state)) return;
     this.deps.controller.resumeChain(chain.id);
+    // Re-sync so the rows/footer reflect the state resumeChain transitioned to.
+    this.syncFromController();
     this.markDirty();
   }
 

package/src/renderer/agent-detail-modal.ts

@@ -4,7 +4,7 @@ import { ModalFactory } from './modal-factory.ts';
 import type { AgentManager } from '@pellux/goodvibes-sdk/platform/tools';
 import type { AgentMessageBus } from '@pellux/goodvibes-sdk/platform/agents';
 import type { WrfcController } from '@pellux/goodvibes-sdk/platform/agents';
-import { formatDuration } from './modal-utils.ts';
+import { formatElapsed } from '../utils/format-elapsed.ts';
 import { logger } from '@pellux/goodvibes-sdk/platform/utils';
 import { getOverlaySurfaceMetrics, getStableOverlayContentRows } from './overlay-viewport.ts';
 import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
@@ -249,7 +249,7 @@ export function renderAgentDetailModal(
   sections.push({ type: 'text', content: `Model    : ${modelStr}` });
   const isStalled = !MODAL_TERMINAL_STATUSES.has(rec.status) && (now - rec.startedAt) >= MODAL_STALL_THRESHOLD_MS;
   sections.push({ type: 'text', content: `Status   : ${rec.status}${isStalled ? '  [STALLED — 5+ min no activity]' : ''}` });
-  sections.push({ type: 'text', content: `Duration : ${formatDuration(elapsedMs)}` });
+  sections.push({ type: 'text', content: `Duration : ${formatElapsed(elapsedMs)}` });
   sections.push({ type: 'separator' });
 
   // Metrics

package/src/renderer/modal-utils.ts

@@ -2,16 +2,6 @@
  * Shared rendering utilities for modal components.
  */
 
-/** Format elapsed milliseconds as a compact duration string. */
-export function formatDuration(ms: number): string {
-  if (ms < 1000) return `${ms}ms`;
-  const secs = Math.floor(ms / 1000);
-  if (secs < 60) return `${secs}s`;
-  const mins = Math.floor(secs / 60);
-  const remSecs = secs % 60;
-  return `${mins}m${remSecs}s`;
-}
-
 /**
  * Format a Unix millisecond timestamp as YYYY-MM-DD HH:MM.
  * Returns '(unknown)' for falsy timestamps.

package/src/renderer/process-modal.ts

@@ -1,6 +1,6 @@
 import { type Line } from '../types/grid.ts';
 import { ModalFactory } from './modal-factory.ts';
-import { formatDuration } from './modal-utils.ts';
+import { formatElapsed } from '../utils/format-elapsed.ts';
 import type { ProcessManager } from '@pellux/goodvibes-sdk/platform/tools';
 import type { AgentManager, AgentRecord } from '@pellux/goodvibes-sdk/platform/tools';
 import type { WrfcController } from '@pellux/goodvibes-sdk/platform/agents';
@@ -623,7 +623,7 @@ export function renderProcessModal(modal: ProcessModal, width: number, viewportH
       cancelled: '–',
     }[e.status] ?? '•';
     const typeTag = e.type === 'agent' ? '[agent]' : '[exec]';
-    const dur = formatDuration(e.elapsedMs);
+    const dur = formatElapsed(e.elapsedMs);
     const statusStr = e.streamSnippet ? `streaming  ${dur}` : `${e.status}  ${dur}`;
     const suffix = `  ${statusStr}`;
     const treePrefix = e.treePrefix ?? '';

package/src/runtime/bootstrap-command-context.ts

@@ -112,6 +112,7 @@ export type CreateBootstrapCommandContextOptions = {
   activatePlan: (planId: string, task: string) => void;
   completeModelSelectionSideEffect?: () => void;
   sessionLineageTracker?: import('@pellux/goodvibes-sdk/platform/core').SessionLineageTracker;
+  wrfcController?: import('@pellux/goodvibes-sdk/platform/agents').WrfcController;
   componentHealthMonitor: import('@/runtime/index.ts').ComponentHealthMonitor;
 };
 
@@ -164,6 +165,7 @@ export function createBootstrapCommandContext(
     webhookNotifier,
     sessionMemoryStore,
     sessionLineageTracker,
+    wrfcController,
     changeTracker,
     planManager,
     adaptivePlanner,
@@ -219,6 +221,7 @@ export function createBootstrapCommandContext(
     sessionManager,
     sessionMemoryStore,
     sessionLineageTracker,
+    wrfcController,
     changeTracker,
   });
   const provider = createBootstrapCommandProviderSection({

package/src/runtime/bootstrap-command-parts.ts

@@ -107,6 +107,7 @@ export interface BootstrapCommandSectionOptions {
   readonly webhookNotifier?: import('@pellux/goodvibes-sdk/platform/integrations').WebhookNotifier;
   readonly sessionMemoryStore?: import('@pellux/goodvibes-sdk/platform/core').SessionMemoryStore;
   readonly sessionLineageTracker?: import('@pellux/goodvibes-sdk/platform/core').SessionLineageTracker;
+  readonly wrfcController?: import('@pellux/goodvibes-sdk/platform/agents').WrfcController;
   readonly changeTracker?: import('@pellux/goodvibes-sdk/platform/sessions').SessionChangeTracker;
   readonly agentManager?: ShellAgentManagerService;
   readonly modeManager?: ShellModeManagerService;
@@ -299,7 +300,7 @@ export function createBootstrapCommandActions(
 export function createBootstrapCommandSessionSection(
   options: Pick<
     BootstrapCommandSectionOptions,
-    'conversation' | 'runtime' | 'sessionManager' | 'sessionMemoryStore' | 'sessionLineageTracker' | 'changeTracker'
+    'conversation' | 'runtime' | 'sessionManager' | 'sessionMemoryStore' | 'sessionLineageTracker' | 'wrfcController' | 'changeTracker'
   >,
 ): BootstrapCommandSessionSection {
   return {
@@ -308,6 +309,7 @@ export function createBootstrapCommandSessionSection(
     sessionManager: options.sessionManager,
     sessionMemoryStore: options.sessionMemoryStore,
     sessionLineageTracker: options.sessionLineageTracker,
+    wrfcController: options.wrfcController,
     changeTracker: options.changeTracker,
   };
 }

package/src/runtime/bootstrap-core.ts

@@ -399,50 +399,50 @@ export async function initializeBootstrapCore(
   });
 
   const renderRequestRef = { value: (): void => {} };
-  // R1: Coalescing render scheduler — collapses N same-microtask requestRender() calls into 1.
-  // Also enforces a 16ms minimum interval to cap at ~60fps during streaming.
+  // R1: Coalescing render scheduler — collapses N requestRender() calls into 1
+  // and enforces a 16ms minimum interval to cap repaints at ~60fps.
+  //
+  // renderScheduled stays set for the ENTIRE window (until run() executes), so
+  // requestRender() calls that arrive on later event-loop ticks within the same
+  // 16ms window are coalesced into the one already-pending tail render instead
+  // of each queuing their own setTimeout. (The streaming hot path drives its own
+  // direct repaints and does not flow through this scheduler.)
   let renderScheduled = false;
   let lastRenderTime = 0;
   const RENDER_INTERVAL_MS = 16;
+  // run() performs the actual render. It clears renderScheduled FIRST — even if
+  // the render callback throws — otherwise a single render exception would wedge
+  // the entire TUI (no future requestRender() call would schedule anything). The
+  // renderer is expected to surface failures via its own error path; we log at
+  // error so the next requestRender() can still reschedule.
+  const run = (): void => {
+    renderScheduled = false;
+    lastRenderTime = Date.now();
+    try {
+      renderRequestRef.value();
+    } catch (err) {
+      logger.error('Render threw; next requestRender will reschedule', { error: String(err) });
+    }
+  };
   const requestRender = (): void => {
     if (renderScheduled) return;
     renderScheduled = true;
     setImmediate(() => {
-      // Error Handling: the scheduler flag MUST be cleared even if the render
-      // callback throws; otherwise a single render exception would wedge the
-      // entire TUI (no future requestRender() call would schedule anything).
-      renderScheduled = false;
-      const now = Date.now();
-      const elapsed = now - lastRenderTime;
-      try {
-        if (elapsed < RENDER_INTERVAL_MS) {
-          // Too soon — debounce to the tail of the current 16ms window
-          const delay = RENDER_INTERVAL_MS - elapsed;
-          setTimeout(() => {
-            try {
-              lastRenderTime = Date.now();
-              renderRequestRef.value();
-            } catch (err) {
-              // Throttled-render error: swallow but log at error so the next
-              // requestRender() call can still schedule. The renderer itself
-              // is expected to surface failures via its own error path.
-              logger.error('Throttled render threw; next requestRender will reschedule', { error: String(err) });
-            }
-          }, delay);
-        } else {
-          lastRenderTime = now;
-          renderRequestRef.value();
-        }
-      } catch (err) {
-        logger.error('Immediate render threw; next requestRender will reschedule', { error: String(err) });
+      const elapsed = Date.now() - lastRenderTime;
+      if (elapsed < RENDER_INTERVAL_MS) {
+        // Too soon — debounce to the tail of the current 16ms window. The flag
+        // stays set until run() fires, so window-local requests coalesce here.
+        setTimeout(run, RENDER_INTERVAL_MS - elapsed);
+      } else {
+        run();
       }
     });
   };
   const permissionPromptRef = {
     requestPermission: (async () => ({ approved: false, remember: false })) as PermissionRequestHandler,
   };
-  void approvalBroker.start();
-  void sharedSessionBroker.start();
+  approvalBroker.start().catch((err) => logger.warn('approval broker start failed at bootstrap', { err }));
+  sharedSessionBroker.start().catch((err) => logger.warn('shared session broker start failed at bootstrap', { err }));
   const runtimeSessionIdRef = { value: userSessionId };
   const wrfcBuffer = new WrfcPreRouterBuffer();
   // Smart ref: setting .value auto-flushes the pre-router buffer so events

package/src/runtime/bootstrap-shell.ts

@@ -240,6 +240,7 @@ export function createBootstrapShell(options: BootstrapShellOptions): BootstrapS
     webhookNotifier: services.webhookNotifier,
     sessionMemoryStore: services.sessionMemoryStore,
     sessionLineageTracker: services.sessionLineageTracker,
+    wrfcController: services.wrfcController,
     changeTracker: services.sessionChangeTracker,
     planManager: services.planManager,
     adaptivePlanner: services.adaptivePlanner,

package/src/runtime/onboarding/apply.ts

@@ -17,6 +17,7 @@ import type {
   OnboardingApplyRequest,
   OnboardingApplyResult,
 } from './types.ts';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
 
 function getNow(deps: Pick<OnboardingApplyDependencies, 'clock'>): number {
   return deps.clock?.() ?? Date.now();
@@ -116,7 +117,7 @@ async function runRollbacks(rollbacks: readonly RollbackAction[]): Promise<reado
     try {
       await rollback();
     } catch (error) {
-      errors.push(error instanceof Error ? error.message : String(error));
+      errors.push(summarizeError(error));
     }
   }
   return errors;
@@ -523,7 +524,7 @@ function prevalidateApplyRequest(
     } catch (error) {
       errors.push({
         kind: operation.kind,
-        message: error instanceof Error ? error.message : String(error),
+        message: summarizeError(error),
       });
     }
   }
@@ -595,7 +596,7 @@ export async function applyOnboardingRequest(
         errors.push({
           kind: operation.kind,
           message: [
-            error instanceof Error ? error.message : String(error),
+            summarizeError(error),
             ...rollbackErrors.map((rollbackError) => `rollback: ${rollbackError}`),
           ].join('; '),
         });

package/src/runtime/onboarding/snapshot.ts

@@ -14,6 +14,7 @@ import type {
   OnboardingSnapshotState,
   OnboardingSurfaceRecord,
 } from './types.ts';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
 
 function sortUnique(values: readonly string[]): string[] {
   return [...new Set(values)].sort((left, right) => left.localeCompare(right));
@@ -100,7 +101,7 @@ async function buildServicesSnapshot(
       issues: [
         {
           area: 'services',
-          message: error instanceof Error ? error.message : String(error),
+          message: summarizeError(error),
         },
       ],
     };
@@ -147,7 +148,7 @@ async function buildServicesSnapshot(
         } satisfies OnboardingServiceState,
         issue: {
           area: 'services',
-          message: `${name}: ${error instanceof Error ? error.message : String(error)}`,
+          message: `${name}: ${summarizeError(error)}`,
         } satisfies OnboardingSnapshotCollectionIssue,
       };
     }
@@ -244,7 +245,7 @@ async function loadOptionalSnapshot<T>(
       value: fallback,
       issue: {
         area,
-        message: error instanceof Error ? error.message : String(error),
+        message: summarizeError(error),
       },
     };
   }

package/src/runtime/process-lifecycle.ts

@@ -0,0 +1,195 @@
+/**
+ * Process-lifecycle wiring for the TUI shell.
+ *
+ * Extracted from main() to keep the entrypoint under the architecture line-count
+ * gate. `installProcessLifecycle` builds the terminal-restoring crash/termination
+ * handlers and the graceful `exitApp` teardown, then returns them so main() can
+ * register them on the exact same process/stdin/stdout listeners it used before.
+ *
+ * Behavior is identical to the previous inline version: the synchronous terminal
+ * restore runs BEFORE the (possibly slow) async shutdown, the shutdown races a 3s
+ * hard timeout, the recovery file is deleted only when the durable save completed,
+ * signal exit codes are preserved (SIGHUP -> 129, otherwise 143; uncaught -> 1;
+ * exitApp -> 0), and the `exiting`/`terminalRestored` reentrancy guards are kept.
+ *
+ * Some captured values are late-bound or mutable in main(): the InputHandler, the
+ * render closure, and the terminal output guard are constructed AFTER this factory
+ * runs (injected as thunks), while `recoveryInterval` and `stopSpokenOutputForExit`
+ * are assigned later and read at exit time (injected as getters/setter). The
+ * `unsubs` registry is shared by reference and drained on exit.
+ */
+import { logger, summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
+import { formatUserFacingErrorLine } from '../core/format-user-error.ts';
+import { allowTerminalWrite } from './terminal-output-guard.ts';
+import { buildPersistedSessionContext, deleteRecoveryFile } from '@/runtime/index.ts';
+import type { BootstrapContext } from './bootstrap.ts';
+import type { InputHandler } from '../input/handler.ts';
+import type { ConversationMessageSnapshot } from '../core/conversation.ts';
+
+/** ANSI escape sequences used by the synchronous terminal restore. */
+export interface ProcessLifecycleAnsi {
+  readonly CLEAR_SCREEN: string;
+  readonly ALT_SCREEN_EXIT: string;
+  readonly PASTE_DISABLE: string;
+  readonly KEYBOARD_EXT_DISABLE: string;
+  readonly MOUSE_DISABLE: string;
+  readonly CURSOR_SHOW: string;
+}
+
+export interface ProcessLifecycleDeps {
+  readonly stdin: NodeJS.ReadStream;
+  readonly stdout: NodeJS.WriteStream;
+  readonly ctx: BootstrapContext;
+  /** Mirrors cli.flags.noAltScreen: whether the alt screen is exited on restore. */
+  readonly noAltScreen: boolean;
+  readonly ansi: ProcessLifecycleAnsi;
+  /** Late-bound: the InputHandler is constructed after this factory runs. */
+  readonly getInput: () => InputHandler;
+  /** Late-bound: the render closure is defined after this factory runs. */
+  readonly render: () => void;
+  /** Late-bound: the terminal output guard is installed after this factory runs. */
+  readonly getTerminalOutputGuard: () => { readonly dispose: () => void };
+  readonly getPromptContentWidth: () => number;
+  readonly buildSessionContinuityHints: () => Parameters<typeof buildPersistedSessionContext>[2];
+  /** Teardown registry shared with main(); drained on exit. */
+  readonly unsubs: ReadonlyArray<() => void>;
+  readonly getRecoveryInterval: () => ReturnType<typeof setInterval> | null;
+  readonly setRecoveryInterval: (value: ReturnType<typeof setInterval> | null) => void;
+  readonly getStopSpokenOutputForExit: () => (() => void) | null;
+}
+
+export interface ProcessLifecycleHandlers {
+  readonly exitApp: () => Promise<void>;
+  readonly restoreTerminal: () => void;
+  readonly resizeHandler: () => void;
+  readonly sigintHandler: () => void;
+  readonly unhandledRejectionHandler: (reason: unknown) => void;
+  readonly uncaughtExceptionHandler: (err: Error) => void;
+  readonly terminationSignalHandler: (signal: NodeJS.Signals) => void;
+  readonly exitListener: () => void;
+}
+
+export function installProcessLifecycle(deps: ProcessLifecycleDeps): ProcessLifecycleHandlers {
+  const {
+    stdin,
+    stdout,
+    ctx,
+    noAltScreen,
+    ansi,
+    getInput,
+    render,
+    getTerminalOutputGuard,
+    getPromptContentWidth,
+    buildSessionContinuityHints,
+    unsubs,
+    getRecoveryInterval,
+    setRecoveryInterval,
+    getStopSpokenOutputForExit,
+  } = deps;
+
+  const sigintHandler = (): void => getInput().feed('\x03');
+  let _unhandledRejectionCount = 0;
+  let _unhandledRejectionWindowStart = Date.now();
+  const unhandledRejectionHandler = (reason: unknown): void => {
+    const now = Date.now();
+    if (now - _unhandledRejectionWindowStart > 10000) {
+      _unhandledRejectionCount = 0;
+      _unhandledRejectionWindowStart = now;
+    }
+    _unhandledRejectionCount++;
+    const msg = summarizeError(reason);
+    if (_unhandledRejectionCount > 3) {
+      logger.error('CRITICAL: cascading unhandled rejections — consider restarting', {
+        count: _unhandledRejectionCount,
+        windowMs: now - _unhandledRejectionWindowStart,
+        error: String(reason),
+      });
+      ctx.systemMessageRouter.high(
+        `[Critical] Multiple errors detected (${_unhandledRejectionCount} in 10s). If the issue persists, please restart. Latest: ${msg}`
+      );
+    } else {
+      const formatted = formatUserFacingErrorLine(reason);
+      ctx.systemMessageRouter.high(`[Error] ${formatted}`);
+      logger.error('unhandledRejection', { error: String(reason) });
+    }
+    render();
+  };
+  const resizeHandler = (): void => {
+    getInput().setContentWidth(getPromptContentWidth());
+    ctx.compositor.resetDiff();
+    render();
+  };
+
+  let terminalRestored = false;
+  // Idempotent, synchronous-only terminal restore. Safe to call from process.on('exit'),
+  // signal handlers, uncaughtException, and exitApp. Disposes the output guard FIRST so a
+  // crash stack reaches the real stderr instead of being suppressed by the guard.
+  const restoreTerminal = (): void => {
+    if (terminalRestored) return;
+    terminalRestored = true;
+    const exitScreen = noAltScreen ? ansi.CLEAR_SCREEN : ansi.CLEAR_SCREEN + ansi.ALT_SCREEN_EXIT;
+    allowTerminalWrite(() => stdout.write(ansi.PASTE_DISABLE + ansi.KEYBOARD_EXT_DISABLE + ansi.MOUSE_DISABLE + ansi.CURSOR_SHOW + exitScreen));
+    getTerminalOutputGuard().dispose();
+    try { stdin.setRawMode(false); } catch { /* stdin may not be a TTY */ }
+  };
+
+  const uncaughtExceptionHandler = (err: Error): void => {
+    restoreTerminal();
+    logger.error('uncaughtException — terminal restored, exiting', { error: summarizeError(err) });
+    process.exit(1);
+  };
+  const terminationSignalHandler = (signal: NodeJS.Signals): void => {
+    restoreTerminal();
+    logger.error(`Received ${signal} — terminal restored, exiting`, {});
+    process.exit(signal === 'SIGHUP' ? 129 : 143);
+  };
+  const exitListener = (): void => { restoreTerminal(); };
+
+  let exiting = false;
+  const exitApp = async (): Promise<void> => {
+    // Reentrancy guard: a second /exit or keypress during the awaited shutdown below
+    // must not re-run teardown or double-fire ctx.shutdown.
+    if (exiting) return;
+    exiting = true;
+    getStopSpokenOutputForExit()?.();
+    unsubs.forEach(fn => fn());
+    const interval = getRecoveryInterval();
+    if (interval !== null) { clearInterval(interval); setRecoveryInterval(null); }
+    stdin.removeAllListeners('data');
+    stdout.removeListener('resize', resizeHandler);
+    process.removeListener('SIGINT', sigintHandler);
+    process.removeListener('unhandledRejection', unhandledRejectionHandler);
+    // Restore the terminal synchronously BEFORE the (possibly slow) async shutdown so the
+    // user is not left staring at a frozen alt screen while we drain and persist.
+    restoreTerminal();
+    const snapshot = ctx.conversation.toJSON() as { messages: Array<ConversationMessageSnapshot>; timestamp?: number };
+    let shutdownOk = false;
+    try {
+      // Race the graceful shutdown against a hard timeout — externalServices.stop() can hang
+      // and we must still exit; deferredStartup.drain only budgets 100ms internally.
+      await Promise.race([
+        ctx.shutdown({ ...snapshot, ...buildPersistedSessionContext(snapshot.messages, ctx.conversation.getTitleSource(), buildSessionContinuityHints()) }).then(() => { shutdownOk = true; }),
+        new Promise<void>((resolve) => setTimeout(resolve, 3000)),
+      ]);
+    } catch (err) {
+      logger.debug('ctx.shutdown error during exitApp (non-fatal)', { error: summarizeError(err) });
+    }
+    // Only remove the recovery fallback once the durable shutdown save actually completed,
+    // so an interrupted or timed-out shutdown leaves the snapshot for the next launch.
+    if (shutdownOk) {
+      deleteRecoveryFile({ homeDirectory: ctx.services.homeDirectory });
+    }
+    process.exit(0);
+  };
+
+  return {
+    exitApp,
+    restoreTerminal,
+    resizeHandler,
+    sigintHandler,
+    unhandledRejectionHandler,
+    uncaughtExceptionHandler,
+    terminationSignalHandler,
+    exitListener,
+  };
+}