feat(desktop): support the Work Louder Codex Micro#23869

@@ -0,0 +1,280 @@
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
+import * as Random from "effect/Random";
+import * as Schedule from "effect/Schedule";
+import * as Schema from "effect/Schema";
+import * as Semaphore from "effect/Semaphore";
+import { devicesAsync as listHidDevices, HIDAsync } from "node-hid";

@@ -0,0 +1,280 @@
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
+import * as Random from "effect/Random";
+import * as Schedule from "effect/Schedule";
+import * as Schema from "effect/Schema";
+import * as Semaphore from "effect/Semaphore";
+import { devicesAsync as listHidDevices, HIDAsync } from "node-hid";
+
+import {
+  DISCONNECTED_CODEX_MICRO_STATE,
+  type CodexMicroDeviceState,
+  type CodexMicroEvent,
+  type CodexMicroLighting,
+} from "@t3tools/contracts";
+
+import {
+  CHANNEL_RPC,
+  CODEX_MICRO_PRODUCT_ID,
+  decodeReport,
+  encodeRpcRequest,
+  isDeepEqual,
+  LineAssembler,
+  MAX_RPC_ID,
+  NOTIFY_METHODS,
+  parseRpcLine,
+  RPC_METHODS,
+  VENDOR_USAGE_PAGE,
+  WORK_LOUDER_VENDOR_ID,
+} from "./CodexMicroProtocol.ts";
+import { lightingFrame } from "./CodexMicroLighting.ts";
+
+export class CodexMicroError extends Schema.TaggedError<CodexMicroError>()("CodexMicroError", {
+  message: Schema.String,
+  cause: Schema.optional(Schema.Defect()),
+}) {}
+
+const MAX_CONSECUTIVE_FAILURES = 3;
+
+export interface CodexMicroDevice {
+  readonly getState: Effect.Effect<CodexMicroDeviceState>;
+  readonly setLighting: (lighting: CodexMicroLighting) => Effect.Effect<void>;
+}
+
+// Enumeration is async so polling never blocks the main process.
+const findDevicePath = Effect.tryPromise({
+  try: () => listHidDevices(),
+  catch: (cause) => new CodexMicroError({ message: "Could not list HID devices", cause }),
+}).pipe(
+  Effect.map(
+    (devices) =>
+      devices.find(
+        (device) =>
+          device.vendorId === WORK_LOUDER_VENDOR_ID &&
+          device.productId === CODEX_MICRO_PRODUCT_ID &&
+          device.usagePage === VENDOR_USAGE_PAGE,
+      )?.path ?? null,
+  ),
+);
+
+/**
+ * Owns one Codex Micro for the lifetime of the scope: discovery, reconnects,
+ * serialized JSON-RPC (the firmware handles one request at a time), lighting
+ * with auto-dim, and key/joystick notifications.
+ */
+export const makeCodexMicroDevice = Effect.fn("desktop.codexMicro.makeDevice")(function* (
+  onEvent: (event: CodexMicroEvent) => void,
+) {
+  const runFork = Effect.runForkWith(yield* Effect.context<never>());
+  const rpcLock = yield* Semaphore.make(1);
+  const lines = new LineAssembler();
+  const pending = new Map<string, Deferred.Deferred<unknown, CodexMicroError>>();
+
+  let hid: HIDAsync | null = null;
+  let state: CodexMicroDeviceState = DISCONNECTED_CODEX_MICRO_STATE;
+  let lighting: CodexMicroLighting | null = null;
+  let lightsOff = false;
+  let appliedFrame: ReturnType<typeof lightingFrame> | null = null;
+  let dimFiber: Fiber.Fiber<void> | null = null;
+
+  const setState = (next: CodexMicroDeviceState) => {
+    if (isDeepEqual(next, state)) return;
+    state = next;
+    onEvent({ type: "state", state });
+  };
+
+  const send = Effect.fn("desktop.codexMicro.send")(function* (method: string, params: unknown) {
+    const device = hid;
+    if (!device) return yield* new CodexMicroError({ message: "Codex Micro is not connected" });
+    const id = yield* Random.nextIntBetween(0, MAX_RPC_ID);
+    const response = yield* Deferred.make<unknown, CodexMicroError>();
+    pending.set(String(id), response);
+    return yield* Effect.gen(function* () {
+      for (const report of encodeRpcRequest(method, params, id)) {
+        yield* Effect.tryPromise({
+          try: () => device.write(Buffer.from(report)),
+          catch: (cause) => new CodexMicroError({ message: `Codex Micro write failed`, cause }),
+        });
+      }
+      return yield* Deferred.await(response).pipe(
+        Effect.timeoutOrElse({
+          duration: "5 seconds",
+          orElse: () =>
+            Effect.fail(new CodexMicroError({ message: `Codex Micro ${method} timed out` })),
+        }),
+      );
+    }).pipe(Effect.ensuring(Effect.sync(() => pending.delete(String(id)))));
+  });
+
+  // A short cooldown between requests keeps the firmware's parser happy.
+  // A handle can go dead without a read error (sleep/wake, a dropped Bluetooth
+  // link). Treat a run of failed requests as a disconnect so discovery reopens it.
+  let consecutiveFailures = 0;
+  const call = (method: string, params: unknown) =>
+    rpcLock.withPermits(1)(
+      send(method, params).pipe(
+        Effect.tap(() => Effect.sync(() => (consecutiveFailures = 0))),
+        Effect.tapError(() =>
+          Effect.suspend(() =>
+            ++consecutiveFailures >= MAX_CONSECUTIVE_FAILURES ? disconnect : Effect.void,
+          ),
+        ),
+        Effect.ensuring(Effect.sleep("15 millis")),
+      ),
+    );
+
+  const applyLighting = Effect.gen(function* () {
+    if (!hid || !lighting) return;
+    const frame = lightingFrame(lighting, lightsOff);
+    if (isDeepEqual(frame, appliedFrame)) return;
+    appliedFrame = frame;
+    yield* call(RPC_METHODS.lightingConfig, frame.zones);
+    yield* call(RPC_METHODS.slotLighting, frame.slots);
+  }).pipe(
+    Effect.catch((error) =>
+      Effect.sync(() => {
+        appliedFrame = null;
+      }).pipe(Effect.andThen(Effect.logWarning("Codex Micro lighting update failed", error))),
+    ),
+  );
+
+  /** Input or a lighting change restores the lights and restarts auto-dim. */
+  const wake = () => {
+    if (dimFiber) runFork(Fiber.interrupt(dimFiber));
+    dimFiber = null;
+    const autoDimMs = lighting?.autoDimMs;
+    if (autoDimMs) {
+      dimFiber = runFork(
+        Effect.sleep(autoDimMs).pipe(
+          Effect.andThen(Effect.sync(() => (lightsOff = true))),
+          Effect.andThen(applyLighting),
+        ),
+      );
+    }
+    if (lightsOff) {
+      lightsOff = false;
+      runFork(applyLighting);
+    }
+  };
+
+  const onData = (data: Buffer) => {
+    const report = decodeReport(data);
+    if (!report || report.channel !== CHANNEL_RPC) return;
+    for (const line of lines.push(report)) {
+      const message = parseRpcLine(line);
+      if (!message) continue;
+      if (message.kind === "response") {
+        const response = pending.get(message.id);
+        if (!response) continue;
+        runFork(
+          message.error
+            ? Deferred.fail(response, new CodexMicroError({ message: message.error }))
+            : Deferred.succeed(response, message.result),
+        );
+        continue;
+      }
+      const { method, params } = message;
+      if (method === NOTIFY_METHODS.key) {
+        wake();
+        const act = typeof params.act === "number" ? params.act : null;
+        onEvent({ type: "input", input: { type: "key", key: String(params.k), act } });
+      } else if (method === NOTIFY_METHODS.joystick) {
+        const distance = Number(params.d);
+        if (distance > 0.1) wake();
+        onEvent({ type: "input", input: { type: "joystick", angle: Number(params.a), distance } });
+      }
+    }
+  };
+
+  const disconnect: Effect.Effect<void> = Effect.gen(function* () {
+    const device = hid;
+    consecutiveFailures = 0;
+    hid = null;
+    lines.reset();
+    for (const response of pending.values()) {
+      yield* Deferred.fail(response, new CodexMicroError({ message: "Codex Micro disconnected" }));
+    }
+    pending.clear();
+    if (device) yield* Effect.promise(() => device.close()).pipe(Effect.ignore);

@@ -2477,3 +2495,41 @@ code {
     }
   }
 }
+
+/* Codex Micro preview materials, matching the device and Codex's own preview. */
+:root {
+  --micro-body: #ebe8e2;
+  --micro-cap: #f7f5f1;
+  --micro-knob: #f5f3ee;
+  --micro-stick-housing: #dad4ca;
+  --micro-stick: #111111;
+  --micro-touch: #2d2925;
+  --micro-dot: rgb(104 95 174 / 85%);
+  --micro-glow: #8db5ff;
+  --micro-led: #b8b98b;
+  --micro-led-active: #9ebdff;
+  --micro-shadow-body: inset 0 0 0 1px rgb(255 255 255 / 72%), 0 1px 0 rgb(255 255 255 / 65%);
+  --micro-shadow-cap: inset 0 0 0 1px rgb(228 228 228 / 68%), 0 1px 2px rgb(79 72 63 / 18%);
+  --micro-shadow-agent:
+    inset 0 0 0 1px rgb(228 228 228 / 40%), inset 0 1px 2px rgb(255 255 255 / 50%),
+    0 1px 2px rgb(79 72 63 / 16%);
+  --micro-shadow-knob: inset 0 -1px 2px rgb(92 84 72 / 16%), 0 1px 2px rgb(89 80 67 / 18%);
+  --micro-shadow-stick: inset 0 -1px 2px rgb(255 255 255 / 12%), 0 1px 2px rgb(44 40 35 / 28%);
+  --micro-shadow-dot: 0 0 5px rgb(87 76 151 / 42%);
+}
+
+.dark {
+  --micro-body: #18191e;
+  --micro-cap: #202127;
+  --micro-knob: #262831;
+  --micro-stick-housing: #23252c;
+  --micro-touch: #202127;
+  --micro-dot: rgb(129 119 200 / 90%);
+  --micro-shadow-body: inset 0 0 0 1px rgb(255 255 255 / 8%), 0 1px 0 rgb(0 0 0 / 28%);
+  --micro-shadow-cap: inset 0 0 0 1px rgb(255 255 255 / 8%), 0 1px 2px rgb(0 0 0 / 32%);
+  --micro-shadow-agent:
+    inset 0 0 0 1px rgb(255 255 255 / 9%), inset 0 1px 2px rgb(255 255 255 / 8%),
+    0 1px 2px rgb(0 0 0 / 30%);
+  --micro-shadow-knob: inset 0 -1px 2px rgb(255 255 255 / 8%), 0 1px 2px rgb(0 0 0 / 34%);
+  --micro-shadow-dot: 0 0 6px rgb(118 104 197 / 50%);
+}

@@ -0,0 +1,113 @@
+import {
+  DISCONNECTED_CODEX_MICRO_STATE,
+  type CodexMicroDeviceState,
+  type CodexMicroInputEvent,
+} from "@t3tools/contracts";
+import { useSyncExternalStore } from "react";
+
+import { EMPTY_CODEX_MICRO_SLOTS, type CodexMicroSlot } from "./codexMicroSlots";
+
+/**
+ * Renderer-side Codex Micro state shared by the headless coordinator (which
+ * owns slots and selection) and the settings page (which previews them).
+ */
+export interface CodexMicroSnapshot {
+  /** False until the main process has reported the device state once. */
+  readonly loaded: boolean;
+  readonly device: CodexMicroDeviceState;
+  readonly slots: ReadonlyArray<CodexMicroSlot>;
+  readonly selectedSlot: number | null;
+  readonly pressedKeys: ReadonlySet<string>;
+  readonly joystick: { readonly angle: number; readonly distance: number };
+}
+
+let snapshot: CodexMicroSnapshot = {
+  loaded: false,
+  device: DISCONNECTED_CODEX_MICRO_STATE,
+  slots: EMPTY_CODEX_MICRO_SLOTS,
+  selectedSlot: null,
+  pressedKeys: new Set(),
+  joystick: { angle: 0, distance: 0 },
+};
+const listeners = new Set<() => void>();
+const inputListeners = new Set<(input: CodexMicroInputEvent) => void>();
+let unsubscribeBridge: (() => void) | null = null;
+
+const bridge = () => (typeof window === "undefined" ? undefined : window.desktopBridge?.codexMicro);
+
+function update(patch: Partial<CodexMicroSnapshot>) {
+  snapshot = { ...snapshot, ...patch };
+  for (const listener of listeners) listener();
+}
+
+function handleInput(input: CodexMicroInputEvent) {
+  if (input.type === "joystick") {
+    update({ joystick: { angle: input.angle, distance: input.distance } });
+  } else if (input.act === 0 || input.act === 1) {
+    const pressedKeys = new Set(snapshot.pressedKeys);
+    if (input.act === 1) pressedKeys.add(input.key);
+    else pressedKeys.delete(input.key);
+    update({ pressedKeys });
+  }
+  for (const listener of inputListeners) listener(input);
+}
+
+function connectBridge() {
+  const codexMicro = bridge();
+  if (!codexMicro || unsubscribeBridge) return;
+  unsubscribeBridge = codexMicro.onEvent((event) => {
+    if (event.type === "state") {
+      update({
+        loaded: true,
+        device: event.state,
+        ...(event.state.connected ? {} : { pressedKeys: new Set<string>(), selectedSlot: null }),
+      });
+    } else {
+      handleInput(event.input);
+    }
+  });
+  void codexMicro.getState().then((device) => update({ loaded: true, device }));
+}

@@ -0,0 +1,467 @@
+import {
+  CODEX_MICRO_STATUS_COLORS,
+  DEFAULT_CODEX_MICRO_CONTROLS,
+  type CodexMicroAction,
+  type CodexMicroAgentMode,
+  type CodexMicroControlId,
+  type CodexMicroKnobMode,
+  type CodexMicroSettings,
+} from "@t3tools/contracts";
+import { Navigate } from "@tanstack/react-router";
+import type { ReactNode } from "react";
+
+import {
+  CODEX_MICRO_ACTION_GROUPS,
+  codexMicroActionKey,
+  describeCodexMicroAction,
+  resolveCodexMicroControl,
+} from "../../codexMicro/codexMicroActions";
+import { useCodexMicroSnapshot } from "../../codexMicro/codexMicroStore";
+import {
+  getClientSettings,
+  updateClientSettings,
+  useClientSettings,
+} from "../../hooks/useSettings";
+import { usePrimaryEnvironmentId } from "../../state/environments";
+import { useQuietThreadShells } from "../../state/entities";
+import { Button } from "../ui/button";
+import {
+  Menu,
+  MenuGroup,
+  MenuGroupLabel,
+  MenuPopup,
+  MenuRadioGroup,
+  MenuRadioItem,
+  MenuSeparator,
+  MenuTrigger,
+} from "../ui/menu";
+import { SelectButton } from "../ui/select";
+import { Switch } from "../ui/switch";
+import { CodexMicroActionIcon, CodexMicroDevicePreview } from "./CodexMicroDevicePreview";
+import { SettingsPageContainer, SettingsRow, SettingsSection } from "./settingsLayout";
+
+const AGENT_MODES: ReadonlyArray<{
+  value: CodexMicroAgentMode;
+  label: string;
+  description: string;
+}> = [
+  {
+    value: "priority",
+    label: "Priority threads",
+    description: "Waiting, unread, and active threads first",
+  },
+  { value: "pinned", label: "Pinned threads", description: "First six threads in Pinned" },
+  {
+    value: "recent",
+    label: "Most recent threads",
+    description: "First six recently updated threads",
+  },
+];
+
+const KNOB_MODES: ReadonlyArray<{ value: CodexMicroKnobMode; label: string; description: string }> =
+  [
+    {
+      value: "agents",
+      label: "Agent keys",
+      description: "Turn to choose an agent key, click to open its thread",
+    },
+    {
+      value: "threads",
+      label: "Thread switching",
+      description: "Turn to move between threads, click for the command palette",
+    },
+    { value: "custom", label: "Custom", description: "Choose an action for each turn and click" },
+  ];
+
+const BRIGHTNESS = [0.25, 0.5, 0.8, 1] as const;
+const AUTO_DIM: ReadonlyArray<{ value: number | null; label: string }> = [
+  { value: null, label: "Off" },
+  { value: 60_000, label: "1 minute" },
+  { value: 180_000, label: "3 minutes" },
+  { value: 600_000, label: "10 minutes" },
+  { value: 1_800_000, label: "30 minutes" },
+  { value: 3_600_000, label: "1 hour" },
+];
+
+const STATUS_LEGEND = [
+  ["working", "Working"],
+  ["needs-input", "Needs you"],
+  ["done", "Unread"],
+  ["error", "Error"],
+  ["idle", "Idle"],
+] as const;
+
+const COMMAND_KEY_ROWS: ReadonlyArray<[CodexMicroControlId, string, string]> = [
+  ["ACT06", "Key 1", "Third row, left"],
+  ["ACT07", "Key 2", "Third row"],
+  ["ACT08", "Key 3", "Third row"],
+  ["ACT09", "Key 4", "Third row, right"],
+  ["ACT10", "Wide key", "Bottom row"],
+  ["ACT11", "Wide key, right switch", "Bottom row"],
+  ["ACT12", "Corner key", "Bottom row, right"],
+];
+const STICK: ReadonlyArray<[CodexMicroControlId, string]> = [
+  ["JOY_UP", "Up"],
+  ["JOY_RIGHT", "Right"],
+  ["JOY_DOWN", "Down"],
+  ["JOY_LEFT", "Left"],
+];
+const KNOB: ReadonlyArray<[CodexMicroControlId, string]> = [
+  ["ENC_CC", "Turn left"],
+  ["ENC_CW", "Turn right"],
+  ["ENC", "Click"],
+];
+
+const controlRowId = (control: CodexMicroControlId) => `codex-micro-${control}`;
+const agentRowId = (index: number) => `codex-micro-agent-${index}`;
+
+function openRowMenu(id: string) {
+  const row = document.getElementById(id);
+  row?.scrollIntoView({ block: "center", behavior: "smooth" });
+  row?.querySelector<HTMLButtonElement>("[data-codex-micro-trigger]")?.click();
+}
+
+// Read the latest stored value so quick successive edits don't overwrite each other.
+const save = (patch: Partial<CodexMicroSettings>) =>
+  void updateClientSettings({ codexMicro: { ...getClientSettings().codexMicro, ...patch } });
+
+function OptionMenu<T>(props: {
+  readonly label: string;
+  readonly value: T;
+  readonly options: ReadonlyArray<{ value: T; label: string }>;
+  readonly onChange: (value: T) => void;
+}) {
+  const index = Math.max(
+    0,
+    props.options.findIndex((option) => option.value === props.value),
+  );
+  return (
+    <Menu>
+      <MenuTrigger
+        aria-label={props.label}
+        render={<SelectButton size="sm" />}
+        className="w-auto min-w-0"
+      >
+        {props.options[index]?.label}
+      </MenuTrigger>
+      <MenuPopup align="end">
+        <MenuRadioGroup
+          value={String(index)}
+          onValueChange={(next) => props.onChange(props.options[Number(next)]!.value)}
+        >
+          {props.options.map((option, i) => (
+            <MenuRadioItem key={option.label} closeOnClick value={String(i)}>

@@ -0,0 +1,315 @@
+import * as Clock from "effect/Clock";
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
+import * as Random from "effect/Random";
+import * as Schedule from "effect/Schedule";
+import * as Schema from "effect/Schema";
+import * as Semaphore from "effect/Semaphore";
+import type { HIDAsync } from "node-hid";
+
+import {
+  DISCONNECTED_CODEX_MICRO_STATE,
+  type CodexMicroDeviceState,
+  type CodexMicroEvent,
+  type CodexMicroLighting,
+} from "@t3tools/contracts";
+
+import {
+  CHANNEL_RPC,
+  type CodexMicroEndpoint,
+  decodeReport,
+  encodeRpcRequest,
+  findEndpoints,
+  isDeepEqual,
+  LineAssembler,
+  MAX_RPC_ID,
+  NOTIFY_METHODS,
+  parseRpcLine,
+  reconcileEndpoint,
+  RPC_METHODS,
+} from "./CodexMicroProtocol.ts";
+import { lightingFrame } from "./CodexMicroLighting.ts";
+
+export class CodexMicroError extends Schema.TaggedError<CodexMicroError>()("CodexMicroError", {
+  message: Schema.String,
+  cause: Schema.optional(Schema.Defect()),
+}) {}
+
+const MAX_CONSECUTIVE_FAILURES = 3;
+
+export interface CodexMicroDevice {
+  readonly getState: Effect.Effect<CodexMicroDeviceState>;
+  readonly setLighting: (lighting: CodexMicroLighting) => Effect.Effect<void>;
+}
+
+// A failed open waits this long before retrying, unless the topology changes.
+const RETRY_AFTER_FAILURE_MS = 10_000;
+
+// node-hid is a native addon: load it on first use so a broken prebuild can
+// only disable the Codex Micro, never stop the desktop app from starting.
+let nodeHid: Promise<typeof import("node-hid")> | null = null;
+const loadNodeHid = Effect.tryPromise({
+  try: () => (nodeHid ??= import("node-hid")),
+  catch: (cause) => new CodexMicroError({ message: "Could not load node-hid", cause }),
+});
+
+// Enumeration is async so polling never blocks the main process.
+const listEndpoints = loadNodeHid.pipe(
+  Effect.flatMap((hidModule) =>
+    Effect.tryPromise({
+      try: () => hidModule.devicesAsync(),
+      catch: (cause) => new CodexMicroError({ message: "Could not list HID devices", cause }),
+    }),
+  ),
+  Effect.map(findEndpoints),
+);
+
+/**
+ * Owns one Codex Micro for the lifetime of the scope: discovery, reconnects,
+ * serialized JSON-RPC (the firmware handles one request at a time), lighting
+ * with auto-dim, and key/joystick notifications.
+ */
+export const makeCodexMicroDevice = Effect.fn("desktop.codexMicro.makeDevice")(function* (
+  onEvent: (event: CodexMicroEvent) => void,
+) {
+  const runFork = Effect.runForkWith(yield* Effect.context<never>());
+  const rpcLock = yield* Semaphore.make(1);
+  const lines = new LineAssembler();
+  const pending = new Map<string, Deferred.Deferred<unknown, CodexMicroError>>();
+
+  let hid: HIDAsync | null = null;
+  let endpoint: CodexMicroEndpoint | null = null;
+  let state: CodexMicroDeviceState = DISCONNECTED_CODEX_MICRO_STATE;
+  let lighting: CodexMicroLighting | null = null;
+  let lightsOff = false;
+  let appliedFrame: ReturnType<typeof lightingFrame> | null = null;
+  let dimFiber: Fiber.Fiber<void> | null = null;
+
+  const setState = (next: CodexMicroDeviceState) => {
+    if (isDeepEqual(next, state)) return;
+    state = next;
+    onEvent({ type: "state", state });
+  };
+
+  const send = Effect.fn("desktop.codexMicro.send")(function* (method: string, params: unknown) {
+    const device = hid;
+    if (!device) return yield* new CodexMicroError({ message: "Codex Micro is not connected" });
+    const id = yield* Random.nextIntBetween(0, MAX_RPC_ID);
+    const response = yield* Deferred.make<unknown, CodexMicroError>();
+    pending.set(String(id), response);
+    return yield* Effect.gen(function* () {
+      for (const report of encodeRpcRequest(method, params, id)) {
+        yield* Effect.tryPromise({
+          try: () => device.write(Buffer.from(report)),
+          catch: (cause) => new CodexMicroError({ message: `Codex Micro write failed`, cause }),

@@ -0,0 +1,474 @@
+import {
+  CODEX_MICRO_STATUS_COLORS,
+  DEFAULT_CODEX_MICRO_CONTROLS,
+  type CodexMicroAction,
+  type CodexMicroAgentMode,
+  type CodexMicroControlId,
+  type CodexMicroKnobMode,
+  type CodexMicroSettings,
+} from "@t3tools/contracts";
+import { Navigate } from "@tanstack/react-router";
+import type { ReactNode } from "react";
+
+import {
+  CODEX_MICRO_ACTION_GROUPS,
+  codexMicroActionKey,
+  describeCodexMicroAction,
+  resolveCodexMicroControl,
+} from "../../codexMicro/codexMicroActions";
+import { useCodexMicroSnapshot } from "../../codexMicro/codexMicroStore";
+import {
+  getClientSettings,
+  updateClientSettings,
+  useClientSettings,
+} from "../../hooks/useSettings";
+import { usePrimaryEnvironmentId } from "../../state/environments";
+import { useQuietThreadShells } from "../../state/entities";
+import { Button } from "../ui/button";
+import {
+  Menu,
+  MenuGroup,
+  MenuGroupLabel,
+  MenuPopup,
+  MenuRadioGroup,
+  MenuRadioItem,
+  MenuSeparator,
+  MenuTrigger,
+} from "../ui/menu";
+import { SelectButton } from "../ui/select";
+import { Switch } from "../ui/switch";
+import { CodexMicroActionIcon, CodexMicroDevicePreview } from "./CodexMicroDevicePreview";
+import { SettingsPageContainer, SettingsRow, SettingsSection } from "./settingsLayout";
+
+const AGENT_MODES: ReadonlyArray<{
+  value: CodexMicroAgentMode;
+  label: string;
+  description: string;
+}> = [
+  {
+    value: "priority",
+    label: "Priority threads",
+    description: "Waiting, unread, and active threads first",
+  },
+  { value: "pinned", label: "Pinned threads", description: "First six threads in Pinned" },
+  {
+    value: "recent",
+    label: "Most recent threads",
+    description: "First six recently updated threads",
+  },
+];
+
+const KNOB_MODES: ReadonlyArray<{ value: CodexMicroKnobMode; label: string; description: string }> =
+  [
+    {
+      value: "agents",
+      label: "Agent keys",
+      description: "Turn to choose an agent key, click to open its thread",
+    },
+    {
+      value: "threads",
+      label: "Thread switching",
+      description: "Turn to move between threads, click for the command palette",
+    },
+    { value: "custom", label: "Custom", description: "Choose an action for each turn and click" },
+  ];
+
+const BRIGHTNESS = [0.25, 0.5, 0.8, 1] as const;
+const AUTO_DIM: ReadonlyArray<{ value: number | null; label: string }> = [
+  { value: null, label: "Off" },
+  { value: 60_000, label: "1 minute" },
+  { value: 180_000, label: "3 minutes" },
+  { value: 600_000, label: "10 minutes" },
+  { value: 1_800_000, label: "30 minutes" },
+  { value: 3_600_000, label: "1 hour" },
+];
+
+const STATUS_LEGEND = [
+  ["working", "Working"],
+  ["needs-input", "Needs you"],
+  ["done", "Unread"],
+  ["error", "Error"],
+  ["idle", "Idle"],
+] as const;
+
+const COMMAND_KEY_ROWS: ReadonlyArray<[CodexMicroControlId, string, string]> = [
+  ["ACT06", "Key 1", "Third row, left"],
+  ["ACT07", "Key 2", "Third row"],
+  ["ACT08", "Key 3", "Third row"],
+  ["ACT09", "Key 4", "Third row, right"],
+  ["ACT10", "Wide key", "Bottom row"],
+  ["ACT11", "Wide key, right switch", "Bottom row"],
+  ["ACT12", "Corner key", "Bottom row, right"],
+];
+const STICK: ReadonlyArray<[CodexMicroControlId, string]> = [
+  ["JOY_UP", "Up"],
+  ["JOY_RIGHT", "Right"],
+  ["JOY_DOWN", "Down"],
+  ["JOY_LEFT", "Left"],
+];
+const KNOB: ReadonlyArray<[CodexMicroControlId, string]> = [
+  ["ENC_CC", "Turn left"],
+  ["ENC_CW", "Turn right"],
+  ["ENC", "Click"],
+];
+
+const controlRowId = (control: CodexMicroControlId) => `codex-micro-${control}`;
+const agentRowId = (index: number) => `codex-micro-agent-${index}`;
+
+function openRowMenu(id: string) {
+  const row = document.getElementById(id);
+  row?.scrollIntoView({ block: "center", behavior: "smooth" });
+  row?.querySelector<HTMLButtonElement>("[data-codex-micro-trigger]")?.click();
+}
+
+// Read the latest stored value so quick successive edits don't overwrite each other.
+const save = (patch: Partial<CodexMicroSettings>) =>
+  void updateClientSettings({ codexMicro: { ...getClientSettings().codexMicro, ...patch } });
+
+function OptionMenu<T>(props: {
+  readonly label: string;
+  readonly value: T;
+  readonly options: ReadonlyArray<{ value: T; label: string }>;
+  readonly onChange: (value: T) => void;
+}) {
+  const index = Math.max(
+    0,
+    props.options.findIndex((option) => option.value === props.value),
+  );
+  return (
+    <Menu>
+      <MenuTrigger
+        aria-label={props.label}
+        render={<SelectButton size="sm" />}
+        className="w-auto min-w-0"
+      >
+        {props.options[index]?.label}
+      </MenuTrigger>
+      <MenuPopup align="end">
+        <MenuRadioGroup
+          value={String(index)}
+          onValueChange={(next) => props.onChange(props.options[Number(next)]!.value)}
+        >
+          {props.options.map((option, i) => (
+            <MenuRadioItem key={`${i}:${option.label}`} closeOnClick value={String(i)}>
+              {option.label}
+            </MenuRadioItem>
+          ))}
+        </MenuRadioGroup>
+      </MenuPopup>
+    </Menu>
+  );
+}
+
+function ActionMenu(props: {
+  readonly action: CodexMicroAction;
+  readonly onChange: (action: CodexMicroAction) => void;
+}) {
+  const options = new Map(
+    CODEX_MICRO_ACTION_GROUPS.flatMap((group) => group.options).map((option) => [
+      option.key,
+      option.action,
+    ]),
+  );
+  return (
+    <Menu>
+      <MenuTrigger
+        data-codex-micro-trigger
+        aria-label={`Action: ${describeCodexMicroAction(props.action)}`}
+        render={<SelectButton size="sm" />}
+        className="w-auto min-w-0 max-w-60"
+      >
+        <span className="flex min-w-0 items-center gap-1.5">
+          <CodexMicroActionIcon action={props.action} className="size-3.5 shrink-0 opacity-70" />
+          <span className="truncate">{describeCodexMicroAction(props.action)}</span>
+        </span>
+      </MenuTrigger>
+      <MenuPopup align="end" className="max-h-96 overflow-y-auto">
+        <MenuRadioGroup
+          value={codexMicroActionKey(props.action)}
+          onValueChange={(key) => {
+            const action = options.get(String(key));
+            if (action) props.onChange(action);
+          }}
+        >
+          {CODEX_MICRO_ACTION_GROUPS.map((group, index) => (
+            <MenuGroup key={group.title}>
+              {index > 0 ? <MenuSeparator /> : null}
+              <MenuGroupLabel>{group.title}</MenuGroupLabel>
+              {group.options.map((option) => (
+                <MenuRadioItem key={option.key} closeOnClick value={option.key}>
+                  {option.label}
+                </MenuRadioItem>
+              ))}
+            </MenuGroup>
+          ))}
+        </MenuRadioGroup>
+      </MenuPopup>
+    </Menu>
+  );
+}
+
+export function CodexMicroSettingsPanel() {
+  const settings = useClientSettings((current) => current.codexMicro);
+  const { loaded, device, slots, selectedSlot, pressedKeys, joystick } = useCodexMicroSnapshot();
+  const environmentId = usePrimaryEnvironmentId();
+  const threads = useQuietThreadShells()
+    .filter(
+      (thread) => thread.environmentId === environmentId && !thread.archivedAt && !thread.deletedAt,
+    )
+    .toSorted((a, b) => b.updatedAt.localeCompare(a.updatedAt))
+    .slice(0, 15);
+
+  // The page only exists while the device is attached.
+  if (!loaded) return null;
+  if (!device.connected) return <Navigate to="/settings/general" replace />;
+
+  const actionFor = (control: CodexMicroControlId) =>
+    resolveCodexMicroControl(control, settings.knobMode, settings.controls);
+  const setControl = (control: CodexMicroControlId, action: CodexMicroAction) =>
+    save({ controls: { ...getClientSettings().codexMicro.controls, [control]: action } });
+  const setPin = (index: number, threadId: string | null) => {
+    const pinnedThreads = Array.from({ length: 6 }, (_, i) => settings.pinnedThreads[i] ?? null);
+    // A thread lives on one key at a time.
+    for (let i = 0; i < pinnedThreads.length; i += 1) {
+      if (threadId !== null && pinnedThreads[i] === threadId) pinnedThreads[i] = null;
+    }
+    pinnedThreads[index] = threadId;
+    save({ pinnedThreads });
+  };
+  const controlRow = (control: CodexMicroControlId, title: ReactNode, description?: string) => (
+    <SettingsRow
+      key={control}
+      id={controlRowId(control)}
+      title={title}
+      description={description}
+      control={
+        <ActionMenu
+          action={settings.controls[control]}
+          onChange={(action) => setControl(control, action)}
+        />
+      }
+    />
+  );
+  const battery =
+    device.batteryPercentage === null
+      ? null
+      : `${device.batteryPercentage}%${device.charging ? ", charging" : ""}`;
+
+  return (
+    <SettingsPageContainer>
+      <div className="flex flex-col items-center gap-4 rounded-2xl border bg-muted/30 px-4 pt-7 pb-5">
+        <CodexMicroDevicePreview
+          slots={slots}
+          selectedSlot={selectedSlot}
+          pinnedThreads={settings.pinnedThreads}
+          pressedKeys={pressedKeys}
+          joystick={joystick}
+          separateMicrophoneKeys={settings.separateMicrophoneKeys}
+          actionFor={actionFor}
+          onAgentKey={(index) => openRowMenu(agentRowId(index))}
+          onControl={(control) =>
+            openRowMenu(
+              control.startsWith("JOY")
+                ? controlRowId(control)
+                : control.startsWith("ENC")
+                  ? "codex-micro-knob"

@@ -0,0 +1,315 @@
+import * as Clock from "effect/Clock";
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
+import * as Random from "effect/Random";
+import * as Schedule from "effect/Schedule";
+import * as Schema from "effect/Schema";
+import * as Semaphore from "effect/Semaphore";
+import type { HIDAsync } from "node-hid";
+
+import {
+  DISCONNECTED_CODEX_MICRO_STATE,
+  type CodexMicroDeviceState,
+  type CodexMicroEvent,
+  type CodexMicroLighting,
+} from "@t3tools/contracts";
+
+import {
+  CHANNEL_RPC,
+  type CodexMicroEndpoint,
+  decodeReport,
+  encodeRpcRequest,
+  findEndpoints,
+  isDeepEqual,
+  LineAssembler,
+  MAX_RPC_ID,
+  NOTIFY_METHODS,
+  parseRpcLine,
+  reconcileEndpoint,
+  RPC_METHODS,
+} from "./CodexMicroProtocol.ts";
+import { lightingFrame } from "./CodexMicroLighting.ts";
+
+export class CodexMicroError extends Schema.TaggedError<CodexMicroError>()("CodexMicroError", {
+  message: Schema.String,
+  cause: Schema.optional(Schema.Defect()),
+}) {}
+
+const MAX_CONSECUTIVE_FAILURES = 3;
+
+export interface CodexMicroDevice {
+  readonly getState: Effect.Effect<CodexMicroDeviceState>;
+  readonly setLighting: (lighting: CodexMicroLighting) => Effect.Effect<void>;
+}
+
+// A failed open waits this long before retrying, unless the topology changes.
+const RETRY_AFTER_FAILURE_MS = 10_000;
+
+// node-hid is a native addon: load it on first use so a broken prebuild can
+// only disable the Codex Micro, never stop the desktop app from starting.
+let nodeHid: Promise<typeof import("node-hid")> | null = null;
+const loadNodeHid = Effect.tryPromise({
+  try: () => (nodeHid ??= import("node-hid")),
+  catch: (cause) => new CodexMicroError({ message: "Could not load node-hid", cause }),
+});
+
+// Enumeration is async so polling never blocks the main process.
+const listEndpoints = loadNodeHid.pipe(
+  Effect.flatMap((hidModule) =>
+    Effect.tryPromise({
+      try: () => hidModule.devicesAsync(),
+      catch: (cause) => new CodexMicroError({ message: "Could not list HID devices", cause }),
+    }),
+  ),
+  Effect.map(findEndpoints),
+);
+
+/**
+ * Owns one Codex Micro for the lifetime of the scope: discovery, reconnects,
+ * serialized JSON-RPC (the firmware handles one request at a time), lighting
+ * with auto-dim, and key/joystick notifications.
+ */
+export const makeCodexMicroDevice = Effect.fn("desktop.codexMicro.makeDevice")(function* (
+  onEvent: (event: CodexMicroEvent) => void,
+) {
+  const runFork = Effect.runForkWith(yield* Effect.context<never>());
+  const rpcLock = yield* Semaphore.make(1);
+  const lines = new LineAssembler();
+  const pending = new Map<string, Deferred.Deferred<unknown, CodexMicroError>>();
+
+  let hid: HIDAsync | null = null;
+  let endpoint: CodexMicroEndpoint | null = null;
+  let state: CodexMicroDeviceState = DISCONNECTED_CODEX_MICRO_STATE;
+  let lighting: CodexMicroLighting | null = null;
+  let lightsOff = false;
+  let appliedFrame: ReturnType<typeof lightingFrame> | null = null;
+  let dimFiber: Fiber.Fiber<void> | null = null;
+
+  const setState = (next: CodexMicroDeviceState) => {
+    if (isDeepEqual(next, state)) return;
+    state = next;
+    onEvent({ type: "state", state });
+  };
+
+  const send = Effect.fn("desktop.codexMicro.send")(function* (method: string, params: unknown) {
+    const device = hid;
+    if (!device) return yield* new CodexMicroError({ message: "Codex Micro is not connected" });
+    const id = yield* Random.nextIntBetween(0, MAX_RPC_ID);
+    const response = yield* Deferred.make<unknown, CodexMicroError>();
+    pending.set(String(id), response);
+    return yield* Effect.gen(function* () {
+      for (const report of encodeRpcRequest(method, params, id)) {
+        yield* Effect.tryPromise({
+          try: () => device.write(Buffer.from(report)),
+          catch: (cause) => new CodexMicroError({ message: `Codex Micro write failed`, cause }),
+        });
+      }
+      return yield* Deferred.await(response).pipe(
+        Effect.timeoutOrElse({
+          duration: "5 seconds",
+          orElse: () =>
+            Effect.fail(new CodexMicroError({ message: `Codex Micro ${method} timed out` })),
+        }),
+      );
+    }).pipe(Effect.ensuring(Effect.sync(() => pending.delete(String(id)))));
+  });
+
+  // A short cooldown between requests keeps the firmware's parser happy.
+  // A handle can go dead without a read error (sleep/wake, a dropped Bluetooth
+  // link). Treat a run of failed requests as a disconnect so discovery reopens it.
+  let consecutiveFailures = 0;
+  const call = (method: string, params: unknown) =>
+    rpcLock.withPermits(1)(
+      send(method, params).pipe(
+        Effect.tap(() => Effect.sync(() => (consecutiveFailures = 0))),
+        Effect.tapError(() =>
+          Effect.suspend(() =>
+            ++consecutiveFailures >= MAX_CONSECUTIVE_FAILURES ? disconnect : Effect.void,
+          ),
+        ),
+        Effect.ensuring(Effect.sleep("15 millis")),
+      ),
+    );
+
+  const applyLighting = Effect.gen(function* () {
+    if (!hid || !lighting) return;
+    const frame = lightingFrame(lighting, lightsOff);
+    if (isDeepEqual(frame, appliedFrame)) return;
+    appliedFrame = frame;
+    yield* call(RPC_METHODS.lightingConfig, frame.zones);
+    yield* call(RPC_METHODS.slotLighting, frame.slots);
+  }).pipe(
+    Effect.catch((error) =>
+      Effect.sync(() => {
+        appliedFrame = null;
+      }).pipe(Effect.andThen(Effect.logWarning("Codex Micro lighting update failed", error))),
+    ),
+  );
+
+  /** Input or a lighting change restores the lights and restarts auto-dim. */
+  const wake = () => {
+    if (dimFiber) runFork(Fiber.interrupt(dimFiber));
+    dimFiber = null;
+    const autoDimMs = lighting?.autoDimMs;
+    if (autoDimMs) {
+      dimFiber = runFork(
+        Effect.sleep(autoDimMs).pipe(
+          Effect.andThen(Effect.sync(() => (lightsOff = true))),
+          Effect.andThen(applyLighting),
+        ),
+      );
+    }
+    if (lightsOff) {
+      lightsOff = false;
+      runFork(applyLighting);
+    }
+  };
+
+  const onData = (data: Buffer) => {
+    const report = decodeReport(data);
+    if (!report || report.channel !== CHANNEL_RPC) return;
+    for (const line of lines.push(report)) {
+      const message = parseRpcLine(line);
+      if (!message) continue;
+      if (message.kind === "response") {
+        const response = pending.get(message.id);
+        if (!response) continue;
+        runFork(
+          message.error
+            ? Deferred.fail(response, new CodexMicroError({ message: message.error }))
+            : Deferred.succeed(response, message.result),
+        );
+        continue;
+      }
+      const { method, params } = message;
+      if (method === NOTIFY_METHODS.key) {
+        wake();
+        const act = typeof params.act === "number" ? params.act : null;
+        onEvent({ type: "input", input: { type: "key", key: String(params.k), act } });
+      } else if (method === NOTIFY_METHODS.joystick) {
+        const distance = Number(params.d);
+        if (distance > 0.1) wake();
+        onEvent({ type: "input", input: { type: "joystick", angle: Number(params.a), distance } });
+      }

@@ -0,0 +1,148 @@
+import {
+  CODEX_MICRO_SLOT_COUNT,
+  type CodexMicroAgentMode,
+  type CodexMicroSlotStatus,
+  type EnvironmentId,
+  type ThreadId,
+} from "@t3tools/contracts";
+
+import { hasUnseenCompletion, resolveSidebarThreadStatus } from "../components/Sidebar.logic";
+import type { SidebarThreadSummary } from "../types";
+
+export interface CodexMicroSlot {
+  readonly index: number;
+  readonly environmentId: EnvironmentId | null;
+  readonly threadId: ThreadId | null;
+  readonly title: string | null;
+  readonly status: CodexMicroSlotStatus;
+}
+
+export const EMPTY_CODEX_MICRO_SLOTS: ReadonlyArray<CodexMicroSlot> = Array.from(
+  { length: CODEX_MICRO_SLOT_COUNT },
+  (_, index) => ({ index, environmentId: null, threadId: null, title: null, status: "off" }),
+);
+
+/** The same states the sidebar shows, folded into the device's five colors. */
+export function codexMicroSlotStatus(thread: SidebarThreadSummary): CodexMicroSlotStatus {
+  switch (resolveSidebarThreadStatus(thread)) {
+    case "approval":
+    case "input":
+    case "request":
+      return "needs-input";
+    case "working":
+      return "working";
+    case "waiting":
+      return thread.blockedOnThreadWait === true ? "working" : "idle";
+    case "failed":
+    case "limited":
+      return "error";
+    case "ready":
+      return hasUnseenCompletion(thread) ? "done" : "idle";
+  }
+}
+
+const PRIORITY: Record<CodexMicroSlotStatus, number> = {
+  "needs-input": 0,
+  error: 1,
+  working: 2,
+  done: 3,
+  idle: 4,
+  off: 5,
+};
+
+function isVisible(thread: SidebarThreadSummary, now: string): boolean {
+  if (thread.deletedAt || thread.archivedAt) return false;
+  return !thread.snoozedUntil || thread.snoozedUntil <= now;
+}
+
+function rank(
+  threads: ReadonlyArray<SidebarThreadSummary>,
+  mode: CodexMicroAgentMode,
+  now: string,
+): SidebarThreadSummary[] {
+  const visible = threads.filter((thread) => isVisible(thread, now));
+  switch (mode) {
+    case "pinned":
+      // Sidebar "Pinned" order.
+      return visible
+        .filter((thread) => thread.pinnedAt)
+        .toSorted(
+          (a, b) =>
+            (a.pinOrderKey ?? "").localeCompare(b.pinOrderKey ?? "") ||
+            (a.pinnedAt ?? "").localeCompare(b.pinnedAt ?? ""),
+        );
+    case "recent":
+      return visible.toSorted((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+    case "priority":
+      return (
+        visible
+          .map((thread) => ({ thread, status: codexMicroSlotStatus(thread) }))
+          // Live work always shows; finished or idle threads only while in the inbox.
+          .filter(
+            ({ thread, status }) =>
+              status === "working" ||
+              status === "needs-input" ||
+              thread.pinnedAt !== null ||
+              thread.settledAt === null,
+          )
+          .toSorted(
+            (a, b) =>
+              PRIORITY[a.status] - PRIORITY[b.status] ||
+              Number(b.thread.pinnedAt !== null) - Number(a.thread.pinnedAt !== null) ||
+              b.thread.updatedAt.localeCompare(a.thread.updatedAt),
+          )
+          .map(({ thread }) => thread)
+      );
+  }
+}
+
+/**
+ * Picks the threads for the six agent keys. A thread keeps its key while it
+ * stays in the top six, so lights don't jump around; freed keys go to the next
+ * thread in line. `pinnedThreads` hard-assigns keys.
+ */
+export function assignCodexMicroSlots(input: {
+  readonly threads: ReadonlyArray<SidebarThreadSummary>;
+  readonly previous: ReadonlyArray<CodexMicroSlot>;
+  readonly mode: CodexMicroAgentMode;
+  readonly pinnedThreads: ReadonlyArray<string | null>;
+  readonly now: string;
+}): CodexMicroSlot[] {
+  const byId = new Map(input.threads.map((thread) => [thread.id as string, thread]));
+  const pins = Array.from({ length: CODEX_MICRO_SLOT_COUNT }, (_, index) => {
+    const id = input.pinnedThreads[index] ?? null;
+    return id !== null && byId.has(id) ? id : null;
+  });