@jmoyers/harness 0.1.0

package/src/mux/live-mux/global-shortcut-handlers.ts

@@ -0,0 +1,143 @@
+type ShortcutCycleDirection = 'next' | 'previous';
+
+interface HandleGlobalShortcutOptions {
+  shortcut: string | null;
+  requestStop: () => void;
+  resolveDirectoryForAction: () => string | null;
+  openNewThreadPrompt: (directoryId: string) => void;
+  toggleCommandMenu: () => void;
+  openOrCreateCritiqueConversationInDirectory: (directoryId: string) => Promise<void>;
+  toggleGatewayProfile: () => Promise<void>;
+  toggleGatewayStatusTimeline: () => Promise<void>;
+  toggleGatewayRenderTrace: (conversationId: string | null) => Promise<void>;
+  resolveConversationForAction: () => string | null;
+  conversationsHas: (sessionId: string) => boolean;
+  queueControlPlaneOp: (task: () => Promise<void>, label: string) => void;
+  archiveConversation: (sessionId: string) => Promise<void>;
+  interruptConversation: (sessionId: string) => Promise<void>;
+  takeoverConversation: (sessionId: string) => Promise<void>;
+  openAddDirectoryPrompt: () => void;
+  resolveClosableDirectoryId: () => string | null;
+  closeDirectory: (directoryId: string) => Promise<void>;
+  cycleLeftNavSelection: (direction: ShortcutCycleDirection) => void;
+}
+
+export function handleGlobalShortcut(options: HandleGlobalShortcutOptions): boolean {
+  const {
+    shortcut,
+    requestStop,
+    resolveDirectoryForAction,
+    openNewThreadPrompt,
+    toggleCommandMenu,
+    openOrCreateCritiqueConversationInDirectory,
+    toggleGatewayProfile,
+    toggleGatewayStatusTimeline,
+    toggleGatewayRenderTrace,
+    resolveConversationForAction,
+    conversationsHas,
+    queueControlPlaneOp,
+    archiveConversation,
+    interruptConversation,
+    takeoverConversation,
+    openAddDirectoryPrompt,
+    resolveClosableDirectoryId,
+    closeDirectory,
+    cycleLeftNavSelection,
+  } = options;
+  if (shortcut === null) {
+    return false;
+  }
+  if (shortcut === 'mux.app.interrupt-all' || shortcut === 'mux.app.quit') {
+    requestStop();
+    return true;
+  }
+  if (shortcut === 'mux.conversation.new') {
+    const targetDirectoryId = resolveDirectoryForAction();
+    if (targetDirectoryId !== null) {
+      openNewThreadPrompt(targetDirectoryId);
+    }
+    return true;
+  }
+  if (shortcut === 'mux.command-menu.toggle') {
+    toggleCommandMenu();
+    return true;
+  }
+  if (shortcut === 'mux.conversation.critique.open-or-create') {
+    const targetDirectoryId = resolveDirectoryForAction();
+    if (targetDirectoryId !== null) {
+      queueControlPlaneOp(async () => {
+        await openOrCreateCritiqueConversationInDirectory(targetDirectoryId);
+      }, 'shortcut-open-or-create-critique-conversation');
+    }
+    return true;
+  }
+  if (shortcut === 'mux.gateway.profile.toggle') {
+    queueControlPlaneOp(async () => {
+      await toggleGatewayProfile();
+    }, 'shortcut-toggle-gateway-profile');
+    return true;
+  }
+  if (shortcut === 'mux.gateway.status-timeline.toggle') {
+    queueControlPlaneOp(async () => {
+      await toggleGatewayStatusTimeline();
+    }, 'shortcut-toggle-gateway-status-timeline');
+    return true;
+  }
+  if (shortcut === 'mux.gateway.render-trace.toggle') {
+    const targetConversationId = resolveConversationForAction();
+    queueControlPlaneOp(async () => {
+      await toggleGatewayRenderTrace(targetConversationId);
+    }, 'shortcut-toggle-gateway-render-trace');
+    return true;
+  }
+  if (shortcut === 'mux.conversation.archive' || shortcut === 'mux.conversation.delete') {
+    const targetConversationId = resolveConversationForAction();
+    if (targetConversationId !== null && conversationsHas(targetConversationId)) {
+      queueControlPlaneOp(
+        async () => {
+          await archiveConversation(targetConversationId);
+        },
+        shortcut === 'mux.conversation.archive'
+          ? 'shortcut-archive-conversation'
+          : 'shortcut-delete-conversation',
+      );
+    }
+    return true;
+  }
+  if (shortcut === 'mux.conversation.interrupt') {
+    const targetConversationId = resolveConversationForAction();
+    if (targetConversationId !== null && conversationsHas(targetConversationId)) {
+      queueControlPlaneOp(async () => {
+        await interruptConversation(targetConversationId);
+      }, 'shortcut-interrupt-conversation');
+    }
+    return true;
+  }
+  if (shortcut === 'mux.conversation.takeover') {
+    const targetConversationId = resolveConversationForAction();
+    if (targetConversationId !== null && conversationsHas(targetConversationId)) {
+      queueControlPlaneOp(async () => {
+        await takeoverConversation(targetConversationId);
+      }, 'shortcut-takeover-conversation');
+    }
+    return true;
+  }
+  if (shortcut === 'mux.directory.add') {
+    openAddDirectoryPrompt();
+    return true;
+  }
+  if (shortcut === 'mux.directory.close') {
+    const targetDirectoryId = resolveClosableDirectoryId();
+    if (targetDirectoryId !== null) {
+      queueControlPlaneOp(async () => {
+        await closeDirectory(targetDirectoryId);
+      }, 'shortcut-close-directory');
+    }
+    return true;
+  }
+  if (shortcut === 'mux.conversation.next' || shortcut === 'mux.conversation.previous') {
+    cycleLeftNavSelection(shortcut === 'mux.conversation.next' ? 'next' : 'previous');
+    return true;
+  }
+  return false;
+}

package/src/mux/live-mux/home-pane-actions.ts

@@ -0,0 +1,58 @@
+interface HandleHomePaneActionClickOptions {
+  action: string | null;
+  rowIndex: number;
+  clearTaskEditClickState: () => void;
+  clearRepositoryEditClickState: () => void;
+  clearHomePaneDragState: () => void;
+  getTaskRepositoryDropdownOpen: () => boolean;
+  setTaskRepositoryDropdownOpen: (open: boolean) => void;
+  taskIdAtRow: (rowIndex: number) => string | null;
+  repositoryIdAtRow: (rowIndex: number) => string | null;
+  selectTaskById: (taskId: string) => void;
+  selectRepositoryById: (repositoryId: string) => void;
+  runTaskPaneAction: (action: 'task.ready' | 'task.draft' | 'task.complete') => void;
+  markDirty: () => void;
+}
+
+export function handleHomePaneActionClick(options: HandleHomePaneActionClickOptions): boolean {
+  if (options.action === null) {
+    return false;
+  }
+  options.clearTaskEditClickState();
+  options.clearRepositoryEditClickState();
+  options.clearHomePaneDragState();
+
+  if (options.action === 'repository.dropdown.toggle') {
+    options.setTaskRepositoryDropdownOpen(!options.getTaskRepositoryDropdownOpen());
+  } else if (options.action === 'repository.select') {
+    const repositoryId = options.repositoryIdAtRow(options.rowIndex);
+    if (repositoryId !== null) {
+      options.selectRepositoryById(repositoryId);
+    }
+  } else if (options.action === 'task.focus') {
+    const taskId = options.taskIdAtRow(options.rowIndex);
+    if (taskId !== null) {
+      options.selectTaskById(taskId);
+    }
+  } else if (options.action === 'task.status.ready') {
+    const taskId = options.taskIdAtRow(options.rowIndex);
+    if (taskId !== null) {
+      options.selectTaskById(taskId);
+      options.runTaskPaneAction('task.ready');
+    }
+  } else if (options.action === 'task.status.draft') {
+    const taskId = options.taskIdAtRow(options.rowIndex);
+    if (taskId !== null) {
+      options.selectTaskById(taskId);
+      options.runTaskPaneAction('task.draft');
+    }
+  } else if (options.action === 'task.status.complete') {
+    const taskId = options.taskIdAtRow(options.rowIndex);
+    if (taskId !== null) {
+      options.selectTaskById(taskId);
+      options.runTaskPaneAction('task.complete');
+    }
+  }
+  options.markDirty();
+  return true;
+}

package/src/mux/live-mux/home-pane-drop.ts

@@ -0,0 +1,44 @@
+interface HomePaneDragState {
+  readonly kind: 'task' | 'repository';
+  readonly itemId: string;
+  readonly startedRowIndex: number;
+  readonly latestRowIndex: number;
+  readonly hasDragged: boolean;
+}
+
+interface HandleHomePaneDragReleaseOptions {
+  homePaneDragState: HomePaneDragState | null;
+  isMouseRelease: boolean;
+  mainPaneMode: 'conversation' | 'project' | 'home';
+  target: string;
+  rowIndex: number;
+  taskIdAtRow: (rowIndex: number) => string | null;
+  repositoryIdAtRow: (rowIndex: number) => string | null;
+  reorderTaskByDrop: (draggedTaskId: string, targetTaskId: string) => void;
+  reorderRepositoryByDrop: (draggedRepositoryId: string, targetRepositoryId: string) => void;
+  setHomePaneDragState: (next: HomePaneDragState | null) => void;
+  markDirty: () => void;
+}
+
+export function handleHomePaneDragRelease(options: HandleHomePaneDragReleaseOptions): boolean {
+  if (options.homePaneDragState === null || !options.isMouseRelease) {
+    return false;
+  }
+  const drag = options.homePaneDragState;
+  options.setHomePaneDragState(null);
+  if (options.mainPaneMode === 'home' && options.target === 'right' && drag.hasDragged) {
+    if (drag.kind === 'task') {
+      const targetTaskId = options.taskIdAtRow(options.rowIndex);
+      if (targetTaskId !== null) {
+        options.reorderTaskByDrop(drag.itemId, targetTaskId);
+      }
+    } else {
+      const targetRepositoryId = options.repositoryIdAtRow(options.rowIndex);
+      if (targetRepositoryId !== null) {
+        options.reorderRepositoryByDrop(drag.itemId, targetRepositoryId);
+      }
+    }
+  }
+  options.markDirty();
+  return true;
+}

package/src/mux/live-mux/home-pane-entity-click.ts

@@ -0,0 +1,96 @@
+import { detectEntityDoubleClick } from '../double-click.ts';
+
+interface EntityDoubleClickState {
+  readonly entityId: string;
+  readonly atMs: number;
+}
+
+interface HomePaneDragState {
+  readonly kind: 'task' | 'repository';
+  readonly itemId: string;
+  readonly startedRowIndex: number;
+  readonly latestRowIndex: number;
+  readonly hasDragged: boolean;
+}
+
+interface HandleHomePaneEntityClickOptions {
+  rowIndex: number;
+  nowMs: number;
+  homePaneEditDoubleClickWindowMs: number;
+  taskEditClickState: EntityDoubleClickState | null;
+  repositoryEditClickState: EntityDoubleClickState | null;
+  taskIdAtRow: (rowIndex: number) => string | null;
+  repositoryIdAtRow: (rowIndex: number) => string | null;
+  selectTaskById: (taskId: string) => void;
+  selectRepositoryById: (repositoryId: string) => void;
+  clearTaskPaneNotice: () => void;
+  setTaskEditClickState: (next: EntityDoubleClickState | null) => void;
+  setRepositoryEditClickState: (next: EntityDoubleClickState | null) => void;
+  setHomePaneDragState: (next: HomePaneDragState | null) => void;
+  openTaskEditPrompt: (taskId: string) => void;
+  openRepositoryPromptForEdit: (repositoryId: string) => void;
+  markDirty: () => void;
+}
+
+export function handleHomePaneEntityClick(options: HandleHomePaneEntityClickOptions): boolean {
+  const taskId = options.taskIdAtRow(options.rowIndex);
+  if (taskId !== null) {
+    const click = detectEntityDoubleClick(
+      options.taskEditClickState,
+      taskId,
+      options.nowMs,
+      options.homePaneEditDoubleClickWindowMs,
+    );
+    options.selectTaskById(taskId);
+    options.clearTaskPaneNotice();
+    options.setTaskEditClickState(click.nextState);
+    options.setRepositoryEditClickState(null);
+    if (click.doubleClick) {
+      options.setHomePaneDragState(null);
+      options.openTaskEditPrompt(taskId);
+    } else {
+      options.setHomePaneDragState({
+        kind: 'task',
+        itemId: taskId,
+        startedRowIndex: options.rowIndex,
+        latestRowIndex: options.rowIndex,
+        hasDragged: false,
+      });
+    }
+    options.markDirty();
+    return true;
+  }
+
+  const repositoryId = options.repositoryIdAtRow(options.rowIndex);
+  if (repositoryId !== null) {
+    const click = detectEntityDoubleClick(
+      options.repositoryEditClickState,
+      repositoryId,
+      options.nowMs,
+      options.homePaneEditDoubleClickWindowMs,
+    );
+    options.selectRepositoryById(repositoryId);
+    options.clearTaskPaneNotice();
+    options.setRepositoryEditClickState(click.nextState);
+    options.setTaskEditClickState(null);
+    if (click.doubleClick) {
+      options.setHomePaneDragState(null);
+      options.openRepositoryPromptForEdit(repositoryId);
+    } else {
+      options.setHomePaneDragState({
+        kind: 'repository',
+        itemId: repositoryId,
+        startedRowIndex: options.rowIndex,
+        latestRowIndex: options.rowIndex,
+        hasDragged: false,
+      });
+    }
+    options.markDirty();
+    return true;
+  }
+
+  options.setTaskEditClickState(null);
+  options.setRepositoryEditClickState(null);
+  options.setHomePaneDragState(null);
+  return false;
+}

package/src/mux/live-mux/home-pane-pointer.ts

@@ -0,0 +1,96 @@
+import { handleHomePaneActionClick } from './home-pane-actions.ts';
+import { handleHomePaneEntityClick } from './home-pane-entity-click.ts';
+
+interface EntityDoubleClickState {
+  readonly entityId: string;
+  readonly atMs: number;
+}
+
+interface HomePaneDragState {
+  readonly kind: 'task' | 'repository';
+  readonly itemId: string;
+  readonly startedRowIndex: number;
+  readonly latestRowIndex: number;
+  readonly hasDragged: boolean;
+}
+
+interface HandleHomePanePointerClickOptions {
+  clickEligible: boolean;
+  paneRows: number;
+  rightCols: number;
+  rightStartCol: number;
+  pointerRow: number;
+  pointerCol: number;
+  actionAtCell: (rowIndex: number, colIndex: number) => string | null;
+  actionAtRow: (rowIndex: number) => string | null;
+  clearTaskEditClickState: () => void;
+  clearRepositoryEditClickState: () => void;
+  clearHomePaneDragState: () => void;
+  getTaskRepositoryDropdownOpen: () => boolean;
+  setTaskRepositoryDropdownOpen: (open: boolean) => void;
+  taskIdAtRow: (rowIndex: number) => string | null;
+  repositoryIdAtRow: (rowIndex: number) => string | null;
+  selectTaskById: (taskId: string) => void;
+  selectRepositoryById: (repositoryId: string) => void;
+  runTaskPaneAction: (action: 'task.ready' | 'task.draft' | 'task.complete') => void;
+  nowMs: number;
+  homePaneEditDoubleClickWindowMs: number;
+  taskEditClickState: EntityDoubleClickState | null;
+  repositoryEditClickState: EntityDoubleClickState | null;
+  clearTaskPaneNotice: () => void;
+  setTaskEditClickState: (next: EntityDoubleClickState | null) => void;
+  setRepositoryEditClickState: (next: EntityDoubleClickState | null) => void;
+  setHomePaneDragState: (next: HomePaneDragState | null) => void;
+  openTaskEditPrompt: (taskId: string) => void;
+  openRepositoryPromptForEdit: (repositoryId: string) => void;
+  markDirty: () => void;
+}
+
+export function handleHomePanePointerClick(options: HandleHomePanePointerClickOptions): boolean {
+  if (!options.clickEligible) {
+    return false;
+  }
+  const rowIndex = Math.max(0, Math.min(options.paneRows - 1, options.pointerRow - 1));
+  const colIndex = Math.max(
+    0,
+    Math.min(options.rightCols - 1, options.pointerCol - options.rightStartCol),
+  );
+  const action = options.actionAtCell(rowIndex, colIndex) ?? options.actionAtRow(rowIndex);
+  if (
+    handleHomePaneActionClick({
+      action,
+      rowIndex,
+      clearTaskEditClickState: options.clearTaskEditClickState,
+      clearRepositoryEditClickState: options.clearRepositoryEditClickState,
+      clearHomePaneDragState: options.clearHomePaneDragState,
+      getTaskRepositoryDropdownOpen: options.getTaskRepositoryDropdownOpen,
+      setTaskRepositoryDropdownOpen: options.setTaskRepositoryDropdownOpen,
+      taskIdAtRow: options.taskIdAtRow,
+      repositoryIdAtRow: options.repositoryIdAtRow,
+      selectTaskById: options.selectTaskById,
+      selectRepositoryById: options.selectRepositoryById,
+      runTaskPaneAction: options.runTaskPaneAction,
+      markDirty: options.markDirty,
+    })
+  ) {
+    return true;
+  }
+  return handleHomePaneEntityClick({
+    rowIndex,
+    nowMs: options.nowMs,
+    homePaneEditDoubleClickWindowMs: options.homePaneEditDoubleClickWindowMs,
+    taskEditClickState: options.taskEditClickState,
+    repositoryEditClickState: options.repositoryEditClickState,
+    taskIdAtRow: options.taskIdAtRow,
+    repositoryIdAtRow: options.repositoryIdAtRow,
+    selectTaskById: options.selectTaskById,
+    selectRepositoryById: options.selectRepositoryById,
+    clearTaskPaneNotice: options.clearTaskPaneNotice,
+    setTaskEditClickState: options.setTaskEditClickState,
+    setRepositoryEditClickState: options.setRepositoryEditClickState,
+    setHomePaneDragState: options.setHomePaneDragState,
+    openTaskEditPrompt: options.openTaskEditPrompt,
+    openRepositoryPromptForEdit: options.openRepositoryPromptForEdit,
+    markDirty: options.markDirty,
+  });
+}

package/src/mux/live-mux/input-forwarding.ts

@@ -0,0 +1,112 @@
+import type { TerminalSnapshotFrameCore } from '../../terminal/snapshot-oracle.ts';
+
+type RoutedInputToken =
+  | {
+      kind: 'passthrough';
+      text: string;
+    }
+  | {
+      kind: 'mouse';
+      event: {
+        col: number;
+        row: number;
+        code: number;
+        final: 'M' | 'm';
+      };
+    };
+
+interface RouteInputTokensForConversationOptions {
+  tokens: readonly RoutedInputToken[];
+  mainPaneMode: 'conversation' | 'project' | 'home';
+  normalizeMuxKeyboardInputForPty: (input: Buffer) => Buffer;
+  classifyPaneAt: (col: number, row: number) => string;
+  wheelDeltaRowsFromCode: (code: number) => number | null;
+  hasShiftModifier: (code: number) => boolean;
+  layout: {
+    paneRows: number;
+    rightCols: number;
+    rightStartCol: number;
+  };
+  snapshotForInput: Pick<TerminalSnapshotFrameCore, 'activeScreen' | 'viewport'> | null;
+  appMouseTrackingEnabled: boolean;
+}
+
+interface RouteInputTokensForConversationResult {
+  readonly mainPaneScrollRows: number;
+  readonly forwardToSession: readonly Buffer[];
+}
+
+function encodeSgrMouseEvent(code: number, col: number, row: number, final: 'M' | 'm'): Buffer {
+  return Buffer.from(`\u001b[<${String(code)};${String(col)};${String(row)}${final}`, 'utf8');
+}
+
+function shouldPassThroughMouseToConversation(
+  options: Pick<
+    RouteInputTokensForConversationOptions,
+    'snapshotForInput' | 'appMouseTrackingEnabled' | 'hasShiftModifier'
+  >,
+  code: number,
+): boolean {
+  if (options.snapshotForInput === null) {
+    return false;
+  }
+  if (!options.appMouseTrackingEnabled) {
+    return false;
+  }
+  if (options.snapshotForInput.activeScreen !== 'alternate') {
+    return false;
+  }
+  if (!options.snapshotForInput.viewport.followOutput) {
+    return false;
+  }
+  if (options.hasShiftModifier(code)) {
+    return false;
+  }
+  return true;
+}
+
+export function routeInputTokensForConversation(
+  options: RouteInputTokensForConversationOptions,
+): RouteInputTokensForConversationResult {
+  let mainPaneScrollRows = 0;
+  const forwardToSession: Buffer[] = [];
+  for (const token of options.tokens) {
+    if (token.kind === 'passthrough') {
+      if (options.mainPaneMode === 'conversation' && token.text.length > 0) {
+        forwardToSession.push(
+          options.normalizeMuxKeyboardInputForPty(Buffer.from(token.text, 'utf8')),
+        );
+      }
+      continue;
+    }
+    if (options.classifyPaneAt(token.event.col, token.event.row) !== 'right') {
+      continue;
+    }
+    if (options.mainPaneMode !== 'conversation') {
+      continue;
+    }
+    if (shouldPassThroughMouseToConversation(options, token.event.code)) {
+      const sessionCol = Math.max(
+        1,
+        Math.min(options.layout.rightCols, token.event.col - options.layout.rightStartCol + 1),
+      );
+      const sessionRow = Math.max(1, Math.min(options.layout.paneRows, token.event.row));
+      forwardToSession.push(
+        encodeSgrMouseEvent(token.event.code, sessionCol, sessionRow, token.event.final),
+      );
+      continue;
+    }
+    const wheelDelta = options.wheelDeltaRowsFromCode(token.event.code);
+    if (wheelDelta !== null) {
+      mainPaneScrollRows += wheelDelta;
+      continue;
+    }
+    // The mux owns mouse interactions. Forwarding raw SGR mouse sequences to shell-style
+    // threads produces visible control garbage (for example on initial click-to-focus).
+    continue;
+  }
+  return {
+    mainPaneScrollRows,
+    forwardToSession,
+  };
+}

package/src/mux/live-mux/layout.ts

@@ -0,0 +1,30 @@
+const DEFAULT_PANE_WIDTH_PERCENT = 30;
+const MIN_PANE_WIDTH_PERCENT = 1;
+const MAX_PANE_WIDTH_PERCENT = 99;
+
+export function normalizePaneWidthPercent(value: number): number {
+  if (!Number.isFinite(value)) {
+    return DEFAULT_PANE_WIDTH_PERCENT;
+  }
+  if (value < MIN_PANE_WIDTH_PERCENT) {
+    return MIN_PANE_WIDTH_PERCENT;
+  }
+  if (value > MAX_PANE_WIDTH_PERCENT) {
+    return MAX_PANE_WIDTH_PERCENT;
+  }
+  return value;
+}
+
+export function leftColsFromPaneWidthPercent(cols: number, paneWidthPercent: number): number {
+  const availablePaneCols = Math.max(2, cols - 1);
+  const normalizedPercent = normalizePaneWidthPercent(paneWidthPercent);
+  const requestedLeftCols = Math.round((availablePaneCols * normalizedPercent) / 100);
+  return Math.max(1, Math.min(availablePaneCols - 1, requestedLeftCols));
+}
+
+export function paneWidthPercentFromLayout(layout: { cols: number; leftCols: number }): number {
+  const availablePaneCols = Math.max(2, layout.cols - 1);
+  const percent = (layout.leftCols / availablePaneCols) * 100;
+  const rounded = Math.round(percent * 100) / 100;
+  return normalizePaneWidthPercent(rounded);
+}

package/src/mux/live-mux/left-nav-activation.ts

@@ -0,0 +1,103 @@
+import { cycleConversationId } from '../conversation-rail.ts';
+import { leftNavTargetKey, type LeftNavSelection } from './left-nav.ts';
+
+interface ActivateLeftNavTargetOptions {
+  target: LeftNavSelection;
+  direction: 'next' | 'previous';
+  enterHomePane: () => void;
+  firstDirectoryForRepositoryGroup: (repositoryGroupId: string) => string | null;
+  enterProjectPane: (directoryId: string) => void;
+  setMainPaneProjectMode: () => void;
+  selectLeftNavRepository: (repositoryGroupId: string) => void;
+  markDirty: () => void;
+  directoriesHas: (directoryId: string) => boolean;
+  visibleTargetsForState: () => readonly LeftNavSelection[];
+  conversationDirectoryId: (sessionId: string) => string | null;
+  queueControlPlaneOp: (task: () => Promise<void>, label: string) => void;
+  activateConversation: (sessionId: string) => Promise<void>;
+  conversationsHas: (sessionId: string) => boolean;
+}
+
+export function activateLeftNavTarget(options: ActivateLeftNavTargetOptions): void {
+  const {
+    target,
+    direction,
+    enterHomePane,
+    firstDirectoryForRepositoryGroup,
+    enterProjectPane,
+    setMainPaneProjectMode,
+    selectLeftNavRepository,
+    markDirty,
+    directoriesHas,
+    visibleTargetsForState,
+    conversationDirectoryId,
+    queueControlPlaneOp,
+    activateConversation,
+    conversationsHas,
+  } = options;
+  if (target.kind === 'home') {
+    enterHomePane();
+    return;
+  }
+  if (target.kind === 'repository') {
+    const firstDirectoryId = firstDirectoryForRepositoryGroup(target.repositoryId);
+    if (firstDirectoryId !== null) {
+      enterProjectPane(firstDirectoryId);
+    } else {
+      setMainPaneProjectMode();
+    }
+    selectLeftNavRepository(target.repositoryId);
+    markDirty();
+    return;
+  }
+  if (target.kind === 'project') {
+    if (directoriesHas(target.directoryId)) {
+      enterProjectPane(target.directoryId);
+      markDirty();
+      return;
+    }
+    const visibleTargets = visibleTargetsForState();
+    const fallbackConversation = visibleTargets.find(
+      (entry): entry is Extract<LeftNavSelection, { kind: 'conversation' }> =>
+        entry.kind === 'conversation' &&
+        conversationDirectoryId(entry.sessionId) === target.directoryId,
+    );
+    if (fallbackConversation !== undefined) {
+      queueControlPlaneOp(async () => {
+        await activateConversation(fallbackConversation.sessionId);
+      }, `shortcut-activate-${direction}-directory-fallback`);
+    }
+    return;
+  }
+  if (!conversationsHas(target.sessionId)) {
+    return;
+  }
+  queueControlPlaneOp(async () => {
+    await activateConversation(target.sessionId);
+  }, `shortcut-activate-${direction}`);
+}
+
+interface CycleLeftNavSelectionOptions {
+  visibleTargets: readonly LeftNavSelection[];
+  currentSelection: LeftNavSelection;
+  direction: 'next' | 'previous';
+  activateTarget: (target: LeftNavSelection, direction: 'next' | 'previous') => void;
+}
+
+export function cycleLeftNavSelection(options: CycleLeftNavSelectionOptions): boolean {
+  const { visibleTargets, currentSelection, direction, activateTarget } = options;
+  if (visibleTargets.length === 0) {
+    return false;
+  }
+  const targetKeys = visibleTargets.map((target) => leftNavTargetKey(target));
+  const targetKey = cycleConversationId(targetKeys, leftNavTargetKey(currentSelection), direction);
+  if (targetKey === null) {
+    return false;
+  }
+  const target = visibleTargets.find((entry) => leftNavTargetKey(entry) === targetKey);
+  if (target === undefined) {
+    return false;
+  }
+  activateTarget(target, direction);
+  return true;
+}