ompchamber 3.5.0 → 3.6.0

package/src/server/lib/terminal/runtime.server.ts

@@ -4,18 +4,16 @@
  */
 
 /**
- * The terminal registry: which shells are live, who is watching them, and when
- * they die.
+ * The terminal registry: creation, attachment, input, resize and reaping.
  *
  * One real shell per terminal id, created on the first `attach` (there is no
  * separate create endpoint to race against), kept alive while clients come and
  * go, and killed through the process group so the commands it started die with
- * it. Session mechanics live in `session.server.ts`; this module owns the map,
- * the viewer sets, the idle reaper and process-exit cleanup.
+ * it. Session mechanics live in `session.server.ts`, the process-wide state in
+ * `store.ts`, and the liveness questions in `liveness.server.ts`.
  */
 
-import path from 'path';
-import { detectBusyShells, type ShellProcess } from '@/server/lib/terminal/foreground';
+import { countLiveTerminals } from '@/server/lib/terminal/liveness.server';
 import {
   TERMINATION_GRACE_MS,
   TerminalRuntimeError,
@@ -27,6 +25,7 @@ import {
   type TerminalSession,
   type TerminalViewer,
 } from '@/server/lib/terminal/session.server';
+import { terminalStore } from '@/server/lib/terminal/store';
 import { TERMINAL_MAX_INPUT_BYTES, clampTerminalSize, type TerminalSnapshot } from '@/shared/lib/workspace/terminal/protocol';
 
 const MAX_TERMINALS = 8;
@@ -41,41 +40,10 @@ export interface TerminalAttachment {
   replay: Uint8Array;
 }
 
-/**
- * The registry lives on `globalThis`, not in a module-local binding.
- *
- * `bun run --hot` re-evaluates this module on every server-file edit, but the
- * PTY children are detached sessions that keep running. A module-local `Map`
- * would be replaced by a fresh empty one on each reload, leaving the previous
- * shells alive with nothing tracking them — unreachable from the client, never
- * counted, never reaped, and still holding their slots. Anchoring the map to
- * the process keeps a reload from orphaning anything.
- */
-declare global {
-  // eslint-disable-next-line no-var
-  var __ompChamberTerminals: Map<string, TerminalSession> | undefined;
-  // eslint-disable-next-line no-var
-  var __ompChamberTerminalSweep: ReturnType<typeof setInterval> | undefined;
-  // eslint-disable-next-line no-var
-  var __ompChamberTerminalResizes: Map<string, ReturnType<typeof setTimeout>> | undefined;
-  // eslint-disable-next-line no-var
-  var __ompChamberTerminalCleanupInstalled: boolean | undefined;
-}
-
-const sessions: Map<string, TerminalSession> = (globalThis.__ompChamberTerminals ??= new Map());
-
-function getSweepTimer() {
-  return globalThis.__ompChamberTerminalSweep;
-}
-
-function setSweepTimer(timer: ReturnType<typeof setInterval> | undefined) {
-  globalThis.__ompChamberTerminalSweep = timer;
-  return timer;
-}
-
-function getResizeTimers(): Map<string, ReturnType<typeof setTimeout>> {
-  return (globalThis.__ompChamberTerminalResizes ??= new Map());
-}
+/** The process-wide state; see `store.ts` for why it is not module-local. */
+const registry = terminalStore();
+const sessions = registry.sessions;
+const resizeTimers = registry.resizeTimers;
 
 /**
  * Attach `viewer` to `request.id`, creating the shell when the id is unknown.
@@ -83,30 +51,9 @@ function getResizeTimers(): Map<string, ReturnType<typeof setTimeout>> {
  * Registration and history capture happen in one synchronous block: Bun cannot
  * interleave a PTY `data` callback inside it, so the viewer can neither miss
  * output nor receive it twice.
- *
- * The cap counts *live* shells only. An exited shell is a corpse holding a
- * scrollback nobody is reading, and letting corpses consume the budget is how
- * a session that restarted a shell a few times hits the limit with nothing
- * running: every restart leaves its predecessor behind.
  */
 export async function attachTerminal(viewer: TerminalViewer, request: AttachRequest): Promise<TerminalAttachment> {
-  let session = sessions.get(request.id);
-  if (!session) {
-    reclaimExitedTerminals();
-    if ((await countLiveTerminals()) >= MAX_TERMINALS) {
-      throw new TerminalRuntimeError('capacity', `Terminal limit reached (${MAX_TERMINALS} busy shells)`);
-    }
-    const created = await createSession(request);
-    sessions.set(request.id, created);
-    // An exit with nobody watching is the common case for a replaced shell
-    // (restart, repo switch): reap it as soon as it lands instead of leaving
-    // the record for the sweep, which is up to a minute of holding a slot.
-    void created.proc?.exited.then(() => {
-      if (created.viewers.size === 0) forgetTerminal(created.id);
-    });
-    ensureSweeper();
-    session = created;
-  }
+  const session = await openTerminal(request);
 
   const replay = session.history.replay();
   const snapshot = snapshotOf(session);
@@ -116,22 +63,59 @@ export async function attachTerminal(viewer: TerminalViewer, request: AttachRequ
 }
 
 /**
- * Shells that are actually doing work, which is what the cap budgets.
+ * The shell for `request.id`, creating it at most once.
+ *
+ * Creation awaits — cwd resolution, the shell probe, the cap's `ps` — so two
+ * `attach` frames for the same new id both used to pass the `sessions.get`
+ * check and both spawned a shell. The map kept whichever landed last and the
+ * other became unreachable: a PTY plus a detached shell with no record, which
+ * the reaper could never reclaim and the cap never counted. Measured on this
+ * runtime: two concurrent attaches for one id left two shells for one record.
+ * A page reload racing its own reconnect is enough to produce that.
  *
- * Two things are deliberately excluded: an exited shell (a corpse with a
- * scrollback) and a shell sitting at its prompt — the PTY's foreground process
- * group tells them apart exactly (see `foreground.ts`). Counting idle shells
- * is how a panel that was restarted or switched a few times pins the budget
- * with nothing running, and the next attach is refused.
+ * Sharing the in-flight promise makes the loser await the winner's session
+ * instead of creating a rival. The map lives in `store.ts` beside the records,
+ * because a reload that dropped it would reopen the same race.
  */
-export async function countLiveTerminals(): Promise<number> {
-  const running: ShellProcess[] = [];
-  for (const session of sessions.values()) {
-    if (session.status !== 'running' || !session.proc) continue;
-    running.push({ id: session.id, pid: session.proc.pid });
+async function openTerminal(request: AttachRequest): Promise<TerminalSession> {
+  const existing = sessions.get(request.id);
+  if (existing) return existing;
+
+  const inFlight = registry.creating.get(request.id);
+  if (inFlight) return inFlight;
+
+  const entry = createTerminal(request);
+  registry.creating.set(request.id, entry);
+  const release = () => {
+    if (registry.creating.get(request.id) === entry) registry.creating.delete(request.id);
+  };
+  void entry.then(release, release);
+  return entry;
+}
+
+/**
+ * Spawn one shell, register it, and arm the reaper.
+ *
+ * The cap counts *live* shells only. An exited shell is a corpse holding a
+ * scrollback nobody is reading, and letting corpses consume the budget is how
+ * a session that restarted a shell a few times hits the limit with nothing
+ * running: every restart leaves its predecessor behind.
+ */
+async function createTerminal(request: AttachRequest): Promise<TerminalSession> {
+  reclaimExitedTerminals();
+  if ((await countLiveTerminals()) >= MAX_TERMINALS) {
+    throw new TerminalRuntimeError('capacity', `Terminal limit reached (${MAX_TERMINALS} busy shells)`);
   }
-  const busy = await detectBusyShells(running);
-  return busy.size;
+  const created = await createSession(request);
+  sessions.set(request.id, created);
+  // An exit with nobody watching is the common case for a replaced shell
+  // (restart, repo switch): reap it as soon as it lands instead of leaving
+  // the record for the sweep, which is up to a minute of holding a slot.
+  void created.proc?.exited.then(() => {
+    if (created.viewers.size === 0) forgetTerminal(created.id);
+  });
+  ensureSweeper();
+  return created;
 }
 
 /**
@@ -162,32 +146,6 @@ export function detachTerminal(viewer: TerminalViewer, id: string): void {
   if (session.status === 'exited' && session.viewers.size === 0) forgetTerminal(id);
 }
 
-/**
- * Live terminal summaries, optionally narrowed to one scope, so a client can
- * adopt a shell it does not have an id for (a reloaded page, a second tab).
- *
- * `busy` marks a shell with a foreground command — the panel shows it as
- * running, and the cap budgets it. One `ps` for the whole list.
- */
-export async function listTerminals(root?: string | null, repo?: string | null): Promise<TerminalSnapshot[]> {
-  const scope = root ? (repo && repo !== '.' ? path.join(root, repo) : root) : null;
-  const running: ShellProcess[] = [];
-  const out: TerminalSnapshot[] = [];
-  for (const session of sessions.values()) {
-    if (scope && !isWithin(session.cwd, scope)) continue;
-    if (session.status === 'running' && session.proc) {
-      running.push({ id: session.id, pid: session.proc.pid });
-    }
-    out.push(snapshotOf(session));
-  }
-  const busy = await detectBusyShells(running);
-  return out.map((snapshot) => ({ ...snapshot, busy: busy.has(snapshot.id) }));
-}
-
-function isWithin(target: string, root: string): boolean {
-  return target === root || target.startsWith(root.endsWith(path.sep) ? root : root + path.sep);
-}
-
 export function writeTerminalInput(id: string, data: Uint8Array): void {
   const session = sessions.get(id);
   if (!session || session.status !== 'running') return;
@@ -231,8 +189,6 @@ export function resizeTerminal(id: string, cols: number, rows: number): void {
  * and a repaint of an intermediate size is invisible work. A single timeout is
  * reused so the burst coalesces into one signal.
  */
-const resizeTimers = getResizeTimers();
-
 export function resizeTerminalDebounced(id: string, cols: number, rows: number): void {
   const pending = resizeTimers.get(id);
   if (pending) clearTimeout(pending);
@@ -295,7 +251,8 @@ function clearPendingResize(id: string): void {
  * own session and would otherwise outlive the server.
  */
 export function disposeAllTerminals(): void {
-  clearInterval(setSweepTimer(undefined));
+  clearInterval(registry.sweep);
+  registry.sweep = undefined;
   for (const [id, session] of sessions) {
     clearPendingResize(id);
     session.viewers.clear();
@@ -306,8 +263,8 @@ export function disposeAllTerminals(): void {
 }
 
 function ensureSweeper(): void {
-  if (getSweepTimer() !== undefined) return;
-  setSweepTimer(setInterval(() => {
+  if (registry.sweep !== undefined) return;
+  registry.sweep = setInterval(() => {
     // Exited shells are reaped on exit and on detach; this catches the one
     // that finished while a viewer was still attached to it.
     reclaimExitedTerminals();
@@ -319,22 +276,18 @@ function ensureSweeper(): void {
       if (now - session.lastActivity < IDLE_TIMEOUT_MS) continue;
       forgetTerminal(id);
     }
-  }, IDLE_SWEEP_MS));
-  getSweepTimer()!.unref();
+  }, IDLE_SWEEP_MS);
+  registry.sweep.unref?.();
 }
 
 /**
  * Register process-wide cleanup exactly once. A `bun --hot` reload re-evaluates
  * this module while the shells live on, so the guard keeps a reload from
- * stacking duplicate signal handlers.
+ * stacking duplicate signal handlers. It rides the same store as the registry,
+ * which is what makes it survive the reload that would otherwise reset it.
  */
-declare global {
-  // eslint-disable-next-line no-var
-  var __ompChamberTerminalCleanupInstalled: boolean | undefined;
-}
-
-if (!globalThis.__ompChamberTerminalCleanupInstalled) {
-  globalThis.__ompChamberTerminalCleanupInstalled = true;
+if (!registry.cleanupInstalled) {
+  registry.cleanupInstalled = true;
   process.once('exit', disposeAllTerminals);
   process.once('SIGINT', disposeAllTerminals);
   process.once('SIGTERM', disposeAllTerminals);

package/src/server/lib/terminal/session.server.ts

@@ -29,6 +29,7 @@
 
 import { resolveRoot } from '@/server/lib/fs/root';
 import { scopeToRepo } from '@/server/lib/fs/repo-scope';
+import { describeSpawnFailure } from '@/server/lib/lifecycle/fd-pressure';
 import { createTerminalHistory, type TerminalHistory } from '@/server/lib/terminal/history';
 import { resolveShellExecutable, shellCandidates, shellLaunch, terminalEnv } from '@/server/lib/terminal/shell';
 import {
@@ -160,8 +161,10 @@ export async function createSession(request: AttachRequest): Promise<TerminalSes
     });
   } catch (error) {
     closeTerminalStream(session);
-    const message = error instanceof Error ? error.message : String(error);
-    throw new TerminalRuntimeError('spawn', `Failed to start ${executable}: ${message}`);
+    // `describeSpawnFailure` keeps Bun's own message and adds the real cause
+    // when the process is out of descriptors — the raw error argues about
+    // `/bin/sh`, which is the shim, not the thing that ran out.
+    throw new TerminalRuntimeError('spawn', `Failed to start ${executable}: ${describeSpawnFailure(error)}`);
   }
   session.proc = proc;
 

package/src/server/lib/terminal/store.ts

@@ -0,0 +1,72 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The terminal registry's process-wide state, anchored to `globalThis`.
+ *
+ * `bun run --hot` re-evaluates the terminal modules on every server-file edit,
+ * while the PTY children are detached sessions that keep running. A
+ * module-local `Map` would be replaced by a fresh empty one on each reload,
+ * leaving the previous shells alive with nothing tracking them: unreachable from
+ * the client, never counted, never reaped, still holding their slots. Anchoring
+ * the state to the process keeps a reload from orphaning anything.
+ *
+ * The in-flight map has to live here for the same reason, one step further: a
+ * reload that dropped it would let the next `attach` start a second creation
+ * for an id whose first creation is still awaiting — exactly the race the map
+ * exists to prevent. `sweep` survives a reload too, or every generation would
+ * start its own reaper.
+ */
+
+import type { TerminalSession } from '@/server/lib/terminal/session.server';
+
+/** Handle for a pending resize timeout. */
+export type TerminalTimeout = ReturnType<typeof setTimeout>;
+/** Handle for the idle reaper's interval. */
+export type TerminalSweep = ReturnType<typeof setInterval>;
+
+export interface TerminalStore {
+  /** One record per terminal id, live or exited-but-still-watched. */
+  sessions: Map<string, TerminalSession>;
+  /** One in-flight `createSession` per terminal id. See the module doc. */
+  creating: Map<string, Promise<TerminalSession>>;
+  /** Debounced resize timeouts, keyed by terminal id. */
+  resizeTimers: Map<string, TerminalTimeout>;
+  /** The reaper, or undefined when it was never started. */
+  sweep: TerminalSweep | undefined;
+  /** Process-exit cleanup is registered once per process, not per reload. */
+  cleanupInstalled: boolean;
+}
+
+declare global {
+  // eslint-disable-next-line no-var
+  var __ompChamberTerminalState: TerminalStore | undefined;
+  /**
+   * The pre-object shape: a bare sessions Map under its own key. Read once, so a
+   * server that reloads into this module keeps the shells it is already running
+   * instead of dropping their records on the floor.
+   */
+  // eslint-disable-next-line no-var
+  var __ompChamberTerminals: Map<string, TerminalSession> | undefined;
+  // eslint-disable-next-line no-var
+  var __ompChamberTerminalSweep: TerminalSweep | undefined;
+  // eslint-disable-next-line no-var
+  var __ompChamberTerminalResizes: Map<string, TerminalTimeout> | undefined;
+  // eslint-disable-next-line no-var
+  var __ompChamberTerminalCleanupInstalled: boolean | undefined;
+}
+
+export function terminalStore(): TerminalStore {
+  if (globalThis.__ompChamberTerminalState) return globalThis.__ompChamberTerminalState;
+  const legacySessions = globalThis.__ompChamberTerminals;
+  const legacyResizes = globalThis.__ompChamberTerminalResizes;
+  return (globalThis.__ompChamberTerminalState = {
+    sessions: legacySessions instanceof Map ? legacySessions : new Map(),
+    creating: new Map(),
+    resizeTimers: legacyResizes instanceof Map ? legacyResizes : new Map(),
+    sweep: globalThis.__ompChamberTerminalSweep,
+    cleanupInstalled: globalThis.__ompChamberTerminalCleanupInstalled === true,
+  });
+}

package/src/server/lib/updates/apply.ts

@@ -1,49 +1,78 @@
 /**
  * Applies a requested update. oh-my-pi is updated through the omp binary;
  * OMPChamber through the shared self-update engine, which replaces the running
- * install in place (bun global install, or git fast-forward + rebuild) and then
- * restarts this instance through a detached `ompchamber restart` — unless the
- * instance was started from source, which its own launcher has to restart.
+ * install in place (bun global install, or git fast-forward + rebuild).
+ *
+ * Neither branch restarts anything: this module only reports what happened.
+ * The caller decides, because the console has to flush the result to the
+ * browser BEFORE the process that is serving it goes away.
  */
 
-import { scheduleSelfRestart } from '@/server/lib/lifecycle/restart';
 import { updateOmpChamber } from '@/server/lib/updates/install';
 import { applyOmpUpdate } from '@/server/lib/updates/omp';
+import { withUpdateSlot } from '@/server/lib/updates/single-flight';
 import type { UpdateApplyResult, UpdateTarget } from '@/shared/types/updates';
 
-export async function applyUpdate(target: UpdateTarget): Promise<UpdateApplyResult> {
-  if (target === 'omp') {
-    try {
-      const { output } = await applyOmpUpdate();
-      return { success: true, target: 'omp', manual: false, message: 'oh-my-pi updated', output };
-    } catch (err) {
+/** A stage label or a line of command output, as the update produces it. */
+export interface UpdateProgressHooks {
+  onLine?: (chunk: string) => void;
+  onStage?: (label: string) => void;
+}
+
+/**
+ * `updated` is what the caller needs to decide about a restart: an "already up
+ * to date" answer is a success that must not bounce a healthy server.
+ */
+export interface AppliedUpdate {
+  result: UpdateApplyResult;
+  updated: boolean;
+}
+
+/**
+ * Runs one update, and refuses to start while another holds the slot — see
+ * `single-flight.ts` for why the console cannot be the gate. The refusal is
+ * thrown, not returned as a result: it is the caller's decision whether that is
+ * a 409 before the work starts or a failure frame inside it.
+ */
+export async function applyUpdate(target: UpdateTarget, hooks: UpdateProgressHooks = {}): Promise<AppliedUpdate> {
+  return withUpdateSlot(target, async () => {
+    if (target === 'omp') {
+      try {
+        const { output } = await applyOmpUpdate({ onLine: hooks.onLine });
+        return {
+          result: { success: true, target: 'omp', manual: false, message: 'oh-my-pi updated', output },
+          updated: true,
+        };
+      } catch (err) {
+        return {
+          result: {
+            success: false,
+            target: 'omp',
+            manual: false,
+            message: err instanceof Error ? err.message : 'Failed to update oh-my-pi',
+          },
+          updated: false,
+        };
+      }
+    }
+
+    if (target === 'ompchamber') {
+      const result = await updateOmpChamber({ onLine: hooks.onLine, onStage: hooks.onStage });
       return {
-        success: false,
-        target: 'omp',
-        manual: false,
-        message: err instanceof Error ? err.message : 'Failed to update oh-my-pi',
+        result: {
+          success: result.success,
+          target: 'ompchamber',
+          manual: result.manual,
+          message: result.message,
+          output: result.output || undefined,
+        },
+        updated: result.updated,
       };
     }
-  }
 
-  if (target === 'ompchamber') {
-    const result = await updateOmpChamber();
-    // Only a call that actually replaced files has something to restart for:
-    // an "already up to date" answer must not bounce a healthy server.
-    const restart = result.success && result.updated ? scheduleSelfRestart() : null;
     return {
-      success: result.success,
-      target: 'ompchamber',
-      manual: result.manual,
-      message: restart ? `${result.message} ${restart.message}` : result.message,
-      output: result.output || undefined,
+      result: { success: false, target, manual: true, message: 'Unknown update target' },
+      updated: false,
     };
-  }
-
-  return {
-    success: false,
-    target,
-    manual: true,
-    message: 'Unknown update target',
-  };
+  });
 }

package/src/server/lib/updates/install.ts

@@ -166,7 +166,14 @@ export function planUpdateSteps({ method, version, pkgRoot, bunBin }: { method:
   ];
 }
 
-async function pump(stream: ReadableStream<Uint8Array>, sink?: (chunk: string) => void): Promise<string> {
+/**
+ * Drain a child's stdout/stderr, forwarding each chunk to `sink` as it arrives
+ * and returning the whole decoded text. Exported because the omp update path
+ * needs the same streaming read: buffering with `new Response(stream).text()`
+ * emits nothing until the process exits, which is exactly what makes an update
+ * look hung.
+ */
+export async function pumpStream(stream: ReadableStream<Uint8Array>, sink?: (chunk: string) => void): Promise<string> {
   const reader = stream.getReader();
   const decoder = new TextDecoder();
   let text = '';
@@ -191,7 +198,7 @@ async function runStep(step: UpdateStep, onLine?: (chunk: string) => void): Prom
     timeout: STEP_TIMEOUT_MS,
     env: { ...Bun.env, PAGER: 'cat', FORCE_COLOR: '0' },
   });
-  const [stdout, stderr] = await Promise.all([pump(proc.stdout, onLine), pump(proc.stderr, onLine)]);
+  const [stdout, stderr] = await Promise.all([pumpStream(proc.stdout, onLine), pumpStream(proc.stderr, onLine)]);
   const exitCode = await proc.exited;
   return { ok: exitCode === 0, exitCode, output: `${stdout}${stderr}`.trim() };
 }

package/src/server/lib/updates/omp.ts

@@ -5,6 +5,7 @@
  */
 
 import { invalidateOmpCliCache, resolveOmpBin } from '@/server/lib/omp/core/cli';
+import { pumpStream } from '@/server/lib/updates/install';
 import type { UpdateTargetInfo } from '@/shared/types/updates';
 
 /** Runs a command, capturing stdout/stderr separately. Non-zero exits keep the captured output. */
@@ -68,19 +69,46 @@ export async function checkOmpUpdate(): Promise<UpdateTargetInfo> {
   return { current, latest, updateAvailable, installed: true, error };
 }
 
-export async function applyOmpUpdate(): Promise<{ output: string }> {
+export interface OmpUpdateHooks {
+  /** Receives command output as it arrives (the console streams it). */
+  onLine?: (chunk: string) => void;
+}
+
+export async function applyOmpUpdate(hooks: OmpUpdateHooks = {}): Promise<{ output: string }> {
   const bin = resolveOmpBin();
   if (!bin) throw new Error('omp binary not found');
 
+  const proc = Bun.spawn({
+    cmd: [bin, 'update'],
+    stdout: 'pipe',
+    stderr: 'pipe',
+    timeout: 300_000,
+    maxBuffer: 1024 * 1024 * 4,
+    env: { ...Bun.env, PAGER: 'cat', FORCE_COLOR: '0' },
+  });
+
+  // Streamed, not buffered: `omp update` prints its stages as it goes, and the
+  // console draws them. A `new Response(proc.stdout).text()` here would hold
+  // every byte until the process exits — the spinner-blind behavior this path
+  // exists to remove. `maxBuffer` still bounds each stream, so a runaway child
+  // is capped exactly as it was under the buffered read.
+  let exitCode: number | null = null;
+  let stdout = '';
+  let stderr = '';
   try {
-    const { stdout, stderr, exitCode } = await runCapture(bin, ['update'], 300000, 1024 * 1024 * 4);
-    invalidateOmpCliCache();
-    if (exitCode !== 0) {
-      throw new Error(combined(stdout, stderr).trim() || `omp update exited with code ${exitCode}`);
-    }
-    return { output: combined(stdout, stderr).trim() };
-  } catch (err) {
+    [stdout, stderr] = await Promise.all([
+      pumpStream(proc.stdout, hooks.onLine),
+      pumpStream(proc.stderr, hooks.onLine),
+    ]);
+    exitCode = await proc.exited;
+  } finally {
+    // The next request must re-probe the binary: `omp update` can replace its
+    // own launcher, and a cached path may no longer exist.
     invalidateOmpCliCache();
-    throw err instanceof Error ? err : new Error(String(err));
   }
+
+  if (exitCode !== 0) {
+    throw new Error(combined(stdout, stderr).trim() || `omp update exited with code ${exitCode}`);
+  }
+  return { output: combined(stdout, stderr).trim() };
 }

package/src/server/lib/updates/single-flight.test.ts

@@ -0,0 +1,61 @@
+/**
+ * The single-flight contract for updates. Two properties matter and neither is
+ * visible from the call site: a run refusing to start while another holds the
+ * slot, and the slot always being free again afterwards — a stuck claim would
+ * answer "already running" until the server restarted.
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import { runningUpdate, UpdateInProgressError, withUpdateSlot } from '@/server/lib/updates/single-flight';
+
+/** A run that stays open until `release()` is called. */
+function deferred() {
+  let release!: (value: string) => void;
+  const promise = new Promise<string>((resolve) => {
+    release = resolve;
+  });
+  return { promise, release };
+}
+
+describe('withUpdateSlot', () => {
+  test('a run is refused while another holds the slot', async () => {
+    const gate = deferred();
+    const running = withUpdateSlot('omp', () => gate.promise);
+    expect(runningUpdate()).toBe('omp');
+
+    await expect(withUpdateSlot('ompchamber', async () => 'never')).rejects.toThrow(UpdateInProgressError);
+
+    gate.release('done');
+    await expect(running).resolves.toBe('done');
+  });
+
+  test('the refusal names the update that is already running', async () => {
+    const gate = deferred();
+    const running = withUpdateSlot('ompchamber', () => gate.promise);
+
+    const error = await withUpdateSlot('omp', async () => 'never').catch((cause: unknown) => cause);
+    expect(error).toBeInstanceOf(UpdateInProgressError);
+    expect((error as Error).message).toContain('OMPChamber');
+
+    gate.release('done');
+    await expect(running).resolves.toBe('done');
+  });
+
+  test('the slot is free again once the run settles', async () => {
+    await expect(withUpdateSlot('omp', async () => 'first')).resolves.toBe('first');
+
+    expect(runningUpdate()).toBeNull();
+    await expect(withUpdateSlot('omp', async () => 'ok')).resolves.toBe('ok');
+  });
+
+  test('a run that throws does not leave the slot held', async () => {
+    await expect(
+      withUpdateSlot('omp', async () => {
+        throw new Error('boom');
+      }),
+    ).rejects.toThrow('boom');
+
+    expect(runningUpdate()).toBeNull();
+  });
+});