@cueloop/client 0.1.0-alpha.4 → 0.1.0-alpha.40

package/src/keymap.ts

@@ -0,0 +1,339 @@
+/**
+ * The keyboard grammar as a pure reducer: view state in, intents out.
+ * App builds a KeyState per key event, calls reduceKey, and dispatches the
+ * intents to controller verbs and view-state setters - no branch bodies live
+ * in the key handler. Diff and plan reviews share one path for annotation
+ * navigation, deletion, and submit; the read-only rule is one gate here.
+ */
+
+import { actionFor } from "./config";
+
+export type Intent =
+  | { type: "exit" }
+  | { type: "status"; message: string }
+  | { type: "move"; to: "down" | "up" | "top" | "bottom" }
+  | { type: "inboxMove"; to: "down" | "up" }
+  | { type: "openSession" }
+  | { type: "requestDeleteSession" }
+  | { type: "openRename" }
+  | { type: "confirmDialog" }
+  | { type: "startSpan" }
+  | { type: "spanKey"; name: string }
+  | { type: "spanCut" }
+  | { type: "openSpanActions" }
+  | { type: "moveSpanAction"; direction: -1 | 1 }
+  | { type: "pickSpanAction"; index?: number }
+  | { type: "closeSpanActions" }
+  | { type: "openCompose"; kind: "comment"; from: "cursor" | "span" }
+  | { type: "openSubmit" }
+  | { type: "share" }
+  | { type: "cut" }
+  | { type: "edit" }
+  | { type: "editCard" }
+  | { type: "rejectHunk" }
+  | { type: "rejectChange" }
+  | { type: "restoreCuration" }
+  | { type: "nextAnnotation" }
+  | { type: "prevAnnotation" }
+  | { type: "walkStart" }
+  | { type: "walkForward" }
+  | { type: "walkBack" }
+  | { type: "walkLeave" }
+  | { type: "removeAnnotation" }
+  | { type: "deselect" }
+  | { type: "closeOverlay" }
+  | { type: "saveCompose" }
+  | { type: "submitVerdict" }
+  | { type: "cycleVerdict"; direction: -1 | 1 }
+  | { type: "finishReview" }
+  | { type: "optInAutoClose" }
+  | { type: "dismissCompletion" }
+  | { type: "cycleReviewPanel" }
+  | { type: "resizeReviewPanel"; direction: -1 | 1 };
+
+export interface KeyInput {
+  name: string;
+  shift: boolean;
+  /** Option/Alt arrives as `meta` in this terminal stack (never as a raw alt). */
+  meta?: boolean;
+}
+
+export interface KeyState {
+  /** Loaded keymap (config.ts): action -> key combos. */
+  keys: Record<string, string[]>;
+  readOnly: boolean;
+  /**
+   * Owner-only verbs a share collaborator lacks (undefined = owner, allowed).
+   * A collaborator annotates but cannot edit the plan (cut / $EDITOR runs on
+   * the gateway) or submit an agent verdict (there is no agent on a share).
+   */
+  canEditPlan?: boolean;
+  canSubmitVerdict?: boolean;
+  /** Owner-only: publish the plan as a share. A collaborator never re-shares. */
+  canShare?: boolean;
+  /** Layer that owns keys before the grammar runs. */
+  overlay:
+    | "none"
+    | "walk"
+    | "compose"
+    | "submit"
+    | "confirm"
+    | "prompt"
+    | "spanActions"
+    | "completion-prompt"
+    | "completion-counting";
+  view: "inbox" | "plan" | "diff";
+  /** Plan-only span selection sub-mode. */
+  spanMode: boolean;
+  /** The walk cursor sits on the end card - return offers the submit action. */
+  walkAtEnd: boolean;
+  resolved: boolean;
+  hasInboxItems: boolean;
+  annotationCount: number;
+  hasFocusedAnnotation: boolean;
+  /** Cursor sits on annotatable text: a work block (plan) or a code row (diff). */
+  cursorAnnotatable: boolean;
+}
+
+/** Verbs that write session state; an observer never reaches their handlers. */
+const MUTATING_ACTIONS = new Set([
+  "comment",
+  "cut",
+  "edit",
+  "delete_annotation",
+  "submit",
+  "walk",
+  "share",
+  "reject_hunk",
+  "restore_curation",
+]);
+
+const SPAN_KEYS = new Set(["l", "h", "w", "b", "$", "0"]);
+
+function status(message: string): Intent[] {
+  return [{ type: "status", message }];
+}
+
+/**
+ * Reduce one key event to intents. `resolvedAction` is the binding-layer
+ * resolution (key-bindings.ts over @opentui/keymap) when the caller has one;
+ * without it the reducer falls back to the plain reverse lookup, so the
+ * grammar stays testable as a pure function.
+ */
+export function reduceKey(state: KeyState, key: KeyInput, resolvedAction?: string): Intent[] {
+  const name = key.name;
+  // compose/submit overlays own the keys via focused inputs; only escape,
+  // return, and verdict arrows route through the grammar
+  if (state.overlay === "compose" || state.overlay === "submit") {
+    if (name === "escape") return [{ type: "closeOverlay" }];
+    if (name === "return" || name === "enter") {
+      // In the composer, ⌥/Alt+⏎ (meta) and shift+⏎ insert a newline - the
+      // focused textarea owns that; only a bare ⏎ saves. The submit overlay
+      // keeps its plain ⏎ submit.
+      if (state.overlay === "compose") {
+        if (key.shift || key.meta) return [];
+        return [{ type: "saveCompose" }];
+      }
+      return [{ type: "submitVerdict" }];
+    }
+    if (state.overlay === "submit" && (name === "left" || name === "right")) {
+      return [{ type: "cycleVerdict", direction: name === "left" ? -1 : 1 }];
+    }
+    return [];
+  }
+  // a modal confirm owns the keys: ⏎ commits the action, escape backs out
+  if (state.overlay === "confirm") {
+    if (name === "return" || name === "enter") return [{ type: "confirmDialog" }];
+    if (name === "escape") return [{ type: "closeOverlay" }];
+    return [];
+  }
+  // a text prompt: the focused input owns typing; only ⏎ save and esc route here
+  if (state.overlay === "prompt") {
+    if (name === "return" || name === "enter") return [{ type: "confirmDialog" }];
+    if (name === "escape") return [{ type: "closeOverlay" }];
+    return [];
+  }
+  // the quick-actions list owns its keys: j/k move, ⏎ picks the highlighted
+  // action (inserting its preset comment), escape returns to the span toolbar
+  if (state.overlay === "spanActions") {
+    if (name === "j" || name === "down") return [{ type: "moveSpanAction", direction: 1 }];
+    if (name === "k" || name === "up") return [{ type: "moveSpanAction", direction: -1 }];
+    if (name === "return" || name === "enter") return [{ type: "pickSpanAction" }];
+    if (name === "escape") return [{ type: "closeSpanActions" }];
+    return [];
+  }
+  if (state.overlay === "completion-prompt" || state.overlay === "completion-counting") {
+    if (name === "return" || name === "enter" || name === "q") return [{ type: "finishReview" }];
+    if (name === "a") return [{ type: "optInAutoClose" }];
+    if (name === "escape") return [{ type: "dismissCompletion" }];
+    return [];
+  }
+  // the walk wizard owns its keys while active: ] advances (marking the
+  // current file viewed), [ steps back, escape leaves keeping progress, and
+  // return on the end card hands over to the submit confirm
+  if (state.overlay === "walk") {
+    if (name === "]") return [{ type: "walkForward" }];
+    if (name === "[") return [{ type: "walkBack" }];
+    if (name === "escape") return [{ type: "walkLeave" }];
+    if ((name === "return" || name === "enter") && state.walkAtEnd) {
+      return [{ type: "walkLeave" }, { type: "openSubmit" }];
+    }
+    if (name === "q") return [{ type: "exit" }];
+    return [];
+  }
+  const action = resolvedAction ?? actionFor(state.keys, name, key.shift);
+  if (action === "quit") return [{ type: "exit" }];
+  // the ONE read-only rule: any mutating attempt answers instead of acting
+  // (span-mode c, x, and a are hardwired keys, so they gate by name as well)
+  const mutating =
+    MUTATING_ACTIONS.has(action ?? "") ||
+    (state.spanMode && (name === "c" || name === "x" || name === "a"));
+  if (state.readOnly && mutating) return status("observer - read-only");
+
+  // share is a session-level verb: it works from any view, owner only
+  if (action === "share") {
+    if (state.canShare === false) return status("only the plan owner can share");
+    return [{ type: "share" }];
+  }
+
+  if (state.view === "inbox") return inboxGrammar(state, name);
+  // span mode owns its single-letter keys (b slides the span back) before the
+  // review-panel controls claim them
+  if (state.spanMode) return spanGrammar(state, name);
+  // the review panel rides both plan and diff reviews; collapsing and resizing
+  // are view state, so the read-only gate above lets them through
+  const reviewPanel = reviewPanelGrammar(action);
+  if (reviewPanel) return reviewPanel;
+  if (state.view === "diff") return diffGrammar(state, action);
+  return planGrammar(state, action, name);
+}
+
+/** The review-panel controls: cycle the mode, widen and narrow the rail. */
+function reviewPanelGrammar(action: string | undefined): Intent[] | null {
+  if (action === "review_cycle") return [{ type: "cycleReviewPanel" }];
+  if (action === "review_wider") return [{ type: "resizeReviewPanel", direction: 1 }];
+  if (action === "review_narrower") return [{ type: "resizeReviewPanel", direction: -1 }];
+  return null;
+}
+
+function inboxGrammar(state: KeyState, name: string): Intent[] {
+  if (!state.hasInboxItems) return [];
+  if (name === "j" || name === "down") return [{ type: "inboxMove", to: "down" }];
+  if (name === "k" || name === "up") return [{ type: "inboxMove", to: "up" }];
+  if (name === "return" || name === "enter") return [{ type: "openSession" }];
+  if (name === "d") return [{ type: "requestDeleteSession" }];
+  return [];
+}
+
+function diffGrammar(state: KeyState, action: string | undefined): Intent[] {
+  const navigation = navigationIntent(action);
+  if (navigation) return navigation;
+  if (action === "walk") {
+    // marking viewed writes the session record, so a resolved review answers
+    if (state.resolved) return status("review submitted - read-only");
+    return [{ type: "walkStart" }];
+  }
+  if (action === "comment") {
+    if (state.resolved) return status("review submitted - read-only");
+    if (!state.cursorAnnotatable) return status("move to a code line to comment");
+    return [{ type: "openCompose", kind: "comment", from: "cursor" }];
+  }
+  // cut rejects the change under the cursor, reject_hunk the whole hunk; both
+  // write the working copy, so they gate on owner like a plan edit.
+  if (action === "cut" || action === "reject_hunk") {
+    if (state.resolved) return status("review submitted - read-only");
+    if (state.canEditPlan === false) return status("only the diff owner can curate hunks");
+    return [{ type: action === "reject_hunk" ? "rejectHunk" : "rejectChange" }];
+  }
+  // restore un-does a curated-out rejection from the rail; same owner gate as reject
+  if (action === "restore_curation") {
+    if (state.resolved) return status("review submitted - read-only");
+    if (state.canEditPlan === false) return status("only the diff owner can curate hunks");
+    return [{ type: "restoreCuration" }];
+  }
+  const shared = annotationCluster(state, action);
+  if (shared) return shared;
+  if (action === "span" || action === "edit") {
+    return status("plan-only verb - diff review uses c on a line");
+  }
+  return [];
+}
+
+function spanGrammar(state: KeyState, name: string): Intent[] {
+  if (name === "escape") return [{ type: "closeOverlay" }];
+  if (SPAN_KEYS.has(name)) return [{ type: "spanKey", name }];
+  // c comments, x cuts, a opens quick-actions - all mutate, so a resolved
+  // review is read-only, like the plan grammar
+  if (name === "c" || name === "x" || name === "a") {
+    if (state.resolved) return status("review submitted - read-only");
+    if (name === "c") return [{ type: "openCompose", kind: "comment", from: "span" }];
+    if (name === "a") return [{ type: "openSpanActions" }];
+    // partial-span cut is not in the working-copy model, so cut removes the
+    // whole block the span sits in; owner-only, like plan cut
+    if (state.canEditPlan === false) return [];
+    return [{ type: "spanCut" }];
+  }
+  return [];
+}
+
+function planGrammar(state: KeyState, action: string | undefined, name: string): Intent[] {
+  const navigation = navigationIntent(action);
+  if (navigation) return navigation;
+  if (action === "walk") return status("the guided walk is a diff-review mode");
+  if (name === "escape") return [{ type: "deselect" }];
+  if (action === "span") return state.cursorAnnotatable ? [{ type: "startSpan" }] : [];
+  if (action === "comment") {
+    if (state.resolved) return status("review submitted - read-only");
+    if (!state.cursorAnnotatable) return status("text is cut - restore it first");
+    return [{ type: "openCompose", kind: "comment", from: "cursor" }];
+  }
+  // restore un-does a rail removal (a cut block); a plan edit, so owner-only
+  if (action === "restore_curation") {
+    if (state.resolved) return status("review submitted - read-only");
+    if (state.canEditPlan === false) return [];
+    return [{ type: "restoreCuration" }];
+  }
+  if (action === "cut" || action === "edit") {
+    if (state.resolved) return status("review submitted - read-only");
+    // the document selects, the rail edits: with a card selected, Cut deletes
+    // the annotation and edit rewrites the card body in place
+    if (state.hasFocusedAnnotation)
+      return [action === "cut" ? { type: "removeAnnotation" } : { type: "editCard" }];
+    // editing the plan itself is the owner's verb; a share viewer only annotates,
+    // and has no edit affordance, so the key is silent rather than a nag
+    if (state.canEditPlan === false) return [];
+    return [{ type: action }];
+  }
+  return annotationCluster(state, action) ?? [];
+}
+
+/** Cursor movement is the same intent everywhere; views clamp their own bounds. */
+function navigationIntent(action: string | undefined): Intent[] | null {
+  if (action === "down" || action === "up" || action === "top" || action === "bottom") {
+    return [{ type: "move", to: action }];
+  }
+  return null;
+}
+
+/** Annotation navigation, deletion, and submit: one path for plan and diff. */
+function annotationCluster(state: KeyState, action: string | undefined): Intent[] | null {
+  if (action === "next_annotation" || action === "prev_annotation") {
+    if (!state.annotationCount) return status("no annotations");
+    return [{ type: action === "next_annotation" ? "nextAnnotation" : "prevAnnotation" }];
+  }
+  if (action === "delete_annotation") {
+    if (state.resolved || !state.hasFocusedAnnotation) return [];
+    return [{ type: "removeAnnotation" }];
+  }
+  if (action === "rename") {
+    if (!state.hasFocusedAnnotation) return status("select a collaborator's note to rename them");
+    return [{ type: "openRename" }];
+  }
+  if (action === "submit") {
+    // a collaborator's notes union back as they go; there is no verdict to submit
+    if (state.canSubmitVerdict === false)
+      return status("shared view - your notes save as you go; q to leave");
+    return state.resolved ? [] : [{ type: "openSubmit" }];
+  }
+  return null;
+}

package/src/review-panel.test.ts

@@ -0,0 +1,113 @@
+import { describe, expect, test } from "bun:test";
+import {
+  REVIEW_DEFAULT_WIDTH,
+  REVIEW_MAX_WIDTH,
+  REVIEW_MIN_WIDTH,
+  REVIEW_PLAN_MIN_WIDTH,
+  REVIEW_RESIZE_STEP,
+  clampWidth,
+  cycleReviewPanelMode,
+  maxWidthForTerminal,
+  resolveReviewWidth,
+  reviewRowsToDivider,
+  toggleReviewPanelMode,
+  widthFromMouseColumn,
+} from "./review-panel";
+
+describe("clampWidth", () => {
+  test("keeps a width inside the bounds untouched", () => {
+    expect(clampWidth(REVIEW_DEFAULT_WIDTH)).toBe(REVIEW_DEFAULT_WIDTH);
+  });
+
+  test("clamps below the minimum and above the maximum", () => {
+    expect(clampWidth(REVIEW_MIN_WIDTH - 10)).toBe(REVIEW_MIN_WIDTH);
+    expect(clampWidth(REVIEW_MAX_WIDTH + 10)).toBe(REVIEW_MAX_WIDTH);
+  });
+
+  test("rounds a fractional column to a whole one", () => {
+    expect(clampWidth(30.7)).toBe(31);
+  });
+
+  test("honors explicit bounds", () => {
+    expect(clampWidth(100, 10, 20)).toBe(20);
+    expect(clampWidth(5, 10, 20)).toBe(10);
+  });
+});
+
+describe("cycleReviewPanelMode", () => {
+  test("cycles expanded -> compact -> hidden -> expanded", () => {
+    expect(cycleReviewPanelMode("expanded")).toBe("compact");
+    expect(cycleReviewPanelMode("compact")).toBe("hidden");
+    expect(cycleReviewPanelMode("hidden")).toBe("expanded");
+  });
+});
+
+describe("toggleReviewPanelMode", () => {
+  test("the chevron toggles only between expanded and compact, never hidden", () => {
+    expect(toggleReviewPanelMode("expanded")).toBe("compact");
+    expect(toggleReviewPanelMode("compact")).toBe("expanded");
+    // a hidden panel has no chevron; a stray toggle still opens it
+    expect(toggleReviewPanelMode("hidden")).toBe("expanded");
+  });
+});
+
+describe("widthFromMouseColumn", () => {
+  test("measures the rail from the mouse column to the right edge", () => {
+    // divider dragged to column 80 of a 120-wide terminal -> a 40-col rail
+    expect(widthFromMouseColumn(80, 120)).toBe(40);
+  });
+
+  test("clamps the dragged width to the bounds", () => {
+    expect(widthFromMouseColumn(0, 120)).toBe(REVIEW_MAX_WIDTH);
+    expect(widthFromMouseColumn(119, 120)).toBe(REVIEW_MIN_WIDTH);
+  });
+
+  test("cannot drag the rail wide enough to starve the plan on a narrow terminal", () => {
+    // dragging to the far left edge of a 60-col terminal still leaves the plan its minimum
+    expect(widthFromMouseColumn(0, 60)).toBe(60 - REVIEW_PLAN_MIN_WIDTH - 1);
+  });
+
+  test("the resize step widens and narrows within the clamp", () => {
+    expect(clampWidth(REVIEW_DEFAULT_WIDTH + REVIEW_RESIZE_STEP)).toBe(
+      REVIEW_DEFAULT_WIDTH + REVIEW_RESIZE_STEP,
+    );
+    expect(clampWidth(REVIEW_MIN_WIDTH - REVIEW_RESIZE_STEP)).toBe(REVIEW_MIN_WIDTH);
+  });
+});
+
+describe("maxWidthForTerminal", () => {
+  test("allows the full rail on a wide terminal", () => {
+    expect(maxWidthForTerminal(120)).toBe(REVIEW_MAX_WIDTH);
+  });
+
+  test("reserves the plan its minimum on a narrow terminal", () => {
+    // 60-col terminal: 30 for the plan and 1 for the divider leaves 29 for the rail
+    expect(maxWidthForTerminal(60)).toBe(60 - REVIEW_PLAN_MIN_WIDTH - 1);
+  });
+
+  test("never drops below the rail minimum, however narrow the terminal", () => {
+    expect(maxWidthForTerminal(40)).toBe(REVIEW_MIN_WIDTH);
+  });
+});
+
+describe("resolveReviewWidth", () => {
+  test("leaves a width that already fits untouched", () => {
+    expect(resolveReviewWidth(REVIEW_DEFAULT_WIDTH, 120)).toBe(REVIEW_DEFAULT_WIDTH);
+  });
+
+  test("shrinks a wide persisted width so the plan keeps its room", () => {
+    // a saved 50-col rail on a 60-col terminal would leave the plan 9 cols; clamp it back
+    expect(resolveReviewWidth(REVIEW_MAX_WIDTH, 60)).toBe(60 - REVIEW_PLAN_MIN_WIDTH - 1);
+  });
+});
+
+describe("reviewRowsToDivider", () => {
+  test("builds one vertical glyph per row", () => {
+    expect(reviewRowsToDivider(3)).toBe("│\n│\n│");
+  });
+
+  test("never collapses to an empty column", () => {
+    expect(reviewRowsToDivider(0)).toBe("│");
+    expect(reviewRowsToDivider(-4)).toBe("│");
+  });
+});

package/src/review-panel.ts

@@ -0,0 +1,83 @@
+/**
+ * Pure geometry and state for the resizable review panel. The panel shows the
+ * review rail in one of three modes and the expanded rail resizes within a
+ * clamp; App owns the React state and the mouse wiring, this module owns the
+ * arithmetic so the layout math stays unit-tested and out of the JSX. Bounds
+ * and the compact width carry over verbatim from the approved prototype.
+ */
+
+/** Expanded (full rail), compact (count + dots strip), or hidden (nothing). */
+export type ReviewPanelMode = "expanded" | "compact" | "hidden";
+
+/** Expanded-rail width bounds, in terminal columns. */
+export const REVIEW_MIN_WIDTH = 24;
+export const REVIEW_MAX_WIDTH = 50;
+export const REVIEW_DEFAULT_WIDTH = 34;
+/**
+ * Columns the plan/diff column keeps for itself: the expanded rail yields past
+ * this so a narrow terminal (or a wide persisted width) can never crowd the
+ * plan out to nothing - the whole reason the panel is resizable. On terminals
+ * wide enough for the full 50-col rail this bound never binds.
+ */
+export const REVIEW_PLAN_MIN_WIDTH = 30;
+/** The compact strip is a fixed narrow column: count on top, one dot per card. */
+export const REVIEW_COMPACT_WIDTH = 6;
+/** Keyboard resize step, in columns, for the widen/narrow keys. */
+export const REVIEW_RESIZE_STEP = 2;
+
+/** Round a desired width to a whole column and clamp it to the bounds. */
+export function clampWidth(
+  desiredWidth: number,
+  min = REVIEW_MIN_WIDTH,
+  max = REVIEW_MAX_WIDTH,
+): number {
+  return Math.max(min, Math.min(max, Math.round(desiredWidth)));
+}
+
+/**
+ * The widest the expanded rail may be on a given terminal, reserving the plan
+ * its minimum and one column for the divider. Never drops below REVIEW_MIN_WIDTH
+ * (an extremely narrow terminal is the auto-collapse case, handled elsewhere).
+ */
+export function maxWidthForTerminal(terminalWidth: number): number {
+  return Math.max(
+    REVIEW_MIN_WIDTH,
+    Math.min(REVIEW_MAX_WIDTH, terminalWidth - REVIEW_PLAN_MIN_WIDTH - 1),
+  );
+}
+
+/** Clamp a desired rail width to the bounds AND the terminal, so the plan keeps its room. */
+export function resolveReviewWidth(desiredWidth: number, terminalWidth: number): number {
+  return clampWidth(desiredWidth, REVIEW_MIN_WIDTH, maxWidthForTerminal(terminalWidth));
+}
+
+/** The keybinding cycle: expanded -> compact -> hidden -> expanded. */
+export function cycleReviewPanelMode(mode: ReviewPanelMode): ReviewPanelMode {
+  return mode === "expanded" ? "compact" : mode === "compact" ? "hidden" : "expanded";
+}
+
+/**
+ * The clickable chevron toggles only between expanded and compact - hidden is
+ * reachable by keybinding alone, so it never leaves a leftover tab behind. A
+ * toggle from hidden still opens the panel rather than doing nothing.
+ */
+export function toggleReviewPanelMode(mode: ReviewPanelMode): ReviewPanelMode {
+  return mode === "expanded" ? "compact" : "expanded";
+}
+
+/**
+ * Rail width from an absolute mouse column while dragging the divider: the rail
+ * spans from the mouse column to the terminal's right edge, then clamps.
+ */
+export function widthFromMouseColumn(mouseColumn: number, terminalWidth: number): number {
+  return resolveReviewWidth(terminalWidth - mouseColumn, terminalWidth);
+}
+
+/**
+ * The divider is a single-column stack of vertical glyphs (a text block, not a
+ * bordered box - a one-column box with a border renders a full box). One glyph
+ * per row, at least one so the column never collapses.
+ */
+export function reviewRowsToDivider(rows: number): string {
+  return Array.from({ length: Math.max(1, rows) }, () => "│").join("\n");
+}

package/src/run.ts

@@ -10,17 +10,21 @@ export interface RunClientOptions {
   home?: string;
 }
 
-export async function runClient(opts: RunClientOptions): Promise<number> {
-  const renderer = await createCliRenderer();
+export async function runClient(options: RunClientOptions): Promise<number> {
+  // mouse movement reporting makes multiplexers forward drags to the app,
+  // so the renderer's native selection is the drag driver
+  const renderer = await createCliRenderer({ enableMouseMovement: true });
   return new Promise<number>((resolve) => {
     createRoot(renderer).render(
       React.createElement(App, {
-        home: opts.home,
-        sessionId: opts.sessionId,
+        home: options.home,
+        sessionId: options.sessionId,
         onExit: (code: number) => {
           renderer.destroy();
           resolve(code);
-          process.exit(code);
+          // one microtask between destroy and exit lets the renderer flush
+          // its terminal-restore sequences before the process dies
+          queueMicrotask(() => process.exit(code));
         },
       }),
     );

package/src/serve.test.ts

@@ -38,7 +38,11 @@ afterEach(async () => {
 });
 
 /** Connect, open a PTY shell, resolve with the bytes seen until `until` matches. */
-function sshCapture(port: number, until: (s: string) => boolean, timeoutMs = 8000): Promise<string> {
+function sshCapture(
+  port: number,
+  until: (frame: string) => boolean,
+  timeoutMs = 8000,
+): Promise<string> {
   return new Promise((resolve, reject) => {
     const conn = new Client();
     let out = "";
@@ -48,15 +52,16 @@ function sshCapture(port: number, until: (s: string) => boolean, timeoutMs = 800
       done = true;
       clearTimeout(timer);
       conn.end();
-      err ? reject(err) : resolve(out);
+      if (err) reject(err);
+      else resolve(out);
     };
     const timer = setTimeout(() => finish(new Error(`timed out; captured:\n${out}`)), timeoutMs);
     conn
       .on("ready", () => {
         conn.shell({ term: "xterm-256color", cols: 100, rows: 30 }, (err, stream) => {
           if (err) return finish(err);
-          stream.on("data", (d: Buffer) => {
-            out += d.toString("utf8");
+          stream.on("data", (chunk: Buffer) => {
+            out += chunk.toString("utf8");
             if (until(out)) finish();
           });
           stream.on("close", () => finish(new Error(`stream closed early; captured:\n${out}`)));
@@ -70,6 +75,7 @@ function sshCapture(port: number, until: (s: string) => boolean, timeoutMs = 800
 
 describe("cueloop serve", () => {
   test("listens on localhost, persists a host key under CUELOOP_HOME/ssh", () => {
+    // Assert
     expect(handle.host).toBe("127.0.0.1");
     expect(handle.port).toBeGreaterThan(0);
     expect(handle.fingerprints.length).toBe(1);
@@ -78,18 +84,27 @@ describe("cueloop serve", () => {
   });
 
   test("an anonymous ssh client gets the observer TUI for the session", async () => {
-    const bytes = await sshCapture(handle.port, (s) => s.includes("Rollout Plan") && s.includes("observer"));
+    // Act
+    const bytes = await sshCapture(
+      handle.port,
+      (frame) => frame.includes("Rollout Plan") && frame.includes("observer"),
+    );
+
+    // Assert
     expect(bytes).toContain("cueloop");
     expect(bytes).toContain("Rollout Plan");
-    // observer chrome, not the controller's mutating hint bar
-    expect(bytes).toContain("observer - read-only");
+    // observer chrome: the header badge marks the read-only session
+    expect(bytes).toContain("observer");
   });
 
   test("two observers can watch at once", async () => {
+    // Act
     const [a, b] = await Promise.all([
-      sshCapture(handle.port, (s) => s.includes("Rollout Plan")),
-      sshCapture(handle.port, (s) => s.includes("Rollout Plan")),
+      sshCapture(handle.port, (frame) => frame.includes("Rollout Plan")),
+      sshCapture(handle.port, (frame) => frame.includes("Rollout Plan")),
     ]);
+
+    // Assert
     expect(a).toContain("Rollout Plan");
     expect(b).toContain("Rollout Plan");
   });

package/src/serve.ts

@@ -1,5 +1,5 @@
 /**
- * SSH-served TUI (#22 share path): `cueloop serve` lets teammates join a
+ * SSH-served TUI: `cueloop serve` lets teammates join a
  * review session over plain ssh. Every SSH connection renders <App> in
  * observer mode (readOnly) against the same local daemon; the one writable
  * controller stays the local owner's own `cueloop` TUI.
@@ -44,8 +44,8 @@ export interface ServeHandle {
   close(): Promise<void>;
 }
 
-export async function serveClient(opts: ServeOptions = {}): Promise<ServeHandle> {
-  const home = opts.home ?? cueloopHome();
+export async function serveClient(options: ServeOptions = {}): Promise<ServeHandle> {
+  const home = options.home ?? cueloopHome();
   const sshDir = join(home, "ssh");
   mkdirSync(sshDir, { recursive: true, mode: 0o700 });
 
@@ -53,15 +53,15 @@ export async function serveClient(opts: ServeOptions = {}): Promise<ServeHandle>
     // password-less by design; see the trust model in the module comment
     auth: "open",
     hostKey: { path: join(sshDir, "host_key") },
-    startupBanner: opts.banner ?? true,
+    startupBanner: options.banner ?? true,
     idleTimeout: "2h",
-    onError: opts.onError,
+    onError: options.onError,
   }).serve((session) => {
     const root = createRoot(session.renderer);
     root.render(
       React.createElement(App, {
         home,
-        sessionId: opts.sessionId,
+        sessionId: options.sessionId,
         readOnly: true,
         // q disconnects only this observer, never the server
         onExit: () => session.end(),
@@ -70,6 +70,6 @@ export async function serveClient(opts: ServeOptions = {}): Promise<ServeHandle>
     session.onClose(() => root.unmount());
   });
 
-  const info = await server.listen(opts.port ?? 2222, opts.host ?? "127.0.0.1");
+  const info = await server.listen(options.port ?? 2222, options.host ?? "127.0.0.1");
   return { ...info, close: () => server.close() };
 }