@kabmo-labs/kabmo 0.5.3 → 0.6.0

package/src/server/lib/omp/session/auto-title.server.ts

@@ -18,7 +18,7 @@
  * rpc-mode dispatches for a `prompt` frame BEFORE that frame is forwarded as a
  * turn — so the request can be sent at any point in a run and never becomes
  * part of the conversation. Verified against omp 18.3.0 — the ack returns
- * `{agentInvoked:false}` immediately, the generation lands ~3-4s later as
+ * `{agentInvoked:false}` immediately, the generation lands seconds later as
  * `session_info_update` + `command_output`, and no entry is written to the
  * transcript.
  *
@@ -30,13 +30,28 @@
  * on every attempt rather than cached, so a rename made in another tab is
  * respected.
  *
- * ONE ATTEMPT PER CONVERSATION, RETRIED ONCE INSIDE THE FIRST RUN. The title
- * is derived from the FIRST run and never re-asked after it. omp's `/rename`
- * derives its title from the newest turns (and `generateRenameTitle` reserves a
- * fresh title revision, which cancels any generation still in flight), so a
- * second attempt after turn two would name the session after whatever the
- * conversation had become by then — and could even discard a slow first
- * generation.
+ * ## The title runs on the SESSION's model, not omp's `tiny` role
+ *
+ * This is the reason auto-titling produced no name at all on a real install:
+ * omp names a session with its `tiny` ROLE (`getTitleModels` →
+ * `roleCandidatePool("tiny")`) and only appends the session's own model when
+ * `retry.modelFallback` is on. Measured on this machine — six auto-title
+ * attempts across four fresh sessions, every one on
+ * `kenari/deepseek-v4-flash`, every one answered `429 plan_limit_reached`
+ * after ~52 s, and not a single session named; the two renames that DID succeed
+ * (the manual action) ran on `kenari-jatis/deepseek-v4-1-flash`, the
+ * conversation's own model, through the pin. `withTitleModelOverride` now wraps
+ * BOTH paths, and it is held until the request's frames arrive — omp resolves
+ * the role again for the card request that follows a successful title, so a pin
+ * released on the ack would produce an uncarded title (or none).
+ *
+ * ## One attempt per conversation, retried ONCE after the first run
+ *
+ * The title is derived from the FIRST run and never re-asked after it. omp's
+ * `/rename` derives its title from the newest turns (and `renameTitle` reserves
+ * a fresh title revision, which cancels any generation still in flight), so a
+ * third attempt after turn two would name the session after whatever the
+ * conversation had become by then.
  *
  * There are exactly two triggers, both inside that first run:
  *
@@ -49,6 +64,14 @@
  *      no title — a provider error, a timeout, a child that went away, or the
  *      tiny model declining.
  *
+ * **The fallback ALWAYS dispatches.** It used to stand down while the early
+ * generation was "still in flight" (the claim window), which assumed that
+ * generation would land; on a real session it was the attempt that had already
+ * failed 52 s earlier, and the run ended with the window still armed — so the
+ * session was never asked again. The two dispatches are serialized
+ * (`title-request.server.ts`), and the last one wins omp's title revision,
+ * which is the behaviour we want: the fallback reads the completed first turn.
+ *
  * The eligibility latch `autoTitlePending` is consumed by the fallback, so that
  * is the last chance this conversation gets and a later run can never title it.
  * `autoTitleRequested` is what keeps the early trigger from firing again on a
@@ -64,7 +87,25 @@
 
 import { readSettingsJson } from '@/server/lib/db/settings-store';
 import { getDb } from '@/server/db.server';
-import { GET_STATE_TIMEOUT_MS, PROMPT_ACK_TIMEOUT_MS, type RpcSessionState } from '@/server/lib/omp/rpc/constants';
+import { GET_STATE_TIMEOUT_MS, type RpcSessionState } from '@/server/lib/omp/rpc/constants';
+import {
+  GENERATE_TITLE_COMMAND,
+  sendTitleRequest,
+  waitForTitleOutcome,
+  type TitleRequestHost,
+} from '@/server/lib/omp/session/title-request.server';
+import { withTitleModelOverride } from '@/server/lib/omp/session/title-model-overlay.server';
+
+export {
+  GENERATE_TITLE_COMMAND,
+  awaitTitleDispatch,
+  consumeAutoTitleOutput,
+  markTitleRequestSent,
+  releaseTitleClaim,
+  sendTitleRequest,
+  waitForTitleOutcome,
+} from '@/server/lib/omp/session/title-request.server';
+export type { TitleRequestHost } from '@/server/lib/omp/session/title-request.server';
 
 /** Settings blob key; mirrors the other blob keys (see `shared/lib/settings/keys`). */
 const SETTINGS_BLOB_KEY = 'kabmo_settings';
@@ -74,32 +115,10 @@ const SETTINGS_BLOB_KEY = 'kabmo_settings';
  *  and the cost is one tiny-model call per session. */
 const AUTO_SESSION_TITLE_DEFAULT = true;
 
-/** omp's builtin that generates a title from the conversation. Sent with no
- *  args so omp derives it through its own `generateRenameTitle`. */
-const GENERATE_TITLE_COMMAND = '/rename';
-
-/**
- * How long Kabmo's own `/rename` may keep emitting its diagnostic frames.
- *
- * The command answers on the prompt path with an immediate ack and then streams
- * `session_info_update` + `command_output` once the tiny model returns
- * (measured ~4s). Both carry NO correlation id, so the only way to attribute
- * them to our background request is this window. It is deliberately generous —
- * a slow provider must not leak the message — because the cost of over-holding
- * it is only that a slash command typed in the same few seconds loses its
- * output row.
- */
-const AUTO_TITLE_OUTPUT_WINDOW_MS = 60_000;
-
-/** Wrapper state this module reads and writes. The in-flight flag, the
- *  output window and the one-shot latch are owned by the caller because they
- *  are per-session runtime state, not policy. */
-export interface AutoTitleHost {
-  sessionId: string;
-  autoTitleInFlight: boolean;
-  /** Epoch ms until which frames belong to our own background rename; 0 when
-   *  no request is outstanding. */
-  autoTitleWindowUntil: number;
+/** Wrapper state this module reads and writes. The dispatch chain and the claim
+ *  count are owned by the caller because they are per-session runtime state,
+ *  not policy. */
+export interface AutoTitleHost extends TitleRequestHost {
   /** True only while this conversation is still eligible for a title at all.
    *  Seeded from omp's own message count when the child is spawned, so it
    *  survives an idle reclaim (a `--resume` child reports the messages it
@@ -109,42 +128,10 @@ export interface AutoTitleHost {
   /** True once the early attempt (the first settled user message) has been
    *  made, so a queued steer message cannot re-ask inside the same run. */
   autoTitleRequested: boolean;
-  proc: {
-    sendCommand<T = unknown>(command: { type: string; [key: string]: unknown }, timeoutMs?: number): Promise<T>;
-  };
-}
-
-/**
- * Claim the frames our own `/rename` is about to emit, so the wrapper can keep
- * its diagnostics out of the timeline — and, more importantly, so the
- * `prompt_result {agentInvoked:false}` this background command answers with is
- * not read as "the operator's prompt opened no turn".
- *
- * Called BEFORE the request is sent, never after its ack. omp answers the ack
- * and emits the `prompt_result` in the same tick (measured: 3 ms apart on
- * 18.7.0), while the operator's turn is still streaming — so a window opened
- * after the await is already too late. The `prompt_result` then reached the
- * client, which folds it as "the run settled": the generating indicator blanked
- * and the sidebar's live `stream` row was cleared while the answer kept
- * arriving. `frame-fold` only suppresses the frame when the window is armed, so
- * arming late is exactly the hole this ordering closes.
- *
- * On a send that never reached omp the claim is dropped (see the caller), so a
- * window can never belong to nothing and block the settle-stage fallback.
- */
-export function markTitleRequestSent(host: AutoTitleHost): void {
-  host.autoTitleWindowUntil = Date.now() + AUTO_TITLE_OUTPUT_WINDOW_MS;
-}
-
-/**
- * True when this frame is the tail of our own background rename, consuming the
- * window. One frame per request: omp emits exactly one `command_output` for it,
- * on both the success and the "could not generate" path.
- */
-export function consumeAutoTitleOutput(host: AutoTitleHost): boolean {
-  if (host.autoTitleWindowUntil === 0 || Date.now() > host.autoTitleWindowUntil) return false;
-  host.autoTitleWindowUntil = 0;
-  return true;
+  /** The model the session is actually served by — the pin the title request
+   *  runs under. Null before the child reports one; the request then runs on
+   *  omp's configured role, which is the only honest fallback. */
+  autoTitleModel?: { provider: string; modelId: string } | null;
 }
 
 /**
@@ -176,75 +163,118 @@ export type AutoTitleStage = 'opening' | 'settle';
 /**
  * Ask omp to name this session from its opening turns.
  *
- * Called twice at most, both inside the conversation's first run: once when the
- * first user message settles (`opening`), and once at the terminal `agent_end`
- * as a fallback (`settle`). A second run never gets either — see the module
- * doc for why a title derived from a later turn is the bug this gate prevents.
- *
- * Every bail-out is deliberate: a named session is never renamed by this path
- * (the name is re-read from omp, so a rename made in another tab is respected),
- * a generation already in flight is never duplicated, and failures are
- * swallowed — an auto-title is a convenience, and a session whose opening
- * message was low-signal ("hi") simply keeps its placeholder.
+ * The eligibility gates run SYNCHRONOUSLY, and the request is chained onto the
+ * host's dispatch slot before the first await. That ordering is what lets a
+ * prompt sent right after the run end wait for this rename to reach the child
+ * (`awaitTitleDispatch` in the prompt path) instead of racing it.
  */
-export async function triggerAutoSessionTitle(host: AutoTitleHost, stage: AutoTitleStage): Promise<void> {
-  if (!host.autoTitlePending) return;
+export function triggerAutoSessionTitle(host: AutoTitleHost, stage: AutoTitleStage): Promise<void> {
+  if (!host.autoTitlePending) return Promise.resolve();
   if (stage === 'opening') {
     // One early attempt per run. A queued steer message also settles as a user
     // message inside the same run, and re-asking on it would cancel the first
     // generation for no gain — the context is the same turn either way.
-    if (host.autoTitleRequested) return;
-    // Consumed before the first await: two user messages settling in the same
-    // tick must not both pass the gate.
+    if (host.autoTitleRequested) return Promise.resolve();
+    // Consumed synchronously: two user messages settling in the same tick must
+    // not both pass the gate.
     host.autoTitleRequested = true;
   } else {
     // Consumed before the first await: the fallback is this conversation's last
     // chance, and two settles must never both pass the gate.
     host.autoTitlePending = false;
-    // The early attempt is still generating. Its `command_output` has not
-    // arrived, so omp is mid-generation and a second `/rename` now would
-    // reserve a new title revision and cancel it — same title context, wasted
-    // model call. Leave the early attempt to finish.
-    if (host.autoTitleWindowUntil > Date.now()) return;
   }
-  if (host.autoTitleInFlight || !host.sessionId) return;
+  if (!host.sessionId) return Promise.resolve();
+
+  // Captured before this run claims the slot: the run's own dispatch queues
+  // behind what was already in flight, not behind itself.
+  const previous = host.autoTitleDispatch;
+  // Two different promises, deliberately:
+  //   - the DISPATCH resolves when the request is on the wire (or the gate
+  //     decided not to send). That is what a following prompt waits for, and
+  //     what the next request is chained behind;
+  //   - the returned REQUEST resolves when the model pin has been released,
+  //     which is after the generation answered — a title model can take a
+  //     minute, and no prompt should wait for that.
+  const dispatched = Promise.withResolvers<void>();
+  const run = runTitleRequest(host, previous, dispatched.resolve);
+  const barrier = dispatched.promise;
+  host.autoTitleDispatch = barrier;
+  void barrier.then(() => {
+    if (host.autoTitleDispatch === barrier) host.autoTitleDispatch = null;
+  });
+  return run.then(
+    () => undefined,
+    () => undefined,
+  );
+}
+
+/** The gated part: settings, the unnamed check, the model pin, the send. */
+async function runTitleRequest(
+  host: AutoTitleHost,
+  after: Promise<void> | null,
+  onDispatched: () => void,
+): Promise<void> {
+  let released = false;
+  const release = () => {
+    if (released) return;
+    released = true;
+    onDispatched();
+  };
+  try {
+    await dispatchTitleRequest(host, after, release);
+  } finally {
+    // Every exit — a disabled setting, a named session, a failed send — must
+    // release the barrier: a prompt waiting on it pays the ceiling otherwise.
+    release();
+  }
+}
+
+async function dispatchTitleRequest(
+  host: AutoTitleHost,
+  after: Promise<void> | null,
+  onDispatched: () => void,
+): Promise<void> {
   if (!(await isAutoTitleEnabled())) return;
 
-  host.autoTitleInFlight = true;
+  let state: RpcSessionState;
   try {
     // Re-read the name from omp rather than trusting a cached value: a rename
     // made in another tab (or by omp's own TUI on the same session file) would
     // otherwise be overwritten by the `"user"` write `/rename` performs. This is
     // also what makes the fallback a no-op when the early attempt already
     // landed — the name is simply there by then.
-    const state = await host.proc.sendCommand<RpcSessionState>({ type: 'get_state' }, GET_STATE_TIMEOUT_MS);
-    if (state.sessionName?.trim()) return;
-    // The session changed under us (a reset, or a `switch_session`): the name
-    // we just read belongs to a different conversation.
-    if (state.sessionId !== host.sessionId) return;
-
-    // Direct `proc` write, NOT Kabmo's prompt dispatch: this is
-    // background work, so it must not mark the session streaming or claim the
-    // sidebar's run row. omp's ack is immediate (`agentInvoked:false`); the
-    // generation itself streams back later as ordinary frames.
-    //
-    // The claim is armed BEFORE the send, not after its ack: omp emits the
-    // `prompt_result {agentInvoked:false}` that answers this command within
-    // milliseconds, and the fold can only suppress it while the window is open
-    // (see `markTitleRequestSent`). An armed window is rolled back if the send
-    // never reached omp, so it cannot outlive a request that did not happen.
-    markTitleRequestSent(host);
-    try {
-      await host.proc.sendCommand({ type: 'prompt', message: GENERATE_TITLE_COMMAND }, PROMPT_ACK_TIMEOUT_MS);
-    } catch (error) {
-      host.autoTitleWindowUntil = 0;
-      throw error;
-    }
+    state = await host.proc.sendCommand<RpcSessionState>({ type: 'get_state' }, GET_STATE_TIMEOUT_MS);
   } catch {
     // Provider error, timeout, or a child that went away — leave the session
-    // unnamed; the settle attempt (or the next run, for an aborted turn) tries
-    // again.
-  } finally {
-    host.autoTitleInFlight = false;
+    // unnamed rather than naming the wrong conversation.
+    return;
   }
+  if (state.sessionName?.trim()) return;
+  // The session changed under us (a reset, or a `switch_session`): the name we
+  // just read belongs to a different conversation.
+  if (state.sessionId !== host.sessionId) return;
+
+  const model = host.autoTitleModel;
+  const selector = model ? `${model.provider}/${model.modelId}` : undefined;
+  await withTitleModelOverride(selector, async () => {
+    try {
+      // Direct `proc` write, NOT Kabmo's prompt dispatch: this is background
+      // work, so it must not mark the session streaming or claim the sidebar's
+      // run row. omp's ack is immediate (`agentInvoked:false`); the generation
+      // itself streams back later as ordinary frames.
+      await sendTitleRequest(host, GENERATE_TITLE_COMMAND, after);
+    } finally {
+      // The request is on the wire (or refused): a prompt waiting on this
+      // rename must be released now, not after the generation.
+      onDispatched();
+    }
+    // The pin is held across the generation, not just the dispatch: omp
+    // resolves the title role again for the card request that follows a
+    // successful title, and releasing it there names the session with the
+    // configured role — the failure the pin exists to avoid.
+    await waitForTitleOutcome(host);
+  }).catch(() => {
+    // A refused send or a cancelled generation leaves the session unnamed; the
+    // other stage (or nothing) is the honest outcome.
+  });
 }

package/src/server/lib/omp/session/rename-with-ai.server.test.ts

@@ -35,7 +35,9 @@ interface FakeProc {
   sent: Promise<void>;
 }
 
-function makeHost(options: { sendFails?: boolean } = {}): { host: TitleFrameHost; proc: FakeProc } {
+function makeHost(
+  options: { sendFails?: boolean; onSend?: (host: TitleFrameHost) => void } = {},
+): { host: TitleFrameHost; proc: FakeProc } {
   const listeners = new Set<(frame: Frame) => void>();
   const sent = Promise.withResolvers<void>();
   const proc: FakeProc = {
@@ -46,6 +48,7 @@ function makeHost(options: { sendFails?: boolean } = {}): { host: TitleFrameHost
     },
     async sendCommand<T>(command: { type: string; [key: string]: unknown }): Promise<T> {
       proc.commands.push(command);
+      options.onSend?.(host);
       sent.resolve();
       if (options.sendFails) throw new Error('omp RPC process has exited');
       // omp acks /rename before it has a title — the case that makes waiting
@@ -56,10 +59,12 @@ function makeHost(options: { sendFails?: boolean } = {}): { host: TitleFrameHost
 
   const host = {
     sessionId: 'sess-1',
-    autoTitleInFlight: false,
     autoTitleWindowUntil: 0,
+    autoTitleClaims: 0,
+    autoTitleDispatch: null,
     autoTitlePending: false,
     autoTitleRequested: false,
+    autoTitleModel: null,
     proc: {
       sendCommand: proc.sendCommand,
       onFrame(listener: (frame: Frame) => void) {
@@ -117,14 +122,21 @@ describe('renameSessionWithAi frame handling', () => {
   });
 
   test('the request claims the output window before sending, so the frames stay out of the timeline', async () => {
-    const { host, proc } = makeHost();
+    let claimsAtSend = -1;
+    const { host, proc } = makeHost({
+      onSend: (h) => {
+        claimsAtSend = h.autoTitleClaims;
+      },
+    });
     const pending = awaitTitleFrame(host);
 
-    // Claimed synchronously with the call, not on the ack — a title frame that
-    // overtakes the ack must still be attributed to this request.
+    // Armed before the `prompt` reaches the wire, not on its ack: omp answers
+    // within the same tick (measured ~3 ms), so a claim armed after the ack can
+    // already be too late for the frame it was meant to cover.
+    await proc.sent;
+    expect(claimsAtSend).toBe(1);
     expect(host.autoTitleWindowUntil).toBeGreaterThan(Date.now());
 
-    await proc.sent;
     proc.emit({ type: 'session_info_update', title: 'Named' });
     await pending;
   });

package/src/server/lib/omp/session/rename-with-ai.server.ts

@@ -36,9 +36,13 @@
  */
 
 import { getRpcSession, resolveSpawnCwd, startRpcSession } from '@/server/lib/omp/rpc/manager';
-import { PROMPT_ACK_TIMEOUT_MS } from '@/server/lib/omp/rpc/constants';
 import { resolveSessionPathOr404 } from '@/server/lib/omp/session/locator';
-import { markTitleRequestSent, type AutoTitleHost } from '@/server/lib/omp/session/auto-title.server';
+import type { AutoTitleHost } from '@/server/lib/omp/session/auto-title.server';
+import {
+  GENERATE_TITLE_COMMAND,
+  releaseTitleClaim,
+  sendTitleRequest,
+} from '@/server/lib/omp/session/title-request.server';
 import { resolveSessionOwnership, SessionOwnedElsewhereError } from '@/server/lib/omp/session/ownership.server';
 import { clearSessionFileCaches } from '@/server/lib/omp/session/files';
 import { loadSessionModel } from '@/server/lib/omp/session/messages';
@@ -169,29 +173,41 @@ export function awaitTitleFrame(host: TitleFrameHost): Promise<RenameWithAiResul
   });
 
   const timer = setTimeout(() => {
+    // A request that never answered can never be answered: drop its claim, or
+    // it would swallow the operator's next `command_output` as "our rename".
+    releaseTitleClaim(host);
     finish({ ok: false, error: 'Timed out waiting for a generated title.', status: 504 });
   }, GENERATE_TIMEOUT_MS);
   // A pending generation must never hold the event loop open on its own.
   timer.unref?.();
 
-  // The window is claimed BEFORE the send, not after its ack: omp's response to
-  // the prompt and the rename's own frames are separate frames, and a fast
-  // child could deliver the title first — in which case a window marked on the
-  // ack would let that one frame through to the timeline. A send that never
-  // reached omp clears it again, so nothing is left claimed.
-  markTitleRequestSent(host);
-  void (async () => {
-    try {
-      await host.proc.sendCommand({ type: 'prompt', message: '/rename' }, PROMPT_ACK_TIMEOUT_MS);
-    } catch (error) {
-      host.autoTitleWindowUntil = 0;
-      finish({
-        ok: false,
-        error: error instanceof Error ? error.message : String(error),
-        status: 502,
-      });
-    }
-  })();
+  // The claim is armed by the shared dispatcher BEFORE the send (and released
+  // by it if the send never reached omp), so the `command_output` this request
+  // answers with stays out of the timeline. The claim is deliberately NOT
+  // released on the success frame: omp emits `session_info_update` first and
+  // the `command_output` a few milliseconds later, and releasing on the title
+  // would let that second frame render as a notice row.
+  //
+  // The dispatch slot is claimed SYNCHRONOUSLY, before the first await, so a
+  // prompt the operator sends while this rename is still generating waits for
+  // it instead of racing it (`awaitTitleDispatch` in the prompt path).
+  const previous = host.autoTitleDispatch ?? null;
+  const request = sendTitleRequest(host, GENERATE_TITLE_COMMAND, previous);
+  const dispatched = request.then(
+    () => undefined,
+    () => undefined,
+  );
+  host.autoTitleDispatch = dispatched;
+  void dispatched.then(() => {
+    if (host.autoTitleDispatch === dispatched) host.autoTitleDispatch = null;
+  });
+  void request.catch((error: unknown) => {
+    finish({
+      ok: false,
+      error: error instanceof Error ? error.message : String(error),
+      status: 502,
+    });
+  });
 
   return promise;
 }

package/src/server/lib/omp/session/title-model-overlay.server.test.ts

@@ -128,25 +128,40 @@ describe('title-model overlay', () => {
     expect(readFileSync(path, 'utf8')).toBe('{}\n');
   });
 
-  test('concurrent overrides are serialized, so one cannot reset the other mid-flight', async () => {
+  test('concurrent overrides are newest-wins, and the last holder releases the pin', async () => {
+    // The overlay is ONE file for every session, and a title model can take a
+    // minute — queueing a second request behind the first would make the
+    // operator's next prompt wait on a generation it has nothing to do with.
+    // So the most recent request owns the file, and the file is cleared only
+    // when no request holds it.
     const { withTitleModelOverride, ensureTitleModelOverlay, titleModelOverlayPath } = await overlay();
     ensureTitleModelOverlay();
     const path = titleModelOverlayPath();
-    const order: string[] = [];
+    const seen: string[] = [];
+    const releaseFirst = Promise.withResolvers<void>();
+    const firstHolds = Promise.withResolvers<void>();
+
+    const first = withTitleModelOverride('first/model', async () => {
+      expect(readFileSync(path, 'utf8')).toContain('first/model');
+      seen.push('first');
+      firstHolds.resolve();
+      // Still generating when the second request arrives.
+      await releaseFirst.promise;
+    });
+    await firstHolds.promise;
 
-    await Promise.all([
-      withTitleModelOverride('first/model', async () => {
-        expect(readFileSync(path, 'utf8')).toContain('first/model');
-        order.push('first');
-      }),
-      withTitleModelOverride('second/model', async () => {
-        // The first has already reset by the time this one runs.
-        expect(readFileSync(path, 'utf8')).toContain('second/model');
-        order.push('second');
-      }),
-    ]);
+    const second = withTitleModelOverride('second/model', async () => {
+      // The newer request owns the file even though the older one is running.
+      expect(readFileSync(path, 'utf8')).toContain('second/model');
+      seen.push('second');
+    });
+    await second;
+
+    // The older holder leaving must NOT clear the newer pin.
+    releaseFirst.resolve();
+    await first;
 
-    expect(order).toEqual(['first', 'second']);
+    expect(seen).toEqual(['first', 'second']);
     expect(readFileSync(path, 'utf8')).toBe('{}\n');
   });
 });

package/src/server/lib/omp/session/title-model-overlay.server.ts

@@ -120,42 +120,63 @@ async function writeOverlay(selector: string | undefined): Promise<void> {
 }
 
 /**
- * Serializes the write → settle → run → reset sequence.
+ * Holders of the pin, and the selector each asked for.
  *
- * The overlay is ONE file for every session, so two concurrent renames would
- * otherwise interleave: the second's write would land inside the first's
- * generation and reset the role out from under it. Renames are user-initiated
- * and rare, so queueing them costs nothing a user can perceive.
+ * The overlay is ONE file for every session, so a pin cannot be "owned" by one
+ * request while another waits: a title model can take a minute, and queueing
+ * the second request behind the first would make the operator's next prompt
+ * wait on a generation it has nothing to do with. Instead the pin is
+ * NEWEST-WINS — every holder is recorded, the file always carries the most
+ * recent selector, and the file is cleared only when the last holder leaves.
+ * A request that is superseded mid-generation is one omp cancels anyway
+ * (`renameTitle` reserves a title revision), so it loses nothing it could have
+ * kept.
  */
-let queue: Promise<unknown> = Promise.resolve();
+interface PinHolder {
+  selector: string;
+  order: number;
+}
+const holders = new Set<PinHolder>();
+let nextOrder = 1;
+/** Serializes the FILE writes; a write is one atomic replace, never held. */
+let writeQueue: Promise<unknown> = Promise.resolve();
 
-const wait = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
+/** Write the selector the current holders agree on (newest wins), or clear. */
+function syncOverlay(): Promise<void> {
+  const newest = [...holders].sort((a, b) => b.order - a.order)[0];
+  const selector = newest?.selector;
+  const run = writeQueue.then(() => writeOverlay(selector));
+  writeQueue = run.then(
+    () => undefined,
+    () => undefined,
+  );
+  return run;
+}
 
 /**
- * Run `fn` with the title role pointed at `selector`, then restore the overlay
- * to its empty state.
+ * Run `fn` with the title role pointed at `selector`, and release the pin when
+ * `fn` settles.
  *
  * `selector` of `undefined` (a session whose model cannot be read) runs `fn`
  * untouched: naming a session with a model the conversation never used is worse
- * than the role the user configured. The reset is in a `finally`, so a refused
+ * than the role the user configured. The release is in a `finally`, so a refused
  * or failed rename cannot leave the role pinned for the next child that loads
  * the overlay.
+ *
+ * `fn` should resolve when the generation is DONE, not when the request is
+ * dispatched: omp resolves the title role again for the card request that
+ * follows a successful title, so releasing on the ack names the session with
+ * the configured role — the failure this pin exists to prevent.
  */
 export function withTitleModelOverride<T>(selector: string | undefined, fn: () => Promise<T>): Promise<T> {
   if (!selector) return fn();
-  const run = queue.then(async () => {
-    await writeOverlay(selector);
-    await wait(OVERLAY_SETTLE_MS);
-    try {
-      return await fn();
-    } finally {
-      await writeOverlay(undefined);
-    }
-  });
-  // Keep the chain alive on failure without swallowing the caller's rejection.
-  queue = run.then(
-    () => undefined,
-    () => undefined,
-  );
-  return run;
+  const holder: PinHolder = { selector, order: nextOrder++ };
+  holders.add(holder);
+  return syncOverlay()
+    .then(() => Bun.sleep(OVERLAY_SETTLE_MS))
+    .then(fn)
+    .finally(async () => {
+      holders.delete(holder);
+      await syncOverlay();
+    });
 }