ompchamber 3.4.0 → 3.6.0

package/src/server/lib/db/compact-chat-overlay.ts

@@ -0,0 +1,90 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Boot-time repair of the `chat_sessions` overlay.
+ *
+ * The overlay used to be a full mirror of every conversation: the chat timeline
+ * posted its whole rendered message list on every `message_end`, so each stored
+ * row carried a copy of the transcript omp already owns in the session JSONL.
+ * `overlayRowsForOmpSession` narrows what is written from now on, and this pass
+ * applies the same rule to rows written before it existed — measured on the
+ * author's install, 165.6 MB of 167.9 MB of mirrored rows were assistant
+ * messages no reader ever touches.
+ *
+ * It has NO marker, deliberately, and that is the difference from the
+ * `queue_fk_removed` migration: the guard here is per-row ("does the filter
+ * actually shrink this row?"), which makes the pass self-limiting rather than
+ * once-only. A marker would be set after the first clean pass and then leave
+ * every row written by an older build uncompacted for good — a live server has
+ * to be restarted for the narrowed writer to take effect, and it keeps writing
+ * mirrors until it is.
+ *
+ * Two properties keep it safe on an existing database:
+ *
+ * - It only rewrites a row whose session file EXISTS. For a chamber-created
+ *   session the DB is the only copy, so those rows are left exactly as they are.
+ * - It only rewrites a row it actually shrinks, so the cost is proportional to
+ *   what is left to fix: 762 ms for a 173 MB overlay on first run, and one
+ *   parse-and-skip of the remaining ~5 MB on every later start.
+ *
+ * A failure is logged rather than thrown: it must never be able to stop the
+ * server from starting. It is called from the server bootstrap right after the
+ * "listening" banner and deliberately NOT from `getDb()` — the test suite and
+ * the CLI reach that in real mode, so a database HANDLE would be able to launch
+ * the rewrite (verified the hard way: a `bun test` run compacted a live
+ * database).
+ */
+
+import type { DbClient } from '@/server/lib/db/client';
+import { findSessionFileById } from '@/server/lib/omp/session/locator';
+import { overlayRowsForOmpSession } from '@/server/lib/omp/session/merge-stored';
+
+/**
+ * Rewrite every over-full `chat_sessions` row whose transcript omp owns.
+ *
+ * `sessionsRoot` is the locator's own seam, forwarded so a test can point the
+ * file lookup at its own tree instead of the real agent directory.
+ */
+export async function compactChatOverlayRows(db: DbClient, sessionsRoot?: string): Promise<void> {
+  try {
+    const rows = (await db.all('SELECT session_id, messages FROM chat_sessions')) as {
+      session_id: string;
+      messages: string;
+    }[];
+
+    let compacted = 0;
+    let reclaimed = 0;
+    for (const row of rows) {
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(row.messages);
+      } catch {
+        // Unparseable is not ours to fix: the readers already treat it as empty.
+        continue;
+      }
+      if (!Array.isArray(parsed) || parsed.length === 0) continue;
+
+      const reduced = overlayRowsForOmpSession(parsed);
+      // The filter only ever removes, so an unchanged length means nothing to do
+      // — and the file lookup below is the expensive half, so it comes second.
+      if (reduced.length === parsed.length) continue;
+      if (!(await findSessionFileById(row.session_id, sessionsRoot))) continue;
+
+      const next = JSON.stringify(reduced);
+      await db.run('UPDATE chat_sessions SET messages = ? WHERE session_id = ?', [next, row.session_id]);
+      compacted += 1;
+      reclaimed += row.messages.length - next.length;
+    }
+
+    if (compacted > 0) {
+      console.log(
+        `[chat-overlay] compacted ${compacted} mirrored session row(s), reclaimed ${(reclaimed / 1e6).toFixed(1)} MB`,
+      );
+    }
+  } catch (error) {
+    console.warn('[chat-overlay] compaction failed; will retry on next start:', error);
+  }
+}

package/src/server/lib/fs/path-segment.test.ts

@@ -0,0 +1,100 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The session-delete blast radius.
+ *
+ * `DELETE /api/sessions/:sessionId` removes a directory under the sessions root
+ * and another under the btw root, both by joining the id onto the root. The
+ * case that shipped broken was `.`: `join(root, '.')` is `root` itself, so the
+ * btw purge's unconditional workspace removal deleted EVERY session's side
+ * questions and the route still answered 404 — an invisible, root-wide wipe
+ * from a request that looked like a miss.
+ *
+ * These tests pin the two properties that made it possible: the guard rejects
+ * every value that is not one segment, and the btw purge refuses a non-segment
+ * even when called directly (the route is not the only entry point).
+ */
+
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import fs from 'fs';
+import path from 'path';
+import { isSinglePathSegment } from '@/server/lib/fs/path-segment';
+import { purgeBtwForSession } from '@/server/lib/btw/purge.server';
+
+describe('isSinglePathSegment', () => {
+  test('accepts the id shapes the app actually produces', () => {
+    // omp session ids are UUIDs; mock ids are integers; pending chats are `new-…`.
+    expect(isSinglePathSegment('11111111-2222-3333-4444-555555555555')).toBe(true);
+    expect(isSinglePathSegment('3')).toBe(true);
+    expect(isSinglePathSegment('new-1758800000000')).toBe(true);
+    // A dot INSIDE a name is fine — only a name that resolves to a directory is not.
+    expect(isSinglePathSegment('session.v2')).toBe(true);
+  });
+
+  test('refuses the values that resolve somewhere other than one child', () => {
+    // The shipped bug: join(root, '.') === root.
+    expect(isSinglePathSegment('.')).toBe(false);
+    expect(isSinglePathSegment('..')).toBe(false);
+    expect(isSinglePathSegment('a/b')).toBe(false);
+    expect(isSinglePathSegment('..\\a')).toBe(false);
+    expect(isSinglePathSegment('')).toBe(false);
+    // A NUL byte truncates at the syscall boundary.
+    expect(isSinglePathSegment('a\0b')).toBe(false);
+  });
+
+  test('the guard agrees with the join it is guarding', () => {
+    // The property that matters: whenever the guard says yes, joining onto a
+    // root stays directly inside it. Asserted against `path.join` itself rather
+    // than a restatement of the rule.
+    const root = '/tmp/root';
+    for (const id of ['11111111-2222-3333-4444-555555555555', '3', 'new-1', 'session.v2']) {
+      expect(isSinglePathSegment(id)).toBe(true);
+      expect(path.join(root, id).startsWith(`${root}${path.sep}`)).toBe(true);
+      expect(path.dirname(path.join(root, id))).toBe(root);
+    }
+    for (const id of ['.', '..', 'a/b', '../x']) {
+      expect(isSinglePathSegment(id)).toBe(false);
+    }
+  });
+});
+
+describe('purgeBtwForSession refuses a non-segment id', () => {
+  const root = '/tmp/omc-path-segment-test';
+  const btwRoot = path.join(root, 'btw');
+  const seeded = [
+    path.join(btwRoot, 'sessA', 'topicA', 'session.jsonl'),
+    path.join(btwRoot, 'sessB', 'topicB', 'session.jsonl'),
+  ];
+
+  beforeAll(async () => {
+    await fs.promises.rm(root, { recursive: true, force: true });
+    // Two unrelated sessions' side questions, exactly as the bug destroyed them.
+    // The btw root is derived from the database path, so pointing that at this
+    // tree is what puts them where the purge would look.
+    for (const file of seeded) {
+      await fs.promises.mkdir(path.dirname(file), { recursive: true });
+      await Bun.write(file, '{"type":"session"}\n');
+    }
+    Bun.env.OMPCHAMBER_DB_PATH = path.join(root, 'db.sqlite');
+  });
+
+  afterAll(async () => {
+    delete Bun.env.OMPCHAMBER_DB_PATH;
+    await fs.promises.rm(root, { recursive: true, force: true });
+  });
+
+  test('`.` does not remove the btw root', async () => {
+    // The guard returns before `listBtwTopics`, so no database is touched.
+    expect(await purgeBtwForSession('.')).toBe(0);
+    // Both sessions' transcripts must survive — this is the regression.
+    for (const file of seeded) expect(fs.existsSync(file)).toBe(true);
+  });
+
+  test('a separator does not reach outside the root', async () => {
+    expect(await purgeBtwForSession('../btw')).toBe(0);
+    for (const file of seeded) expect(fs.existsSync(file)).toBe(true);
+  });
+});

package/src/server/lib/fs/path-segment.ts

@@ -0,0 +1,45 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * One rule, two callers: does this id name exactly one child of a root?
+ *
+ * The purge paths join a session id onto a root to find the directory it owns —
+ * `join(sessionsRoot, …)`, `join(btwRoot, sessionId)` — and then remove it
+ * recursively. `path.join` NORMALIZES, so a value that is not a plain segment
+ * silently retargets the removal:
+ *
+ *   join(root, '.')  === root          → deletes every child of the root
+ *   join(root, '..') === dirname(root) → deletes outside the root
+ *   join(root, 'a/b')                  → reaches into a sibling subtree
+ *
+ * Measured: `DELETE /api/sessions/.` (curl needs `--path-as-is`; it strips the
+ * trailing dot itself) passed a `/^[A-Za-z0-9._-]+$/` guard, normalized to the
+ * btw root, and removed two unrelated sessions' side-question transcripts.
+ *
+ * The check is deliberately structural rather than an enumeration of dangerous
+ * spellings: an id is safe exactly when it is one non-dot segment. Real ids
+ * satisfy that by construction — omp session ids are UUIDs and mock ids are
+ * integers — so nothing legitimate is refused.
+ *
+ * `normalize` is compared, not just scanned for separators, because it is the
+ * same operation the callers' `join` performs: asserting the two agree is what
+ * makes this a proof about the path that will actually be built, rather than a
+ * guess about which inputs look suspicious.
+ */
+
+import { normalize } from 'node:path';
+
+/** True when `id` names one child of a root, and nothing else. */
+export function isSinglePathSegment(id: string): boolean {
+  if (id.length === 0) return false;
+  if (id === '.' || id === '..') return false;
+  if (id.includes('/') || id.includes('\\')) return false;
+  // A NUL byte would truncate the path at the syscall boundary.
+  if (id.includes('\0')) return false;
+  // The load-bearing assertion: normalization must be a no-op, so `join(root, id)`
+  // cannot resolve anywhere but directly under `root`.
+  return normalize(id) === id;
+}

package/src/server/lib/lifecycle/fd-pressure.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, test } from 'bun:test';
+import fs from 'node:fs';
+import { SPAWN_CLIFF, countOpenFileDescriptors, describeSpawnFailure } from '@/server/lib/lifecycle/fd-pressure';
+
+describe('countOpenFileDescriptors', () => {
+  test('sweeps this process own descriptors on a POSIX host', () => {
+    const pressure = countOpenFileDescriptors();
+    if (process.platform === 'win32') {
+      expect(pressure).toBeNull();
+      return;
+    }
+    expect(pressure).not.toBeNull();
+    // Stdio is always open, and the sweep never walks past Darwin's OPEN_MAX —
+    // a descriptor above it cannot be opened, which is the whole point.
+    expect(pressure?.open).toBeGreaterThanOrEqual(3);
+    expect(pressure?.highest).toBeGreaterThanOrEqual(2);
+    expect(pressure?.limit).toBeLessThanOrEqual(SPAWN_CLIFF);
+    expect(pressure?.nearCliff).toBe(false);
+  });
+
+  test('counts descriptors opened and closed around it', () => {
+    const before = countOpenFileDescriptors();
+    if (!before) return; // Host cannot answer; nothing to assert.
+    const opened = [0, 1, 2, 3, 4].map(() => fs.openSync('/dev/null', 'r'));
+    try {
+      const during = countOpenFileDescriptors();
+      expect(during!.open - before.open).toBeGreaterThanOrEqual(opened.length);
+      expect(during!.highest).toBeGreaterThanOrEqual(Math.max(...opened));
+    } finally {
+      for (const fd of opened) fs.closeSync(fd);
+    }
+  });
+});
+
+describe('describeSpawnFailure', () => {
+  test('passes an unrelated failure through untouched', () => {
+    // The helper must not relabel a genuine bad-descriptor or ENOENT bug as
+    // resource pressure; only an observable full table earns the extra text.
+    expect(describeSpawnFailure(new Error('spawn ENOENT'))).toBe('spawn ENOENT');
+    expect(describeSpawnFailure('boom')).toBe('boom');
+  });
+
+  test('names exhaustion only when the table really is full', () => {
+    const opened: number[] = [];
+    try {
+      while (opened.length < SPAWN_CLIFF + 16) {
+        try {
+          opened.push(fs.openSync('/dev/null', 'r'));
+        } catch {
+          break; // Host limit is lower than the cliff; the gate is untestable here.
+        }
+      }
+      if (!countOpenFileDescriptors()?.nearCliff) return;
+
+      const raw = "EBADF: bad file descriptor, posix_spawn '/bin/sh'";
+      const described = describeSpawnFailure(new Error(raw));
+      expect(described.startsWith(raw)).toBe(true);
+      expect(described).toContain('out of file descriptors');
+      // The symptom gate still holds under pressure: an unrelated failure keeps
+      // its own message instead of being blamed on the descriptor table.
+      expect(describeSpawnFailure(new Error('spawn ENOENT'))).toBe('spawn ENOENT');
+    } finally {
+      for (const fd of opened) fs.closeSync(fd);
+    }
+  });
+});

package/src/server/lib/lifecycle/fd-pressure.ts

@@ -0,0 +1,159 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * File-descriptor pressure, and the honest name for a spawn that dies from it.
+ *
+ * On macOS `posix_spawn` fails with `EBADF: bad file descriptor` the moment it
+ * must hand the child a descriptor numbered at or above `OPEN_MAX` (10240). The
+ * error names the shim it tried to exec — `posix_spawn '/bin/sh'` — and says
+ * nothing about the cause, so a terminal panel reads "Failed to start /bin/zsh:
+ * EBADF: bad file descriptor, posix_spawn '/bin/sh'" while the real condition is
+ * that the whole server process has run out of descriptors. Measured A/B on Bun
+ * 1.4.2 / macOS 26: 10230 open descriptors spawn fine, 10240 fails with exactly
+ * that message.
+ *
+ * A dev server reaches that state on its own, without a leak in this codebase:
+ * `Bun.serve({ development: true })` keeps the client module graph open
+ * (measured: 3545 descriptors for this app, against 17 in production), and a
+ * macOS reload never closes the previous generation's (bun#40706, bun#40907 —
+ * the pre-exec sweep exists only on Linux). The count therefore grows with
+ * every rebuild, and past the cliff every spawn in the process fails at once:
+ * the PTY shell, the `omp` child, `git`, `rg`.
+ *
+ * `countOpenFileDescriptors()` answers "how close?" with `fcntl(F_GETFD)` over
+ * the descriptor table — the same `bun:ffi` route `flock.ts` takes. The sweep
+ * stops at the cliff, because a descriptor above it cannot be opened anyway and
+ * that bound keeps the probe near 1 ms. It returns null where the symbols are
+ * unavailable (and on Windows), and every caller must read null as "unknown",
+ * never as "fine": `describeSpawnFailure` only names exhaustion when it can see
+ * the pressure, so a genuine bad-descriptor bug still reports itself plainly.
+ */
+
+import { dlopen, FFIType } from 'bun:ffi';
+import type { FFIFunction, Library } from 'bun:ffi';
+
+/**
+ * Darwin's `OPEN_MAX`: the first descriptor number a process cannot hold, and
+ * therefore the point where `posix_spawn` starts answering `EBADF`. Verified on
+ * Bun 1.4.2 (10230 ok, 10240 fails).
+ */
+export const SPAWN_CLIFF = 10_240;
+
+/**
+ * Pressure is reported as "near" from 90% of the swept range. The remaining
+ * 1024 descriptors are what a burst of spawns needs (an omp child takes
+ * several), and the failure arrives without a warning of its own: once the
+ * table is full there is room for neither a retry nor a log line.
+ */
+const NEAR_CLIFF_RATIO = 0.9;
+
+const FD_SYMBOLS = {
+  fcntl: { args: [FFIType.i32, FFIType.i32, FFIType.i32], returns: FFIType.i32 },
+  getdtablesize: { args: [], returns: FFIType.i32 },
+} satisfies Record<string, FFIFunction>;
+
+/** Library names to try, in the order each platform resolves them. */
+const LIBC_NAMES = ['libc.dylib', 'libSystem.B.dylib', 'libc.so.6'] as const;
+
+/** `F_GETFD` — the cheapest question that distinguishes open from closed. */
+const F_GETFD = 1;
+
+declare global {
+  // eslint-disable-next-line no-var
+  var __ompChamberFdLib: Library<typeof FD_SYMBOLS> | null | undefined;
+}
+
+/** libc with `fcntl`/`getdtablesize`, or null where this host has neither. */
+function libc(): Library<typeof FD_SYMBOLS> | null {
+  if (globalThis.__ompChamberFdLib !== undefined) return globalThis.__ompChamberFdLib;
+  globalThis.__ompChamberFdLib = null;
+  if (process.platform === 'win32') return null;
+  for (const name of LIBC_NAMES) {
+    try {
+      globalThis.__ompChamberFdLib = dlopen(name, FD_SYMBOLS);
+      return globalThis.__ompChamberFdLib;
+    } catch {
+      // Try the next name; a host with none of them keeps the null answer.
+    }
+  }
+  return null;
+}
+
+export interface FdPressure {
+  /** Descriptors open below `limit`. */
+  open: number;
+  /** Highest descriptor number seen, or -1 when the table looked empty. */
+  highest: number;
+  /** Where the sweep stopped: `getdtablesize()`, capped at the cliff. */
+  limit: number;
+  /** Whether the next spawn is at risk. See `NEAR_CLIFF_RATIO`. */
+  nearCliff: boolean;
+}
+
+/**
+ * Sweep the descriptor table, or null when this host cannot answer.
+ *
+ * Descriptors are allocated lowest-first, so the number of open descriptors and
+ * the highest one agree on a saturated table — which is the only state that
+ * matters here, and the state a dev server reaches by degrees.
+ *
+ * Never throws: `GET /api/health` is the CLI's readiness probe and the client's
+ * liveness check, so a host where the symbol resolves but the call does not
+ * must degrade to "unknown" rather than take those down. `open` saturates at
+ * `limit`, since the sweep stops there by design.
+ */
+export function countOpenFileDescriptors(): FdPressure | null {
+  const symbols = libc();
+  if (!symbols) return null;
+
+  try {
+    const reported = symbols.symbols.getdtablesize();
+    const table = Number.isFinite(reported) && reported > 0 ? reported : SPAWN_CLIFF;
+    const limit = Math.min(table, SPAWN_CLIFF);
+
+    let open = 0;
+    let highest = -1;
+    for (let fd = 0; fd < limit; fd++) {
+      if (symbols.symbols.fcntl(fd, F_GETFD, 0) !== -1) {
+        open += 1;
+        highest = fd;
+      }
+    }
+    return { open, highest, limit, nearCliff: highest >= limit * NEAR_CLIFF_RATIO };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * What descriptor exhaustion looks like in Bun's own words. macOS names the
+ * failing syscall (`EBADF … posix_spawn '/bin/sh'`), Linux the errno
+ * (`EMFILE: too many open files, socketpair`) — measured on both.
+ */
+const EXHAUSTION_SYMPTOM = /\bEBADF\b|\bEMFILE\b|too many open files/i;
+
+/**
+ * The message to surface for a failed spawn: Bun's own, plus what it takes to
+ * act on it when the cause is descriptor exhaustion.
+ *
+ * Two conditions, both required. The message must carry the symptom, and the
+ * sweep must see real pressure — a truncated table is not the only way `EBADF`
+ * reaches here, and appending "out of descriptors" to a genuine bad-descriptor
+ * bug (or to an unrelated `ENOENT` that failed while the table happened to be
+ * full) sends the next reader down the wrong path.
+ */
+export function describeSpawnFailure(error: unknown): string {
+  const raw = error instanceof Error ? error.message : String(error);
+  if (!EXHAUSTION_SYMPTOM.test(raw)) return raw;
+  const pressure = countOpenFileDescriptors();
+  if (!pressure || !pressure.nearCliff) return raw;
+  return (
+    `${raw} — the chamber server is out of file descriptors ` +
+    `(${pressure.open} of ${pressure.limit} open, highest #${pressure.highest}); restart the instance. ` +
+    `A dev server holds the whole client module graph open and a macOS reload never releases ` +
+    `the previous generation (bun#40706), so the count only climbs.`
+  );
+}

package/src/server/lib/omp/config/commands.test.ts

@@ -0,0 +1,167 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Command-file location and authoring.
+ *
+ * `get_available_commands` reports a command's name, description and hint but
+ * never the file behind it, so the pane's read-only/editable decision and the
+ * delete's safety both rest on this lookup. The rules worth locking are the
+ * ones a user cannot see: which root a duplicate name resolves to (omp runs the
+ * PROJECT file), which roots the chamber may write to (only the two
+ * `omp`-native ones), and the `.prompt.md` suffix VS Code prompt files carry.
+ *
+ * Everything runs inside a temp workspace and a temp `$HOME`, so the real
+ * `~/.omp/agent/commands` is never read or written.
+ */
+
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import fs from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+
+import {
+  deleteCommandFile,
+  locateCommandFile,
+  readCommandFile,
+  writeCommandFile,
+} from '@/server/lib/omp/config/commands';
+
+let projectDir = '';
+let homeDir = '';
+let realHome: string | undefined;
+
+const write = (filePath: string, body = 'body') => {
+  fs.mkdirSync(join(filePath, '..'), { recursive: true });
+  fs.writeFileSync(filePath, body);
+};
+
+beforeAll(() => {
+  projectDir = fs.mkdtempSync(join(tmpdir(), 'ompchamber-cmd-project-'));
+  homeDir = fs.mkdtempSync(join(tmpdir(), 'ompchamber-cmd-home-'));
+  realHome = Bun.env.HOME;
+  // `userCommandDirs()` reads `$HOME` for the `.claude`/`.codex`/`.agents`/
+  // `.config/opencode` roots, so redirecting it keeps the test off the real one.
+  Bun.env.HOME = homeDir;
+});
+
+afterAll(() => {
+  if (realHome === undefined) delete Bun.env.HOME;
+  else Bun.env.HOME = realHome;
+  fs.rmSync(projectDir, { recursive: true, force: true });
+  fs.rmSync(homeDir, { recursive: true, force: true });
+});
+
+describe('locateCommandFile', () => {
+  test('a workspace .omp/commands file is the managed project root', async () => {
+    write(join(projectDir, '.omp', 'commands', 'proj.md'));
+    expect(await locateCommandFile('proj', projectDir)).toEqual({
+      filePath: join(projectDir, '.omp', 'commands', 'proj.md'),
+      scope: 'project',
+      managed: true,
+    });
+  });
+
+  test("another tool's file is found but never managed", async () => {
+    write(join(projectDir, '.claude', 'commands', 'claude-cmd.md'));
+    expect(await locateCommandFile('claude-cmd', projectDir)).toEqual({
+      filePath: join(projectDir, '.claude', 'commands', 'claude-cmd.md'),
+      scope: 'project',
+      managed: false,
+    });
+  });
+
+  test('a prompt file is found under its .prompt.md suffix', async () => {
+    write(join(projectDir, '.github', 'prompts', 'copilot.prompt.md'));
+    expect((await locateCommandFile('copilot', projectDir))?.filePath)
+      .toBe(join(projectDir, '.github', 'prompts', 'copilot.prompt.md'));
+  });
+
+  test('a duplicate name resolves to the project file', async () => {
+    write(join(homeDir, '.claude', 'commands', 'dupe.md'));
+    write(join(projectDir, '.omp', 'commands', 'dupe.md'));
+    expect((await locateCommandFile('dupe', projectDir))?.filePath)
+      .toBe(join(projectDir, '.omp', 'commands', 'dupe.md'));
+    // With no workspace the same name is the user-level file, which the
+    // chamber does not own.
+    expect(await locateCommandFile('dupe')).toEqual({
+      filePath: join(homeDir, '.claude', 'commands', 'dupe.md'),
+      scope: 'user',
+      managed: false,
+    });
+  });
+
+  test('a name that is not a plain file name is refused', async () => {
+    expect(await locateCommandFile('../escape', projectDir)).toBeNull();
+    expect(await locateCommandFile('nested/name', projectDir)).toBeNull();
+    expect(await locateCommandFile('   ', projectDir)).toBeNull();
+  });
+
+  test('a builtin has no file at all', async () => {
+    expect(await locateCommandFile('model', projectDir)).toBeNull();
+  });
+});
+
+describe('writeCommandFile / deleteCommandFile', () => {
+  test('round-trips a project command through the file', async () => {
+    const { filePath } = await writeCommandFile({
+      scope: 'project',
+      projectDir,
+      name: 'round',
+      description: 'round trip',
+      argumentHint: '[a|b]',
+      body: 'do $ARGUMENTS',
+    });
+    expect(filePath).toBe(join(projectDir, '.omp', 'commands', 'round.md'));
+    // The parsed body carries the trailing newline the serializer emits, and
+    // the leading blank line that separates it from the frontmatter is dropped.
+    expect(await readCommandFile(filePath)).toEqual({
+      description: 'round trip',
+      argumentHint: '[a|b]',
+      body: 'do $ARGUMENTS\n',
+    });
+    // Saving what was read must not grow the file: the pane posts exactly this.
+    const first = fs.readFileSync(filePath, 'utf8');
+    const parsed = await readCommandFile(filePath);
+    await writeCommandFile({
+      scope: 'project',
+      projectDir,
+      name: 'round',
+      description: parsed!.description,
+      argumentHint: parsed!.argumentHint,
+      body: parsed!.body,
+    });
+    expect(fs.readFileSync(filePath, 'utf8')).toBe(first);
+    expect(await deleteCommandFile('round', projectDir)).toBe(true);
+    expect(await locateCommandFile('round', projectDir)).toBeNull();
+  });
+
+  test('a rename moves the file instead of leaving two', async () => {
+    await writeCommandFile({ scope: 'project', projectDir, name: 'before', description: 'd', argumentHint: '', body: 'b' });
+    await writeCommandFile({
+      scope: 'project',
+      projectDir,
+      previousName: 'before',
+      name: 'after',
+      description: 'd',
+      argumentHint: '',
+      body: 'b',
+    });
+    expect(await locateCommandFile('before', projectDir)).toBeNull();
+    expect(await locateCommandFile('after', projectDir)).not.toBeNull();
+    await deleteCommandFile('after', projectDir);
+  });
+
+  test('a project write with no workspace is refused', async () => {
+    expect(writeCommandFile({ scope: 'project', name: 'lost', description: 'd', argumentHint: '', body: 'b' }))
+      .rejects.toThrow('workspace root is required');
+  });
+
+  test("a delete cannot reach a file another tool installed", async () => {
+    write(join(projectDir, '.claude', 'commands', 'notours.md'));
+    expect(deleteCommandFile('notours', projectDir)).rejects.toThrow('cannot delete');
+    expect(fs.existsSync(join(projectDir, '.claude', 'commands', 'notours.md'))).toBe(true);
+  });
+});