ompchamber 3.5.0 → 3.6.0

package/src/server/lib/omp/config/skills.ts

@@ -4,90 +4,302 @@
  */
 
 /**
- * Native OMP skill discovery — scans SKILL.md files under ~/.omp/agent/skills
- * and <project>/.omp/skills so the settings skills list reflects the skills
- * the omp agent actually loads. Supports atomic frontmatter toggles
- * (disableModelInvocation) for real skill files.
+ * Skill discovery and SKILL.md authoring for the chamber's Skills settings.
+ *
+ * Discovery is delegated to `omp skill list <dir> --json` rather than
+ * re-implemented here. omp's own resolver is the only thing that knows every
+ * root it reads — `.omp/skills` (project walk-up), `~/.omp/agent/skills`,
+ * `.claude`, `.agents`, `.codex`, `.github`, `.opencode`, plugin packages, the
+ * skillshare store — plus the `skills.*` settings gates and the frontmatter
+ * rules (`enabled: false`, a missing `description`, `hide`). A hand-rolled scan
+ * of two directories silently disagreed with the agent: it listed skills the
+ * agent could not run and hid the ones it could (measured: 6 shown vs 9 loaded
+ * in this repository, and a catalog install into `~/.agents/skills` was
+ * invisible to the chamber while omp ran it happily).
+ *
+ * `omp skill list` is cheap (measured 0.38-0.42s, no session, no model) and is
+ * cached per directory for a few seconds so a panel poll or a settings reload
+ * does not spawn a process per request.
+ *
+ * Writing is deliberately narrow: only the two roots the chamber owns as
+ * omp-native skills (`~/.omp/agent/skills` and `<workspace>/.omp/skills`) can
+ * be created in, edited or deleted. A skill from another provider (a Claude
+ * plugin, a registry package) is read-only here — the chamber is not its
+ * owner, and deleting a file another tool manages is not a "delete skill".
  */
 
 import fs from 'fs';
-import { join } from 'path';
+import { join, resolve } from 'path';
 import { getAgentDir, pathExists } from '@/server/lib/omp/core/paths';
+import { resolveOmpBin } from '@/server/lib/omp/core/cli';
 import { writeFileAtomic } from '@/server/lib/fs/atomic-write';
 import { parseFrontmatter } from '@/server/lib/omp/config/yaml';
 
 const MAX_SKILL_MD_BYTES = 512 * 1024;
+const SKILL_LIST_TIMEOUT_MS = 30_000;
+/** Discovery spawns a process, so a short cache absorbs the panel poll and the
+ *  composer's own fetch without ever serving a stale list for long. */
+const CACHE_TTL_MS = 5_000;
 
 export interface DiscoveredSkill {
+  /** Stable id: `omp-<user|project>-<name>`. */
   id: string;
   name: string;
   description: string;
-  /** Which disk root the skill was discovered from. */
+  /** omp's provider:level source, e.g. `native:user`, `agents:project`. */
+  source: string;
   sourceRoot: 'user' | 'project';
   filePath: string;
+  baseDir: string;
+  /** Excluded from the model's skill listing (`hide` / disableModelInvocation). */
+  hidden: boolean;
+  /** True when the chamber owns the files and may rewrite or remove them. */
+  managed: boolean;
 }
 
-async function parseSkillMd(filePath: string, sourceRoot: 'user' | 'project'): Promise<DiscoveredSkill | undefined> {
+declare global {
+  // eslint-disable-next-line no-var
+  var __ompSkillListCache: Map<string, { at: number; skills: DiscoveredSkill[] }> | undefined;
+}
+
+function getCache(): Map<string, { at: number; skills: DiscoveredSkill[] }> {
+  if (!globalThis.__ompSkillListCache) globalThis.__ompSkillListCache = new Map();
+  return globalThis.__ompSkillListCache;
+}
+
+/** Drop the discovery cache so the next read reflects a write just made. */
+export function invalidateSkillCache(): void {
+  getCache().clear();
+}
+
+/**
+ * The omp-native roots the chamber may create, edit and delete in — and the
+ * only directories a `delete` may touch. A skill folder sits directly under one
+ * of these.
+ */
+export function managedSkillRoots(projectDir?: string | null): string[] {
+  const roots = [join(getAgentDir(), 'skills')];
+  if (projectDir) roots.push(join(projectDir, '.omp', 'skills'));
+  return roots;
+}
+
+/** A skill the chamber owns: omp-native AND sitting directly under a managed
+ *  root. Everything else (a Claude plugin, a registry package) is read-only. */
+function isManagedSkill(skill: { source: string; baseDir: string }, projectDir?: string | null): boolean {
+  if (!skill.source.startsWith('native:')) return false;
+  const parent = resolve(skill.baseDir, '..');
+  return managedSkillRoots(projectDir).some((root) => resolve(root) === parent);
+}
+
+interface CliSkill {
+  name?: unknown;
+  description?: unknown;
+  filePath?: unknown;
+  baseDir?: unknown;
+  source?: unknown;
+  hide?: unknown;
+}
+
+/**
+ * Enumerate the skills an omp session in `cwd` would load, through omp itself.
+ * `projectDir` is the workspace the list is being shown for — it decides which
+ * roots count as chamber-managed, and is NOT the same thing as `cwd` for the
+ * user scope (whose cwd is the agent dir, which is not a workspace).
+ * Returns [] when omp is not installed or the directory is unreadable; a
+ * discovery failure must never surface as "you have no skills" being fatal.
+ */
+export async function discoverSkills(
+  cwd?: string | null,
+  projectDir?: string | null,
+): Promise<DiscoveredSkill[]> {
+  const bin = resolveOmpBin();
+  if (!bin) return [];
+
+  // A missing cwd falls back to the agent dir — the user scope — because that
+  // is the only cwd whose inventory is a real scope rather than the server's
+  // own working directory.
+  const target = cwd && (await pathExists(cwd)) ? cwd : getAgentDir();
+  const cache = getCache();
+  const cached = cache.get(target);
+  if (cached && Date.now() - cached.at < CACHE_TTL_MS) return cached.skills;
+
+  const skills = await runSkillList(bin, target, projectDir ?? null);
+  cache.set(target, { at: Date.now(), skills });
+  return skills;
+}
+
+async function runSkillList(bin: string, cwd: string, projectDir: string | null): Promise<DiscoveredSkill[]> {
+  let stdout: string;
+  try {
+    const proc = Bun.spawn({
+      cmd: [bin, 'skill', 'list', cwd, '--json'],
+      stdout: 'pipe',
+      stderr: 'pipe',
+      timeout: SKILL_LIST_TIMEOUT_MS,
+      maxBuffer: 8 * 1024 * 1024,
+      windowsHide: true,
+    });
+    const [out, err] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+    ]);
+    const exitCode = await proc.exited;
+    if (exitCode !== 0) {
+      console.error(`omp skill list failed (${exitCode}): ${err.trim().slice(0, 400)}`);
+      return [];
+    }
+    stdout = out;
+  } catch (error) {
+    console.error(`omp skill list failed: ${error instanceof Error ? error.message : String(error)}`);
+    return [];
+  }
+
+  let parsed: { skills?: unknown };
+  try {
+    parsed = JSON.parse(stdout);
+  } catch {
+    return [];
+  }
+  if (!Array.isArray(parsed.skills)) return [];
+
+  const result: DiscoveredSkill[] = [];
+  for (const raw of parsed.skills as CliSkill[]) {
+    const name = typeof raw.name === 'string' ? raw.name.trim() : '';
+    const filePath = typeof raw.filePath === 'string' ? raw.filePath : '';
+    if (!name || !filePath) continue;
+    const source = typeof raw.source === 'string' ? raw.source : 'native:user';
+    const baseDir = typeof raw.baseDir === 'string' && raw.baseDir ? raw.baseDir : resolve(filePath, '..');
+    result.push({
+      id: `omp-${source.endsWith(':project') ? 'project' : 'user'}-${name}`,
+      name,
+      description: typeof raw.description === 'string' ? raw.description : '',
+      source,
+      sourceRoot: source.endsWith(':project') ? 'project' : 'user',
+      filePath,
+      baseDir,
+      hidden: raw.hide === true,
+      managed: isManagedSkill({ source, baseDir }, projectDir),
+    });
+  }
+  return result;
+}
+
+/** Read one skill's SKILL.md, split into frontmatter data and body. */
+export async function readSkillFile(
+  filePath: string,
+): Promise<{ description: string; body: string; hidden: boolean } | null> {
   try {
     const file = Bun.file(filePath);
-    if ((await file.stat()).size > MAX_SKILL_MD_BYTES) return undefined;
+    if (!(await file.exists()) || (await file.stat()).size > MAX_SKILL_MD_BYTES) return null;
     const text = await file.text();
-    const { data } = parseFrontmatter(text);
-    const name = data.name || filePath.split('/').slice(-2, -1)[0] || '';
-    if (!name) return undefined;
+    const { data, body } = parseFrontmatter(text);
     return {
-      id: `omp-${sourceRoot}-${name}`,
-      name,
-      description: data.description || '',
-      sourceRoot,
-      filePath,
+      description: data.description ?? '',
+      body: body.replace(/^\r?\n/, ''),
+      hidden: data.disableModelInvocation === 'true' || data.hide === 'true',
     };
   } catch {
-    return undefined;
+    return null;
   }
 }
 
-/**
- * Scan one skill root: either a flat dir of skill folders (each containing a
- * SKILL.md) or nested layouts — any SKILL.md within depth 2 is accepted.
- */
-async function scanSkillRoot(root: string, sourceRoot: 'user' | 'project'): Promise<DiscoveredSkill[]> {
-  if (!(await pathExists(root))) return [];
-  const found: DiscoveredSkill[] = [];
-  try {
-    const entries = await fs.promises.readdir(root, { withFileTypes: true });
-    for (const entry of entries) {
-      if (!entry.isDirectory()) continue;
-      const skillMd = join(root, entry.name, 'SKILL.md');
-      const skill = await parseSkillMd(skillMd, sourceRoot);
-      if (skill) found.push(skill);
+/** A skill name that is safe as a single directory component. */
+function assertSafeName(name: string): string {
+  const trimmed = name.trim();
+  if (!trimmed) throw new Error('Skill name is required');
+  if (/[\\/]/.test(trimmed) || trimmed === '.' || trimmed === '..') {
+    throw new Error('Skill name may not contain a path separator');
+  }
+  return trimmed;
+}
+
+/** Serialize a SKILL.md from its parts. `description` is mandatory for omp to
+ *  load the skill at all, so it is always written as a frontmatter field. */
+function serializeSkillMd(input: { name: string; description: string; hidden: boolean; body: string }): string {
+  const lines = ['---', `name: ${JSON.stringify(input.name)}`, `description: ${JSON.stringify(input.description)}`];
+  if (input.hidden) lines.push('disableModelInvocation: true');
+  lines.push('---', '', input.body.replace(/\r\n/g, '\n').replace(/\s*$/, ''), '');
+  return lines.join('\n');
+}
+
+export interface WriteSkillInput {
+  /** Target root: `user` writes to the agent dir, `project` to the workspace. */
+  scope: 'user' | 'project';
+  /** Workspace root, required for `project`. */
+  projectDir?: string | null;
+  /** Base directory of the skill being edited, when it already exists. */
+  previousDir?: string | null;
+  name: string;
+  description: string;
+  hidden: boolean;
+  body: string;
+}
+
+/** Create or overwrite a chamber-managed SKILL.md. Refuses a scope it cannot
+ *  own (a project write with no workspace) rather than writing somewhere else. */
+export async function writeSkillFile(input: WriteSkillInput): Promise<{ filePath: string }> {
+  const name = assertSafeName(input.name);
+  if (input.scope === 'project' && !input.projectDir) {
+    throw new Error('A workspace root is required to write a project skill');
+  }
+  const root = input.scope === 'project' ? join(input.projectDir!, '.omp', 'skills') : join(getAgentDir(), 'skills');
+
+  const dir = join(root, name);
+  const filePath = join(dir, 'SKILL.md');
+
+  // A rename or a scope move is a move: the old directory must not linger as a
+  // second skill. It is removed only when it is a DIFFERENT directory inside a
+  // managed root, so an edit in place never deletes the file just written and a
+  // move across scopes cleans up the source.
+  const previous = input.previousDir?.trim();
+  if (previous) {
+    const oldDir = resolve(previous);
+    if (oldDir !== resolve(dir)) {
+      const parent = resolve(oldDir, '..');
+      if (managedSkillRoots(input.projectDir).some((candidate) => resolve(candidate) === parent)) {
+        if (await pathExists(oldDir)) await fs.promises.rm(oldDir, { recursive: true, force: true });
+      }
     }
-  } catch {
-    // Unreadable root yields no skills rather than throwing.
   }
-  return found;
+
+  await fs.promises.mkdir(dir, { recursive: true });
+  await writeFileAtomic(
+    filePath,
+    serializeSkillMd({ name, description: input.description, hidden: input.hidden, body: input.body }),
+    { createMode: 0o644 },
+  );
+  invalidateSkillCache();
+  return { filePath };
 }
 
 /**
- * Discover native skills from user + optional project roots. User skills win
- * over project skills with the same folder name. Never throws.
+ * Delete a chamber-managed skill directory. Refused unless the target is an
+ * omp-native skill sitting directly under a managed root, so a delete can never
+ * reach a skill another tool installed.
  */
-export async function discoverNativeSkills(projectDir?: string): Promise<DiscoveredSkill[]> {
-  const userRoot = join(getAgentDir(), 'skills');
-  const projectRoot = projectDir ? join(projectDir, '.omp', 'skills') : undefined;
-  const byName = new Map<string, DiscoveredSkill>();
-  for (const skill of await scanSkillRoot(userRoot, 'user')) byName.set(skill.name, skill);
-  if (projectRoot) {
-    for (const skill of await scanSkillRoot(projectRoot, 'project')) {
-      if (!byName.has(skill.name)) byName.set(skill.name, skill);
-    }
+export async function deleteSkillDir(id: string, projectDir?: string | null): Promise<boolean> {
+  // A user-scope delete (no workspace) is discovered from the agent dir, which
+  // is also the only managed root that applies there.
+  const found = (await discoverSkills(projectDir ?? getAgentDir(), projectDir)).find((skill) => skill.id === id);
+  if (!found) return false;
+  if (!found.managed) throw new Error(`"${found.name}" is managed by ${found.source}; the chamber cannot delete it`);
+
+  const dir = resolve(found.baseDir);
+  const parent = resolve(dir, '..');
+  if (!managedSkillRoots(projectDir).some((root) => resolve(root) === parent)) {
+    throw new Error(`Refusing to delete outside the managed skill roots: ${dir}`);
   }
-  return [...byName.values()];
+  if (!(await pathExists(dir))) return false;
+  await fs.promises.rm(dir, { recursive: true, force: true });
+  invalidateSkillCache();
+  return true;
 }
 
 /**
  * Atomically toggle `disableModelInvocation` in a SKILL.md frontmatter —
- * read-modify-write via temp+rename, preserving the rest of the file.
+ * read-modify-write via temp+rename, preserving the rest of the file. The
+ * skill stays loadable through `skill://` and `/skill:<name>`; it only drops
+ * out of the model's `<skills>` listing.
  */
 export async function setSkillModelInvocation(filePath: string, disable: boolean): Promise<boolean> {
   try {
@@ -111,6 +323,7 @@ export async function setSkillModelInvocation(filePath: string, disable: boolean
     }
     if (next === text) return false;
     await writeFileAtomic(filePath, next);
+    invalidateSkillCache();
     return true;
   } catch {
     return false;

package/src/server/lib/omp/rpc/process.ts

@@ -15,6 +15,7 @@
  */
 
 import type { Subprocess } from 'bun';
+import { describeSpawnFailure } from '@/server/lib/lifecycle/fd-pressure';
 import { resolveOmpBin } from '@/server/lib/omp/core/cli';
 import { RpcFrameDecoder, encodeRpcFrames, type RpcFrameRecord, type RpcProtocolVersion } from '@/shared/lib/omp/rpc/frame';
 import { killProcessTree } from '@/server/lib/omp/rpc/kill-tree';
@@ -57,20 +58,27 @@ export class RpcProcess {
     const childEnv = sanitizeProjectCommandEnvironment({ ...Bun.env, ...options.env });
     if (options.env?.OMP_PROFILE === undefined) delete childEnv.OMP_PROFILE;
     if (options.env?.PI_PROFILE === undefined) delete childEnv.PI_PROFILE;
-    this.child = Bun.spawn({
-      cmd: [bin, ...args],
-      cwd: options.cwd,
-      env: childEnv,
-      stdin: 'pipe',
-      stdout: 'pipe',
-      stderr: 'pipe',
-      windowsHide: true,
-      // On POSIX, omp launches grandchildren (LSP servers, extension subprocesses). Run the
-      // child in its own process group so dispose() can SIGTERM/SIGKILL the whole
-      // tree — otherwise a crashed omp would orphan its LSP children as zombies.
-      // Windows uses taskkill /t instead, so detaching would only create a console.
-      detached: process.platform !== 'win32',
-    });
+    // A spawn fails synchronously when the process is out of descriptors, and
+    // Bun's own `EBADF` names the binary rather than the cause; `status` and
+    // the terminal panel are the diagnostics, so the message has to be right.
+    try {
+      this.child = Bun.spawn({
+        cmd: [bin, ...args],
+        cwd: options.cwd,
+        env: childEnv,
+        stdin: 'pipe',
+        stdout: 'pipe',
+        stderr: 'pipe',
+        windowsHide: true,
+        // On POSIX, omp launches grandchildren (LSP servers, extension subprocesses). Run the
+        // child in its own process group so dispose() can SIGTERM/SIGKILL the whole
+        // tree — otherwise a crashed omp would orphan its LSP children as zombies.
+        // Windows uses taskkill /t instead, so detaching would only create a console.
+        detached: process.platform !== 'win32',
+      });
+    } catch (error) {
+      throw new Error(describeSpawnFailure(error));
+    }
 
     let resolveReady: (frame: RpcFrame) => void;
     let rejectReady: (error: Error) => void;

package/src/server/lib/omp/rpc/session-registry.ts

@@ -43,6 +43,12 @@ export function getRpcSession(sessionId: string): AgentSessionWrapper | undefine
   return getRegistry().get(sessionId);
 }
 
+/** Every live session wrapper, for operations that must reach all of them
+ *  (a plugin/skill reload) rather than one addressed id. */
+export function listRpcSessions(): AgentSessionWrapper[] {
+  return [...getRegistry().values()].filter((session) => session.isAlive());
+}
+
 /**
  * Sessions whose omp process is parked on a dialog only the user can release —
  * an `ask` question or an approval gate. Deliberately independent of

package/src/server/lib/omp/rpc/utility.ts

@@ -72,37 +72,57 @@ interface UtilityRpcState {
 
 declare global {
   // eslint-disable-next-line no-var
-  var __ompUtilityRpcState: UtilityRpcState | undefined;
+  var __ompUtilityRpcStates: Map<string, UtilityRpcState> | undefined;
 }
 
-function getState(): UtilityRpcState {
-  if (!globalThis.__ompUtilityRpcState) {
-    globalThis.__ompUtilityRpcState = { proc: null, idleTimer: null, queue: Promise.resolve() };
-    // Dispose the shared utility omp process on server shutdown so it does not
-    // outlive the server. Idempotent and safe to call any time.
+/**
+ * Utility processes are pooled PER WORKING DIRECTORY, because a cwd is not just
+ * a spawn detail: omp resolves project-scope config from it. `.omp/commands`,
+ * `.omp/skills`, `.claude`, `.agents` and `AGENTS.md` in a workspace are only
+ * discovered by a child started in that workspace (measured: a child in $HOME
+ * reported 7 skill entries and one `file` command; the same child in a repo
+ * reported 9 and the repo's own command). One process per cwd keeps the global
+ * registry queries (`get_available_models`, `get_login_providers`) on the
+ * cheap home-scoped child while letting a workspace-scoped read see its own
+ * project config. Each pool entry is idle-killed on its own timer.
+ */
+function getState(cwd: string): UtilityRpcState {
+  if (!globalThis.__ompUtilityRpcStates) {
+    globalThis.__ompUtilityRpcStates = new Map();
+    // Dispose every pooled process on server shutdown so none outlives the
+    // server. Idempotent and safe to call any time.
     const cleanup = () => disposeUtilityRpc();
     process.once('exit', cleanup);
     process.once('SIGINT', cleanup);
     process.once('SIGTERM', cleanup);
   }
-  return globalThis.__ompUtilityRpcState;
+  const states = globalThis.__ompUtilityRpcStates;
+  let state = states.get(cwd);
+  if (!state) {
+    state = { proc: null, idleTimer: null, queue: Promise.resolve() };
+    states.set(cwd, state);
+  }
+  return state;
 }
 
 /**
- * Tear down the shared utility omp process immediately (skip the idle timer).
- * Safe to call any time — it just clears any pending idle kill and disposes
- * the live child.
+ * Tear down the shared utility omp processes immediately (skip the idle
+ * timers). Safe to call any time — it just clears any pending idle kill and
+ * disposes the live children.
  */
 export function disposeUtilityRpc(): void {
-  const state = globalThis.__ompUtilityRpcState;
-  if (!state) return;
-  if (state.idleTimer) {
-    clearTimeout(state.idleTimer);
-    state.idleTimer = null;
+  const states = globalThis.__ompUtilityRpcStates;
+  if (!states) return;
+  for (const state of states.values()) {
+    if (state.idleTimer) {
+      clearTimeout(state.idleTimer);
+      state.idleTimer = null;
+    }
+    const proc = state.proc;
+    state.proc = null;
+    if (proc) void proc.dispose();
   }
-  const proc = state.proc;
-  state.proc = null;
-  if (proc) void proc.dispose();
+  states.clear();
 }
 
 function scheduleIdleKill(state: UtilityRpcState): void {
@@ -116,9 +136,9 @@ function scheduleIdleKill(state: UtilityRpcState): void {
   state.idleTimer.unref?.();
 }
 
-async function startProcess(state: UtilityRpcState): Promise<RpcProcess> {
+async function startProcess(state: UtilityRpcState, cwd: string): Promise<RpcProcess> {
   const proc = new RpcProcess({
-    cwd: homedir(),
+    cwd,
     extraArgs: UTILITY_EXTRA_ARGS,
     onExit: () => {
       if (state.proc === proc) state.proc = null;
@@ -135,12 +155,14 @@ async function startProcess(state: UtilityRpcState): Promise<RpcProcess> {
 }
 
 /** Run one RPC command on the shared utility process (lazy start, serialized,
- * idle-killed). Rejections from earlier commands never poison the queue. */
+ * idle-killed). Rejections from earlier commands never poison the queue.
+ * `cwd` scopes discovery to a workspace; omitted, the child runs in $HOME. */
 export function runUtilityCommand<T = unknown>(
   command: { type: string; [key: string]: unknown },
   timeoutMs: number = DEFAULT_COMMAND_TIMEOUT_MS,
+  cwd: string = homedir(),
 ): Promise<T> {
-  const state = getState();
+  const state = getState(cwd);
   const run = state.queue.then(async () => {
     if (state.idleTimer) {
       clearTimeout(state.idleTimer);
@@ -148,7 +170,7 @@ export function runUtilityCommand<T = unknown>(
     }
     try {
       if (!state.proc || !state.proc.isAlive) {
-        state.proc = await startProcess(state);
+        state.proc = await startProcess(state, cwd);
       }
       return await state.proc.sendCommand<T>(command, timeoutMs);
     } finally {

package/src/server/lib/omp/session/merge-stored-anchor.test.ts

@@ -0,0 +1,85 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Where an unmatched raw turn lands.
+ *
+ * omp answers a builtin on the command path and writes NO session entry for it,
+ * so `/usage` or `/compact` exists only in the chamber's own copy — no JSONL
+ * user turn relates to it, and it cannot be matched into place. It was
+ * positioned by scanning the stored array forward for the next row the JSONL
+ * carried, which only worked because the overlay also held the mirrored rows —
+ * the very rows `overlayRowsForOmpSession` drops. So this is the regression the
+ * narrowing introduced: those turns fell to the END of the timeline, after
+ * answers that came later. The clock fixes it, and the two tests below are the
+ * behaviour and the equivalence.
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import { mergeOmpAttachments, overlayRowsForOmpSession, type StoredMessage } from '@/server/lib/omp/session/merge-stored';
+
+/** Arbitrary epoch ms, one second per step, so the order is exact. */
+const at = (second: number) => 1_790_000_000_000 + second * 1000;
+
+/** The conversation omp recorded. `/usage` is absent: a builtin writes nothing. */
+function jsonl(): StoredMessage[] {
+  return [
+    { id: 'omp-u1', role: 'user', content: 'first question', startedAt: at(0) },
+    { id: 'omp-a1', role: 'ai', content: 'first answer', startedAt: at(1) },
+    { id: 'omp-u2', role: 'user', content: 'second question', startedAt: at(30) },
+    { id: 'omp-a2', role: 'ai', content: 'second answer', startedAt: at(31) },
+  ];
+}
+
+/** The chamber's copy of the same timeline, built in the order it was lived:
+ *  mirrors and local rows interleaved by time. */
+function storedFull(): StoredMessage[] {
+  return [
+    { id: 'msg-1-user', role: 'user', content: 'first question', startedAt: at(0) },
+    { id: 'omp-a1', role: 'ai', content: 'first answer', startedAt: at(1) },
+    { id: 'msg-2-user', role: 'user', content: '/usage', startedAt: at(2) },
+    { id: 'cmdout-1', role: 'ai', content: '', notice: '/usage output', startedAt: at(3) },
+    { id: 'msg-3-user', role: 'user', content: 'second question', startedAt: at(30) },
+    { id: 'omp-a2', role: 'ai', content: 'second answer', startedAt: at(31) },
+  ];
+}
+
+const order = (messages: StoredMessage[]) => messages.map((m) => m.notice ?? m.content);
+
+describe('unmatched raw turn placement', () => {
+  test('lands where the user sent it, not after the turns that followed', () => {
+    const merged = mergeOmpAttachments(jsonl(), JSON.stringify(overlayRowsForOmpSession(storedFull())));
+
+    expect(order(merged)).toEqual([
+      'first question',
+      'first answer',
+      '/usage',
+      '/usage output',
+      'second question',
+      'second answer',
+    ]);
+  });
+
+  test('narrowing the overlay does not move it', () => {
+    const full = mergeOmpAttachments(jsonl(), JSON.stringify(storedFull()));
+    const narrowed = mergeOmpAttachments(
+      jsonl(),
+      JSON.stringify(overlayRowsForOmpSession(storedFull())),
+    );
+
+    expect(narrowed).toEqual(full);
+  });
+
+  test('a turn with no clock to read still renders rather than being dropped', () => {
+    const clockless: StoredMessage[] = [
+      { id: 'msg-1-user', role: 'user', content: 'first question', startedAt: at(0) },
+      { id: 'msg-2-user', role: 'user', content: '/usage' },
+    ];
+
+    const merged = mergeOmpAttachments(jsonl(), JSON.stringify(clockless));
+
+    expect(order(merged)).toContain('/usage');
+    expect(merged.some((m) => m.startedAt === at(0))).toBe(true);
+  });
+});