@jmoyers/harness 0.1.0

package/src/services/runtime-workspace-observed-events.ts

@@ -0,0 +1,190 @@
+interface WorkspaceObservedReduction {
+  readonly changed: boolean;
+  readonly removedConversationIds: readonly string[];
+  readonly removedDirectoryIds: readonly string[];
+}
+
+interface WorkspaceObservedReducer<TObservedEvent> {
+  apply(observed: TObservedEvent): WorkspaceObservedReduction;
+}
+
+interface RuntimeWorkspaceStateLike {
+  leftNavSelection:
+    | {
+        kind: 'home';
+      }
+    | {
+        kind: 'project';
+        directoryId: string;
+      }
+    | {
+        kind: 'repository';
+        repositoryId: string;
+      }
+    | {
+        kind: 'conversation';
+        sessionId: string;
+      };
+  conversationTitleEdit: {
+    conversationId: string;
+  } | null;
+  projectPaneSnapshot: {
+    directoryId: string;
+  } | null;
+  projectPaneScrollTop: number;
+  activeDirectoryId: string | null;
+  selectLeftNavConversation(sessionId: string): void;
+}
+
+interface RuntimeWorkspaceObservedEventsOptions<TObservedEvent> {
+  readonly reducer: WorkspaceObservedReducer<TObservedEvent>;
+  readonly workspace: RuntimeWorkspaceStateLike;
+  readonly orderedConversationIds: () => readonly string[];
+  readonly conversationDirectoryId: (sessionId: string) => string | null;
+  readonly hasConversation: (sessionId: string) => boolean;
+  readonly getActiveConversationId: () => string | null;
+  readonly setActiveConversationId: (sessionId: string | null) => void;
+  readonly hasDirectory: (directoryId: string) => boolean;
+  readonly resolveActiveDirectoryId: () => string | null;
+  readonly unsubscribeConversationEvents: (sessionId: string) => Promise<void>;
+  readonly stopConversationTitleEdit: (persistPending: boolean) => void;
+  readonly enterProjectPane: (directoryId: string) => void;
+  readonly enterHomePane: () => void;
+  readonly queueControlPlaneOp: (task: () => Promise<void>, label: string) => void;
+  readonly activateConversation: (sessionId: string) => Promise<void>;
+  readonly markDirty: () => void;
+}
+
+export class RuntimeWorkspaceObservedEvents<TObservedEvent> {
+  constructor(private readonly options: RuntimeWorkspaceObservedEventsOptions<TObservedEvent>) {}
+
+  apply(observed: TObservedEvent): void {
+    const activeConversationIdBefore = this.options.getActiveConversationId();
+    const leftNavConversationIdBefore =
+      this.options.workspace.leftNavSelection.kind === 'conversation'
+        ? this.options.workspace.leftNavSelection.sessionId
+        : null;
+    const previousConversationDirectoryById = new Map<string, string | null>();
+    for (const sessionId of this.options.orderedConversationIds()) {
+      previousConversationDirectoryById.set(
+        sessionId,
+        this.options.conversationDirectoryId(sessionId),
+      );
+    }
+
+    const reduced = this.options.reducer.apply(observed);
+    if (!reduced.changed) {
+      return;
+    }
+
+    for (const sessionId of reduced.removedConversationIds) {
+      void this.options.unsubscribeConversationEvents(sessionId);
+      if (this.options.workspace.conversationTitleEdit?.conversationId === sessionId) {
+        this.options.stopConversationTitleEdit(false);
+      }
+    }
+
+    for (const directoryId of reduced.removedDirectoryIds) {
+      if (this.options.workspace.projectPaneSnapshot?.directoryId === directoryId) {
+        this.options.workspace.projectPaneSnapshot = null;
+        this.options.workspace.projectPaneScrollTop = 0;
+      }
+    }
+
+    if (
+      this.options.workspace.activeDirectoryId !== null &&
+      !this.options.hasDirectory(this.options.workspace.activeDirectoryId)
+    ) {
+      this.options.workspace.activeDirectoryId = this.options.resolveActiveDirectoryId();
+    }
+
+    const removedConversationIdSet = new Set(reduced.removedConversationIds);
+    const activateFallbackConversation = (
+      preferredDirectoryId: string | null,
+      label: string,
+    ): boolean => {
+      const ordered = this.options.orderedConversationIds();
+      const fallbackConversationId =
+        (preferredDirectoryId === null
+          ? null
+          : (ordered.find(
+              (sessionId) =>
+                this.options.conversationDirectoryId(sessionId) === preferredDirectoryId,
+            ) ?? null)) ??
+        ordered[0] ??
+        null;
+      if (fallbackConversationId === null) {
+        return false;
+      }
+      this.options.queueControlPlaneOp(async () => {
+        await this.options.activateConversation(fallbackConversationId);
+      }, label);
+      return true;
+    };
+    const fallbackToDirectoryOrHome = (): void => {
+      const fallbackDirectoryId = this.options.resolveActiveDirectoryId();
+      if (fallbackDirectoryId !== null) {
+        this.options.enterProjectPane(fallbackDirectoryId);
+        this.options.markDirty();
+        return;
+      }
+      this.options.enterHomePane();
+    };
+
+    if (
+      activeConversationIdBefore !== null &&
+      removedConversationIdSet.has(activeConversationIdBefore)
+    ) {
+      this.options.setActiveConversationId(null);
+      const preferredDirectoryId =
+        previousConversationDirectoryById.get(activeConversationIdBefore) ?? null;
+      if (
+        !activateFallbackConversation(preferredDirectoryId, 'observed-active-conversation-removed')
+      ) {
+        fallbackToDirectoryOrHome();
+      }
+      this.options.markDirty();
+      return;
+    }
+
+    if (
+      leftNavConversationIdBefore !== null &&
+      removedConversationIdSet.has(leftNavConversationIdBefore)
+    ) {
+      const currentActiveId = this.options.getActiveConversationId();
+      if (currentActiveId !== null && this.options.hasConversation(currentActiveId)) {
+        this.options.workspace.selectLeftNavConversation(currentActiveId);
+        this.options.markDirty();
+        return;
+      }
+      const preferredDirectoryId =
+        previousConversationDirectoryById.get(leftNavConversationIdBefore) ?? null;
+      if (
+        !activateFallbackConversation(
+          preferredDirectoryId,
+          'observed-selected-conversation-removed',
+        )
+      ) {
+        fallbackToDirectoryOrHome();
+      }
+      this.options.markDirty();
+      return;
+    }
+
+    if (
+      this.options.workspace.leftNavSelection.kind === 'project' &&
+      !this.options.hasDirectory(this.options.workspace.leftNavSelection.directoryId)
+    ) {
+      const fallbackDirectoryId = this.options.resolveActiveDirectoryId();
+      if (fallbackDirectoryId !== null) {
+        this.options.enterProjectPane(fallbackDirectoryId);
+      } else {
+        this.options.enterHomePane();
+      }
+      this.options.markDirty();
+      return;
+    }
+
+    this.options.markDirty();
+  }
+}

package/src/services/session-projection-instrumentation.ts

@@ -0,0 +1,190 @@
+import type { ControlPlaneKeyEvent } from '../control-plane/codex-session-stream.ts';
+import { buildSelectorIndexEntries } from '../mux/selector-index.ts';
+import {
+  compactDebugText,
+  conversationSummary,
+  type ConversationState,
+} from '../mux/live-mux/conversation-state.ts';
+import { projectWorkspaceRailConversation } from '../mux/workspace-rail-model.ts';
+
+type PerfAttrs = Record<string, boolean | number | string>;
+
+interface ProcessUsageSample {
+  readonly cpuPercent: number | null;
+  readonly memoryMb: number | null;
+}
+
+interface SelectorIndexDirectory {
+  readonly directoryId: string;
+}
+
+interface ConversationProjectionSnapshot {
+  readonly status: string;
+  readonly glyph: string;
+  readonly detailText: string;
+}
+
+interface SessionProjectionTransition {
+  readonly sessionId: string;
+  readonly eventType: ControlPlaneKeyEvent['type'];
+  readonly cursor: number;
+  readonly statusFrom: string;
+  readonly statusTo: string;
+  readonly glyphFrom: string;
+  readonly glyphTo: string;
+  readonly detailFrom: string;
+  readonly detailTo: string;
+  readonly source: string;
+  readonly eventName: string;
+  readonly summary: string;
+}
+
+interface SessionProjectionInstrumentationOptions {
+  readonly getProcessUsageSample: (sessionId: string) => ProcessUsageSample | undefined;
+  readonly recordPerfEvent: (name: string, attrs: PerfAttrs) => void;
+  readonly onTransition?: (transition: SessionProjectionTransition) => void;
+  readonly nowMs?: () => number;
+}
+
+export class SessionProjectionInstrumentation {
+  private readonly selectorIndexBySessionId = new Map<
+    string,
+    {
+      selectorIndex: number;
+      directoryIndex: number;
+      directoryId: string;
+    }
+  >();
+  private lastSelectorSnapshotHash: string | null = null;
+  private selectorSnapshotVersion = 0;
+  private readonly nowMs: () => number;
+
+  constructor(private readonly options: SessionProjectionInstrumentationOptions) {
+    this.nowMs = options.nowMs ?? Date.now;
+  }
+
+  snapshotForConversation(conversation: ConversationState): ConversationProjectionSnapshot {
+    const projected = projectWorkspaceRailConversation(
+      {
+        ...conversationSummary(conversation),
+        directoryKey: conversation.directoryId ?? 'directory-missing',
+        title: conversation.title,
+        agentLabel: conversation.agentType,
+        cpuPercent: this.options.getProcessUsageSample(conversation.sessionId)?.cpuPercent ?? null,
+        memoryMb: this.options.getProcessUsageSample(conversation.sessionId)?.memoryMb ?? null,
+        statusModel: conversation.statusModel,
+        controller: conversation.controller,
+      },
+      {
+        nowMs: this.nowMs(),
+      },
+    );
+    return {
+      status: projected.status,
+      glyph: projected.glyph,
+      detailText: compactDebugText(projected.detailText),
+    };
+  }
+
+  refreshSelectorSnapshot(
+    reason: string,
+    directories: ReadonlyMap<string, SelectorIndexDirectory>,
+    conversations: ReadonlyMap<string, ConversationState>,
+    orderedIds: readonly string[],
+  ): void {
+    const entries = buildSelectorIndexEntries(directories, conversations, orderedIds);
+    const hash = entries
+      .map(
+        (entry) =>
+          `${entry.selectorIndex}:${entry.directoryId}:${entry.sessionId}:${entry.directoryIndex}:${entry.title}:${entry.agentType}`,
+      )
+      .join('|');
+    if (hash === this.lastSelectorSnapshotHash) {
+      return;
+    }
+    this.lastSelectorSnapshotHash = hash;
+    this.selectorSnapshotVersion += 1;
+    this.selectorIndexBySessionId.clear();
+    for (const entry of entries) {
+      this.selectorIndexBySessionId.set(entry.sessionId, {
+        selectorIndex: entry.selectorIndex,
+        directoryIndex: entry.directoryIndex,
+        directoryId: entry.directoryId,
+      });
+    }
+    this.options.recordPerfEvent('mux.selector.snapshot', {
+      reason: compactDebugText(reason),
+      version: this.selectorSnapshotVersion,
+      count: entries.length,
+    });
+    for (const entry of entries) {
+      this.options.recordPerfEvent('mux.selector.entry', {
+        version: this.selectorSnapshotVersion,
+        index: entry.selectorIndex,
+        directoryIndex: entry.directoryIndex,
+        sessionId: entry.sessionId,
+        directoryId: entry.directoryId,
+        title: compactDebugText(entry.title),
+        agentType: entry.agentType,
+      });
+    }
+  }
+
+  recordTransition(
+    event: ControlPlaneKeyEvent,
+    before: ConversationProjectionSnapshot | null,
+    conversation: ConversationState,
+  ): void {
+    const after = this.snapshotForConversation(conversation);
+    if (this.projectionSnapshotEqual(before, after)) {
+      return;
+    }
+    const selectorEntry = this.selectorIndexBySessionId.get(conversation.sessionId);
+    let source = '';
+    let eventName = '';
+    let summary: string | null = null;
+    if (event.type === 'session-telemetry') {
+      source = event.keyEvent.source;
+      eventName = event.keyEvent.eventName ?? '';
+      summary = event.keyEvent.summary;
+    } else if (event.type === 'session-status') {
+      source = event.telemetry?.source ?? '';
+      eventName = event.telemetry?.eventName ?? '';
+      summary = event.telemetry?.summary ?? null;
+    }
+    const transition: SessionProjectionTransition = {
+      sessionId: conversation.sessionId,
+      eventType: event.type,
+      cursor: event.cursor,
+      statusFrom: before?.status ?? '',
+      statusTo: after.status,
+      glyphFrom: before?.glyph ?? '',
+      glyphTo: after.glyph,
+      detailFrom: before?.detailText ?? '',
+      detailTo: after.detailText,
+      source,
+      eventName,
+      summary: compactDebugText(summary),
+    };
+    this.options.recordPerfEvent('mux.session-projection.transition', {
+      ...transition,
+      selectorIndex: selectorEntry?.selectorIndex ?? 0,
+      directoryIndex: selectorEntry?.directoryIndex ?? 0,
+    });
+    this.options.onTransition?.(transition);
+  }
+
+  private projectionSnapshotEqual(
+    left: ConversationProjectionSnapshot | null,
+    right: ConversationProjectionSnapshot,
+  ): boolean {
+    if (left === null) {
+      return false;
+    }
+    return (
+      left.status === right.status &&
+      left.glyph === right.glyph &&
+      left.detailText === right.detailText
+    );
+  }
+}

package/src/services/startup-background-probe.ts

@@ -0,0 +1,91 @@
+type PerfAttrs = Record<string, boolean | number | string>;
+
+type UsageRefreshReason = 'startup' | 'interval';
+
+type IntervalHandle = ReturnType<typeof setInterval>;
+type TimeoutHandle = ReturnType<typeof setTimeout>;
+
+interface StartupBackgroundProbeOptions {
+  readonly enabled: boolean;
+  readonly maxWaitMs: number;
+  readonly isShuttingDown: () => boolean;
+  readonly waitForSettled: () => Promise<void>;
+  readonly settledObserved: () => boolean;
+  readonly refreshProcessUsage: (reason: UsageRefreshReason) => void | Promise<void>;
+  readonly recordPerfEvent: (name: string, attrs: PerfAttrs) => void;
+  readonly setIntervalFn?: (handler: () => void, ms: number) => IntervalHandle;
+  readonly clearIntervalFn?: (handle: IntervalHandle) => void;
+  readonly setTimeoutFn?: (handler: () => void, ms: number) => TimeoutHandle;
+  readonly clearTimeoutFn?: (handle: TimeoutHandle) => void;
+}
+
+export class StartupBackgroundProbeService {
+  private readonly setIntervalFn: (handler: () => void, ms: number) => IntervalHandle;
+  private readonly clearIntervalFn: (handle: IntervalHandle) => void;
+  private readonly setTimeoutFn: (handler: () => void, ms: number) => TimeoutHandle;
+  private readonly clearTimeoutFn: (handle: TimeoutHandle) => void;
+  private started = false;
+  private intervalHandle: IntervalHandle | null = null;
+
+  constructor(private readonly options: StartupBackgroundProbeOptions) {
+    this.setIntervalFn = options.setIntervalFn ?? setInterval;
+    this.clearIntervalFn = options.clearIntervalFn ?? clearInterval;
+    this.setTimeoutFn = options.setTimeoutFn ?? setTimeout;
+    this.clearTimeoutFn = options.clearTimeoutFn ?? clearTimeout;
+  }
+
+  recordWaitPhase(): void {
+    this.options.recordPerfEvent('mux.startup.background-probes.wait', {
+      maxWaitMs: this.options.maxWaitMs,
+      enabled: this.options.enabled ? 1 : 0,
+    });
+    if (!this.options.enabled) {
+      this.options.recordPerfEvent('mux.startup.background-probes.skipped', {
+        reason: 'disabled',
+      });
+    }
+  }
+
+  async startWhenSettled(): Promise<void> {
+    if (!this.options.enabled) {
+      return;
+    }
+    let timedOut = false;
+    let timeoutHandle: TimeoutHandle | null = null;
+    await Promise.race([
+      this.options.waitForSettled(),
+      new Promise<void>((resolve) => {
+        timeoutHandle = this.setTimeoutFn(() => {
+          timedOut = true;
+          resolve();
+        }, this.options.maxWaitMs);
+      }),
+    ]);
+    if (timeoutHandle !== null) {
+      this.clearTimeoutFn(timeoutHandle);
+    }
+    this.maybeStart(timedOut);
+  }
+
+  stop(): void {
+    if (this.intervalHandle !== null) {
+      this.clearIntervalFn(this.intervalHandle);
+      this.intervalHandle = null;
+    }
+  }
+
+  private maybeStart(timedOut: boolean): void {
+    if (this.options.isShuttingDown() || this.started || !this.options.enabled) {
+      return;
+    }
+    this.started = true;
+    this.options.recordPerfEvent('mux.startup.background-probes.begin', {
+      timedOut,
+      settledObserved: this.options.settledObserved(),
+    });
+    void this.options.refreshProcessUsage('startup');
+    this.intervalHandle = this.setIntervalFn(() => {
+      void this.options.refreshProcessUsage('interval');
+    }, 1000);
+  }
+}

package/src/services/startup-background-resume.ts

@@ -0,0 +1,65 @@
+type PerfAttrs = Record<string, boolean | number | string>;
+type TimeoutHandle = ReturnType<typeof setTimeout>;
+
+interface StartupBackgroundResumeOptions {
+  readonly enabled: boolean;
+  readonly maxWaitMs: number;
+  readonly waitForSettled: () => Promise<void>;
+  readonly settledObserved: () => boolean;
+  readonly queuePersistedConversationsInBackground: (initialActiveId: string | null) => number;
+  readonly recordPerfEvent: (name: string, attrs: PerfAttrs) => void;
+  readonly setTimeoutFn?: (handler: () => void, ms: number) => TimeoutHandle;
+  readonly clearTimeoutFn?: (handle: TimeoutHandle) => void;
+}
+
+export class StartupBackgroundResumeService {
+  private readonly setTimeoutFn: (handler: () => void, ms: number) => TimeoutHandle;
+  private readonly clearTimeoutFn: (handle: TimeoutHandle) => void;
+
+  constructor(private readonly options: StartupBackgroundResumeOptions) {
+    this.setTimeoutFn = options.setTimeoutFn ?? setTimeout;
+    this.clearTimeoutFn = options.clearTimeoutFn ?? clearTimeout;
+  }
+
+  async run(initialActiveId: string | null): Promise<void> {
+    const sessionId = initialActiveId ?? 'none';
+    this.options.recordPerfEvent('mux.startup.background-start.wait', {
+      sessionId,
+      maxWaitMs: this.options.maxWaitMs,
+      enabled: this.options.enabled ? 1 : 0,
+    });
+    if (!this.options.enabled) {
+      this.options.recordPerfEvent('mux.startup.background-start.skipped', {
+        sessionId,
+        reason: 'disabled',
+      });
+      return;
+    }
+
+    let timedOut = false;
+    let timeoutHandle: TimeoutHandle | null = null;
+    await Promise.race([
+      this.options.waitForSettled(),
+      new Promise<void>((resolve) => {
+        timeoutHandle = this.setTimeoutFn(() => {
+          timedOut = true;
+          resolve();
+        }, this.options.maxWaitMs);
+      }),
+    ]);
+    if (timeoutHandle !== null) {
+      this.clearTimeoutFn(timeoutHandle);
+    }
+
+    this.options.recordPerfEvent('mux.startup.background-start.begin', {
+      sessionId,
+      timedOut,
+      settledObserved: this.options.settledObserved(),
+    });
+    const queued = this.options.queuePersistedConversationsInBackground(initialActiveId);
+    this.options.recordPerfEvent('mux.startup.background-start.queued', {
+      sessionId,
+      queued,
+    });
+  }
+}

package/src/services/startup-orchestrator.ts

@@ -0,0 +1,166 @@
+import type { ConversationState } from '../mux/live-mux/conversation-state.ts';
+import { StartupSequencer } from '../mux/startup-sequencer.ts';
+import { StartupBackgroundProbeService } from './startup-background-probe.ts';
+import { StartupBackgroundResumeService } from './startup-background-resume.ts';
+import { StartupOutputTracker } from './startup-output-tracker.ts';
+import { StartupPaintTracker } from './startup-paint-tracker.ts';
+import { StartupSettledGate } from './startup-settled-gate.ts';
+import { StartupShutdownService } from './startup-shutdown.ts';
+import { StartupSpanTracker } from './startup-span-tracker.ts';
+import { StartupVisibility } from './startup-visibility.ts';
+
+type PerfAttrs = Record<string, boolean | number | string>;
+
+interface PerfSpanLike {
+  end(attrs?: PerfAttrs): void;
+}
+
+interface StartupOrchestratorOptions {
+  readonly startupSettleQuietMs: number;
+  readonly startupSettleNonemptyFallbackMs: number;
+  readonly backgroundWaitMaxMs: number;
+  readonly backgroundProbeEnabled: boolean;
+  readonly backgroundResumeEnabled: boolean;
+  readonly startPerfSpan: (name: string, attrs?: PerfAttrs) => PerfSpanLike;
+  readonly startupSpan: PerfSpanLike;
+  readonly recordPerfEvent: (name: string, attrs: PerfAttrs) => void;
+  readonly getConversation: (sessionId: string) => ConversationState | undefined;
+  readonly isShuttingDown: () => boolean;
+  readonly refreshProcessUsage: (reason: 'startup' | 'interval') => void | Promise<void>;
+  readonly queuePersistedConversationsInBackground: (initialActiveId: string | null) => number;
+  readonly hydrateStartupState: (afterCursor: number | null) => Promise<void>;
+  readonly activateConversation: (sessionId: string) => Promise<void>;
+  readonly conversationCount: () => number;
+}
+
+interface StartupRenderFlushInput {
+  readonly activeConversation: ConversationState | null;
+  readonly activeConversationId: string | null;
+  readonly rightFrameVisible: boolean;
+  readonly changedRowCount: number;
+}
+
+export class StartupOrchestrator {
+  private readonly startupSequencer: StartupSequencer;
+  private readonly startupSpanTracker: StartupSpanTracker;
+  private readonly startupOutputTracker: StartupOutputTracker;
+  private readonly startupPaintTracker: StartupPaintTracker;
+  private readonly startupBackgroundProbeService: StartupBackgroundProbeService;
+  private readonly startupBackgroundResumeService: StartupBackgroundResumeService;
+  private readonly startupShutdownService: StartupShutdownService;
+
+  constructor(private readonly options: StartupOrchestratorOptions) {
+    this.startupSequencer = new StartupSequencer({
+      quietMs: options.startupSettleQuietMs,
+      nonemptyFallbackMs: options.startupSettleNonemptyFallbackMs,
+    });
+    this.startupSpanTracker = new StartupSpanTracker(
+      options.startPerfSpan,
+      options.startupSettleQuietMs,
+    );
+    const startupVisibility = new StartupVisibility();
+    const startupSettledGate = new StartupSettledGate({
+      startupSequencer: this.startupSequencer,
+      startupSpanTracker: this.startupSpanTracker,
+      getConversation: options.getConversation,
+      visibleGlyphCellCount: (conversation) =>
+        startupVisibility.visibleGlyphCellCount(conversation),
+      recordPerfEvent: options.recordPerfEvent,
+    });
+    this.startupOutputTracker = new StartupOutputTracker({
+      startupSequencer: this.startupSequencer,
+      startupSpanTracker: this.startupSpanTracker,
+      recordPerfEvent: options.recordPerfEvent,
+    });
+    this.startupPaintTracker = new StartupPaintTracker({
+      startupSequencer: this.startupSequencer,
+      startupSpanTracker: this.startupSpanTracker,
+      startupVisibility,
+      startupSettledGate,
+      recordPerfEvent: options.recordPerfEvent,
+    });
+    this.startupBackgroundProbeService = new StartupBackgroundProbeService({
+      enabled: options.backgroundProbeEnabled,
+      maxWaitMs: options.backgroundWaitMaxMs,
+      isShuttingDown: options.isShuttingDown,
+      waitForSettled: () => this.startupSequencer.waitForSettled(),
+      settledObserved: () => this.startupSequencer.snapshot().settledObserved,
+      refreshProcessUsage: options.refreshProcessUsage,
+      recordPerfEvent: options.recordPerfEvent,
+    });
+    this.startupBackgroundResumeService = new StartupBackgroundResumeService({
+      enabled: options.backgroundResumeEnabled,
+      maxWaitMs: options.backgroundWaitMaxMs,
+      waitForSettled: () => this.startupSequencer.waitForSettled(),
+      settledObserved: () => this.startupSequencer.snapshot().settledObserved,
+      queuePersistedConversationsInBackground: options.queuePersistedConversationsInBackground,
+      recordPerfEvent: options.recordPerfEvent,
+    });
+    this.startupShutdownService = new StartupShutdownService({
+      startupSequencer: this.startupSequencer,
+      startupSpanTracker: this.startupSpanTracker,
+      startupSettledGate,
+    });
+  }
+
+  get firstPaintTargetSessionId(): string | null {
+    return this.startupSpanTracker.firstPaintTargetSessionId;
+  }
+
+  endStartCommandSpan(attrs: PerfAttrs): void {
+    this.startupSpanTracker.endStartCommandSpan(attrs);
+  }
+
+  onOutputChunk(sessionId: string, bytes: number): void {
+    this.startupOutputTracker.onOutputChunk(sessionId, bytes);
+  }
+
+  onPaintOutputChunk(sessionId: string): void {
+    this.startupPaintTracker.onOutputChunk(sessionId);
+  }
+
+  onRenderFlush(input: StartupRenderFlushInput): void {
+    this.startupPaintTracker.onRenderFlush(input);
+  }
+
+  startBackgroundProbe(): void {
+    this.startupBackgroundProbeService.recordWaitPhase();
+    void this.startupBackgroundProbeService.startWhenSettled();
+  }
+
+  stop(): void {
+    this.startupBackgroundProbeService.stop();
+  }
+
+  async hydrateStartupState(afterCursor: number | null): Promise<void> {
+    await this.options.hydrateStartupState(afterCursor);
+  }
+
+  async activateInitialConversation(initialActiveId: string | null): Promise<void> {
+    this.startupSequencer.setTargetSession(initialActiveId);
+    if (initialActiveId === null) {
+      return;
+    }
+    this.startupSpanTracker.beginForSession(initialActiveId);
+    const initialActivateSpan = this.options.startPerfSpan('mux.startup.activate-initial', {
+      initialActiveId,
+    });
+    await this.options.activateConversation(initialActiveId);
+    initialActivateSpan.end();
+  }
+
+  finalizeStartup(initialActiveId: string | null): void {
+    const conversationCount = this.options.conversationCount();
+    this.options.startupSpan.end({
+      conversations: conversationCount,
+    });
+    this.options.recordPerfEvent('mux.startup.ready', {
+      conversations: conversationCount,
+    });
+    void this.startupBackgroundResumeService.run(initialActiveId);
+  }
+
+  finalize(): void {
+    this.startupShutdownService.finalize();
+  }
+}