@kabmo-labs/kabmo 0.0.0-stage → 0.0.1

package/src/server/lib/omp/config/discovery-roots.ts

@@ -0,0 +1,194 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The directories omp discovers skills and commands from.
+ *
+ * ONE table, because two consumers need the same answer and must not drift:
+ * `locateCommandFile` (which file backs a command name) and the discovery
+ * watcher (which directories to watch for a change). They were written
+ * separately, and the watcher's copy was short by every root but the omp-native
+ * pair — so a skill added to `.claude/skills`, `.codex/skills`, `.opencode`,
+ * `.agents` or `.github` in a live session was never noticed.
+ *
+ * The set below is measured, not assumed (omp 18.4.3, a fresh directory with a
+ * `SKILL.md` planted in each candidate and `omp skill list <dir> --json`):
+ *
+ *   project  .omp/skills     → native:project      ← Kabmo may write here
+ *            .claude/skills  → claude:project
+ *            .codex/skills   → codex:project
+ *            .agents/skills  → agents:project
+ *            .opencode/skills→ opencode:project
+ *            .github/skills  → github:project
+ *
+ *   user     ~/.omp/agent/skills → native:user      ← Kabmo may write here
+ *            ~/.agents/skills     → agents:user
+ *
+ * Everything else was verified NOT read at this level: `~/.claude/skills`,
+ * `~/.codex/skills`, `~/.config/opencode/skills` and `~/.opencode/skills` are
+ * all ignored by a child started in an unrelated cwd, even though omp does read
+ * `~/.claude/commands` and friends for COMMANDS. Do not add a root here on the
+ * strength of its command counterpart.
+ *
+ * Commands and skills share the project roots and the omp-native user root; the
+ * registry-backed `~/.agents/skills` is skills-only. `.github` is skills-only
+ * too — its command form is `.github/prompts/*.prompt.md`, a different layout
+ * that `commands.ts` keeps its own entry for.
+ *
+ * A `managed` root is one Kabmo may write to and delete from; every other
+ * root is read-only here, because Kabmo is not the tool that put the file
+ * there.
+ */
+
+import { existsSync } from 'fs';
+import { dirname, join, resolve } from 'path';
+import { homedir } from 'os';
+import { getAgentDir } from '@/server/lib/omp/core/paths';
+
+/** How far up from a cwd the ancestor scan looks. omp's own walk stops at the
+ *  enclosing git repo (or the filesystem root), which is what bounds this in
+ *  practice; the cap only stops a pathological path from producing hundreds of
+ *  entries. */
+const MAX_WALK_UP_DEPTH = 24;
+
+/** A root, relative to a workspace for `project` scope, absolute for `user`. */
+export interface DiscoveryRoot {
+  /** Directory holding the skill/command entries. */
+  dir: string;
+  scope: 'user' | 'project';
+  /** The Kabmo owns files here and may write or delete them. */
+  managed: boolean;
+}
+
+/** Project-scope roots shared by skills and commands, relative to a workspace. */
+const PROJECT_ROOTS: Array<{ dir: string; managed: boolean }> = [
+  { dir: '.omp/skills', managed: true },
+  { dir: '.claude/skills', managed: false },
+  { dir: '.codex/skills', managed: false },
+  { dir: '.agents/skills', managed: false },
+  { dir: '.opencode/skills', managed: false },
+  { dir: '.github/skills', managed: false },
+];
+
+/** Project-scope COMMAND roots. `.github` differs from its skill counterpart:
+ *  VS Code Copilot prompt files live in `.github/prompts` and carry a
+ *  `.prompt.md` suffix, which is why the suffix rides along here. */
+export const PROJECT_COMMAND_ROOTS: Array<{ dir: string; suffix: string; managed: boolean }> = [
+  { dir: '.omp/commands', suffix: '.md', managed: true },
+  { dir: '.claude/commands', suffix: '.md', managed: false },
+  { dir: '.codex/commands', suffix: '.md', managed: false },
+  { dir: '.agents/commands', suffix: '.md', managed: false },
+  { dir: '.opencode/commands', suffix: '.md', managed: false },
+  { dir: '.github/prompts', suffix: '.prompt.md', managed: false },
+];
+
+/** User-scope roots shared by skills and commands. `.omp/agent` comes from the
+ *  agent-dir resolution so `PI_CODING_AGENT_DIR` and profiles are honored. */
+function userSharedRoots(): Array<{ dir: string; managed: boolean }> {
+  return [
+    { dir: join(getAgentDir(), 'skills'), managed: true },
+    { dir: join(getAgentDir(), 'commands'), managed: true },
+  ];
+}
+
+/**
+ * The home directory, with `$HOME` as an OVERRIDE and the OS as the fallback.
+ *
+ * The fallback is the fix, and the override is why it is a fallback rather than
+ * a replacement. `Bun.env.HOME` is EMPTY on Windows (the variable there is
+ * `USERPROFILE`), so `join('', '.agents', 'skills')` produced the RELATIVE path
+ * `.agents\skills` — a root resolved against whatever cwd the server happened to
+ * have, which on a Windows runner is the checkout. Measured on the first Windows
+ * run: the skill and command roots listed `.agents\skills` where they should
+ * have listed `C:\Users\runneradmin\.agents\skills`. `os.homedir()` falls
+ * back to `USERPROFILE` there and to `getpwuid()` on POSIX, which is why
+ * `omp/core/paths.ts` already uses it for every other derived directory.
+ *
+ * `$HOME` still wins when it is set, because the suite points it at a temp
+ * directory to keep the real `~/.claude` and `~/.agents` out of a test — and
+ * `homedir()` reads the OS, not the environment, so it would ignore that.
+ */
+function homeDir(): string {
+  return Bun.env.HOME || homedir();
+}
+
+/** User-scope roots only skills use. */
+function userSkillOnlyRoots(): string[] {
+  return [join(homeDir(), '.agents', 'skills')];
+}
+
+/** User-scope roots only commands use. */
+function userCommandOnlyRoots(): Array<{ dir: string; suffix: string }> {
+  const home = homeDir();
+  return [
+    { dir: join(home, '.claude', 'commands'), suffix: '.md' },
+    { dir: join(home, '.codex', 'commands'), suffix: '.md' },
+    { dir: join(home, '.agents', 'commands'), suffix: '.md' },
+    { dir: join(home, '.config', 'opencode', 'commands'), suffix: '.md' },
+  ];
+}
+
+/** Every SKILL directory omp reads, for one workspace (or user scope alone). */
+export function skillRoots(projectDir?: string | null): DiscoveryRoot[] {
+  const roots: DiscoveryRoot[] = [];
+  if (projectDir) {
+    for (const entry of PROJECT_ROOTS) {
+      roots.push({ dir: join(projectDir, entry.dir), scope: 'project', managed: entry.managed });
+    }
+    roots.push(...walkUpSkillRoots(projectDir));
+  }
+  for (const entry of userSharedRoots()) {
+    // A shared root is a skills root only for its `skills` half.
+    if (entry.dir.endsWith('skills')) roots.push({ dir: entry.dir, scope: 'user', managed: entry.managed });
+  }
+  for (const dir of userSkillOnlyRoots()) roots.push({ dir, scope: 'user', managed: false });
+  return roots;
+}
+
+/**
+ * `<ancestor>/.omp/skills` for every ancestor of `dir` up to the enclosing git
+ * repository, or to the filesystem root when there is none.
+ *
+ * omp does NOT read project skills from the cwd alone — it walks UP from it,
+ * and a `.git` entry is what stops the walk (verified on 18.4.3: from
+ * `/tmp/walk/a/b/c` with no git anywhere, `omp skill list` reported the skills
+ * of all four levels; adding an empty `.git` at `a/b` cut it to that level and
+ * below). $HOME is NOT a boundary — the walk crossed it — and a `.git` FILE
+ * (a worktree or submodule) stops it just like a directory.
+ *
+ * These roots are `managed: false`: omp reads them, but Kabmo's write and
+ * delete paths are scoped to the cwd's own `.omp/skills`, and widening them
+ * would let a save in one project rewrite another's files.
+ */
+function walkUpSkillRoots(dir: string): DiscoveryRoot[] {
+  const roots: DiscoveryRoot[] = [];
+  let current = resolve(dir);
+  for (let depth = 0; depth < MAX_WALK_UP_DEPTH; depth += 1) {
+    const parent = dirname(current);
+    if (parent === current) break; // filesystem root
+    // A `.git` entry ends the walk: omp treats it as the repository boundary.
+    if (existsSync(join(current, '.git'))) break;
+    current = parent;
+    roots.push({ dir: join(current, '.omp', 'skills'), scope: 'project', managed: false });
+  }
+  return roots;
+}
+
+/** Every COMMAND directory omp reads, for one workspace (or user scope alone). */
+export function commandRoots(projectDir?: string | null): Array<DiscoveryRoot & { suffix: string }> {
+  const roots: Array<DiscoveryRoot & { suffix: string }> = [];
+  if (projectDir) {
+    for (const entry of PROJECT_COMMAND_ROOTS) {
+      roots.push({ dir: join(projectDir, entry.dir), suffix: entry.suffix, scope: 'project', managed: entry.managed });
+    }
+  }
+  for (const entry of userSharedRoots()) {
+    if (entry.dir.endsWith('commands')) roots.push({ dir: entry.dir, suffix: '.md', scope: 'user', managed: entry.managed });
+  }
+  for (const entry of userCommandOnlyRoots()) {
+    roots.push({ ...entry, scope: 'user', managed: false });
+  }
+  return roots;
+}

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

@@ -0,0 +1,349 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The comment-preserving YAML config writer and the two settings it edits.
+ *
+ * These modules are the only place Kabmo writes into omp's own config
+ * files, so each promise here is a data-loss promise:
+ *
+ * - `withOmpYamlDocument` must refuse a file that is not a YAML mapping (the
+ *   alternative is overwriting a user's hand-authored file with a scalar), must
+ *   leave the file byte-identical when an edit reports `changed: false`, and
+ *   must create a new config `0600` because these files hold plaintext keys.
+ * - `plainOf` must return PLAIN values: a node would make `Array.isArray` false
+ *   and a membership check silently see an empty list.
+ * - `disabledProviders` is path-scoped — re-enabling one provider must not
+ *   delete a `{ path, providers }` entry, and disabling must not flatten the
+ *   list to bare strings.
+ * - A model override is only accepted for a model the provider registers, and
+ *   a cleared override is deleted rather than written as `null`.
+ *
+ * `PI_CODING_AGENT_DIR` is redirected to a temp dir, so the real
+ * `~/.omp/agent` config is never read or written.
+ */
+
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import fs from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { isSeq, parseDocument } from 'yaml';
+import { testPosix } from '@/test-support/platform';
+
+import {
+  OmpConfigError,
+  plainOf,
+  seqAt,
+  valueAt,
+  withOmpYamlDocument,
+} from '@/server/lib/omp/config/document';
+import {
+  disableNativeProvider,
+  enableNativeProvider,
+  readDisabledProviderEntries,
+  readDisabledProviders,
+} from '@/server/lib/omp/config/disabled-providers';
+import { writeModelOverride } from '@/server/lib/omp/config/model-overrides';
+import { SCHEMA_EXTRAS } from '@/shared/lib/omp/config/schema-extras';
+import { OMP_SCHEMA } from '@/shared/lib/omp/config/schema';
+
+let root = '';
+let agentDir = '';
+let prevAgentDir: string | undefined;
+
+const configPath = () => join(agentDir, 'config.yml');
+const modelsPath = () => join(agentDir, 'models.yml');
+
+function write(file: string, content: string, mode?: number): string {
+  fs.mkdirSync(join(file, '..'), { recursive: true });
+  fs.writeFileSync(file, content);
+  if (mode !== undefined) fs.chmodSync(file, mode);
+  return file;
+}
+
+const read = (file: string) => fs.readFileSync(file, 'utf8');
+
+beforeAll(() => {
+  root = fs.mkdtempSync(join(tmpdir(), 'kabmo-document-'));
+  agentDir = join(root, 'agent');
+  fs.mkdirSync(agentDir, { recursive: true });
+  prevAgentDir = Bun.env.PI_CODING_AGENT_DIR;
+  Bun.env.PI_CODING_AGENT_DIR = agentDir;
+});
+
+afterAll(() => {
+  if (prevAgentDir === undefined) delete Bun.env.PI_CODING_AGENT_DIR;
+  else Bun.env.PI_CODING_AGENT_DIR = prevAgentDir;
+  fs.rmSync(root, { recursive: true, force: true });
+});
+
+describe('document node readers', () => {
+  test('seqAt returns the sequence node only, never a map or scalar', () => {
+    const doc = parseDocument('list:\n  - a\n  - b\nmap:\n  k: v\nscalar: x\n');
+    expect(isSeq(seqAt(doc, ['list']))).toBe(true);
+    expect(seqAt(doc, ['map'])).toBeNull();
+    expect(seqAt(doc, ['scalar'])).toBeNull();
+    expect(seqAt(doc, ['missing'])).toBeNull();
+  });
+
+  test('plainOf and valueAt unwrap nodes to plain values; scalars read through the keep-scalar get', () => {
+    const doc = parseDocument('scalar: 7\nmap:\n  k: v\nseq:\n  - 1\n  - 2\n');
+    expect(plainOf<number>(doc, doc.get('scalar', true))).toBe(7);
+    expect(valueAt<Record<string, string>>(doc, ['map'])).toEqual({ k: 'v' });
+    expect(valueAt<number[]>(doc, ['seq'])).toEqual([1, 2]);
+    expect(plainOf(doc, undefined)).toBeUndefined();
+    expect(plainOf(doc, null)).toBeUndefined();
+  });
+
+  test('valueAt at a path yields a real array, not a YAML node', () => {
+    const doc = parseDocument('a:\n  b:\n    - one\n    - two\n');
+    const list = valueAt<string[]>(doc, ['a', 'b']);
+    expect(Array.isArray(list)).toBe(true);
+    expect(list).toContain('one');
+    expect(valueAt(doc, ['a', 'missing'])).toBeUndefined();
+  });
+
+  test('OmpConfigError carries its own name', () => {
+    expect(new OmpConfigError('boom').name).toBe('OmpConfigError');
+  });
+});
+
+describe('withOmpYamlDocument', () => {
+  test('a missing file is created and the edit result is returned', async () => {
+    const path = join(root, 'created', 'config.yml');
+    const result = await withOmpYamlDocument(path, (doc) => {
+      doc.set('key', 'value');
+      return { result: 'ok', changed: true };
+    });
+    expect(result).toBe('ok');
+    expect(read(path)).toContain('key: value');
+  });
+
+  // `statSync().mode` is a POSIX property (Windows reports a synthesised 0o666),
+  // so the create- and kept-mode assertions are POSIX-only.
+  testPosix('a missing file is created 0600', async () => {
+    const path = join(root, 'created-0600', 'config.yml');
+    await withOmpYamlDocument(path, (doc) => {
+      doc.set('key', 'value');
+      return { result: 'ok', changed: true };
+    });
+    expect(fs.statSync(path).mode & 0o777).toBe(0o600);
+  });
+
+  test('changed:false leaves the file byte-identical and absent if it never existed', async () => {
+    const path = write(join(root, 'noop', 'config.yml'), '# note\nkeep: 1\n');
+    const before = read(path);
+    expect(await withOmpYamlDocument(path, () => ({ result: 1, changed: false }))).toBe(1);
+    expect(read(path)).toBe(before);
+
+    const absent = join(root, 'noop', 'absent.yml');
+    await withOmpYamlDocument(absent, () => ({ result: 0, changed: false }));
+    expect(fs.existsSync(absent)).toBe(false);
+  });
+
+  test('comments and unrelated keys survive an edit', async () => {
+    const path = write(join(root, 'kept', 'config.yml'), '# top comment\nkeep: 1\n', 0o640);
+    await withOmpYamlDocument(path, (doc) => {
+      doc.set('added', true);
+      return { result: null, changed: true };
+    });
+    const after = read(path);
+    expect(after).toContain('# top comment');
+    expect(after).toContain('keep: 1');
+    expect(after).toContain('added: true');
+  });
+
+  testPosix('the file mode is kept across an edit', async () => {
+    const path = write(join(root, 'kept-mode', 'config.yml'), '# top comment\nkeep: 1\n', 0o640);
+    await withOmpYamlDocument(path, (doc) => {
+      doc.set('added', true);
+      return { result: null, changed: true };
+    });
+    expect(fs.statSync(path).mode & 0o777).toBe(0o640);
+  });
+
+  test('invalid YAML and a non-mapping document are refused with OmpConfigError', async () => {
+    const invalid = write(join(root, 'bad', 'invalid.yml'), 'key: [unclosed\n');
+    await expect(withOmpYamlDocument(invalid, () => ({ result: null, changed: true })))
+      .rejects.toThrow(OmpConfigError);
+
+    const scalar = write(join(root, 'bad', 'scalar.yml'), 'just a string\n');
+    await expect(withOmpYamlDocument(scalar, () => ({ result: null, changed: true })))
+      .rejects.toThrow(/must contain a YAML mapping/);
+    expect(read(scalar)).toBe('just a string\n');
+  });
+});
+
+describe('disabledProviders', () => {
+  test('a missing config.yml reads as an empty disabled list', async () => {
+    fs.rmSync(configPath(), { force: true });
+    expect(await readDisabledProviderEntries()).toEqual([]);
+    expect(await readDisabledProviders(agentDir)).toEqual(new Set());
+    expect(await enableNativeProvider('deepseek')).toBe(false);
+  });
+
+  test('bare slugs always apply; a path-scoped entry applies only under its prefix', async () => {
+    write(configPath(), [
+      'disabledProviders:',
+      '  - always',
+      '  - path: ' + join(root, 'work'),
+      '    providers: [work-only]',
+      '  - paths: ["/other"]',
+      '    values: [other-only]',
+      '',
+    ].join('\n'));
+    expect(await readDisabledProviders(join(root, 'work', 'sub'))).toEqual(new Set(['always', 'work-only']));
+    expect(await readDisabledProviders(root)).toEqual(new Set(['always']));
+    expect((await readDisabledProviderEntries()).length).toBe(3);
+  });
+
+  test('disable appends without flattening the list and preserves comments', async () => {
+    write(configPath(), '# keep me\ndisabledProviders:\n  - path: /p\n    providers: [x]\nother: 1\n');
+    expect(await disableNativeProvider('deepseek')).toBe(true);
+    const after = read(configPath());
+    expect(after).toContain('# keep me');
+    expect(after).toContain('other: 1');
+    expect(after).toContain('providers:');
+    expect(await readDisabledProviders(root)).toEqual(new Set(['deepseek']));
+    expect(await disableNativeProvider('deepseek')).toBe(false);
+  });
+
+  test('a slug disabled only through a path-scoped entry cannot be disabled twice', async () => {
+    write(configPath(), 'disabledProviders:\n  - path: /p\n    providers: [x]\n');
+    expect(await disableNativeProvider('x')).toBe(false);
+  });
+
+  test('enable removes a bare slug and reports whether anything changed', async () => {
+    write(configPath(), 'disabledProviders:\n  - a\n  - b\n');
+    expect(await enableNativeProvider('a')).toBe(true);
+    expect(await readDisabledProviderEntries()).toEqual(['b']);
+    expect(await enableNativeProvider('missing')).toBe(false);
+  });
+
+  test('enable edits the path-scoped entry in place, keeping its key and siblings', async () => {
+    write(configPath(), 'disabledProviders:\n  - path: /p\n    providers: [x, y]\n');
+    expect(await enableNativeProvider('x')).toBe(true);
+    const after = read(configPath());
+    expect(after).toContain('providers:');
+    expect(after).toContain('y');
+    expect(after).not.toContain('x,');
+    expect(await readDisabledProviders(join('/p', 'sub'))).toEqual(new Set(['y']));
+  });
+
+  test('enable deletes a path-scoped entry once its last provider is gone', async () => {
+    write(configPath(), 'disabledProviders:\n  - path: /p\n    providers: [only]\n  - keep\n');
+    expect(await enableNativeProvider('only')).toBe(true);
+    expect(await readDisabledProviderEntries()).toEqual(['keep']);
+  });
+});
+
+describe('writeModelOverride', () => {
+  const seedModels = (extra = '') => write(modelsPath(), [
+    'providers:',
+    '  deepseek:',
+    '    models:',
+    '      - id: chat',
+    '      - id: reason',
+    extra,
+    '',
+  ].join('\n'));
+
+  test('an unknown provider/model pair is reported and the file is untouched', async () => {
+    seedModels();
+    const before = read(modelsPath());
+    expect(await writeModelOverride({ provider: 'deepseek', modelId: 'nope', maxTokens: 10 })).toEqual({
+      written: false,
+      unknownTarget: true,
+      reason: 'nope is not registered under provider "deepseek" in models.yml',
+    });
+    expect(read(modelsPath())).toBe(before);
+  });
+
+  test('maxTokens is written, then cleared away with its empty parents', async () => {
+    seedModels();
+    expect(await writeModelOverride({ provider: 'deepseek', modelId: 'chat', maxTokens: 4096 })).toEqual({ written: true });
+    expect(read(modelsPath())).toContain('maxTokens: 4096');
+    expect(await writeModelOverride({ provider: 'deepseek', modelId: 'chat', maxTokens: null })).toEqual({ written: true });
+    expect(read(modelsPath())).not.toContain('maxTokens');
+    expect(read(modelsPath())).not.toContain('modelOverrides');
+  });
+
+  test('a non-positive maxTokens is refused and nothing is written', async () => {
+    seedModels();
+    const before = read(modelsPath());
+    await expect(writeModelOverride({ provider: 'deepseek', modelId: 'chat', maxTokens: 0 }))
+      .rejects.toThrow(/maxTokens must be a positive number/);
+    expect(read(modelsPath())).toBe(before);
+  });
+
+  test('a reasoning effort writes the full vocabulary, and keeps a catalog-provided one', async () => {
+    seedModels();
+    await writeModelOverride({ provider: 'deepseek', modelId: 'reason', reasoningEffort: 'medium' });
+    expect(read(modelsPath())).toContain('defaultLevel: medium');
+    for (const level of ['minimal', 'low', 'medium', 'high', 'xhigh', 'max']) {
+      expect(read(modelsPath())).toContain(`- ${level}`);
+    }
+
+    write(modelsPath(), [
+      'providers:',
+      '  deepseek:',
+      '    models:',
+      '      - id: reason',
+      '    modelOverrides:',
+      '      reason:',
+      '        thinking:',
+      '          mode: effort',
+      '          efforts: [low, high]',
+      '',
+    ].join('\n'));
+    await writeModelOverride({ provider: 'deepseek', modelId: 'reason', reasoningEffort: 'medium' });
+    const after = read(modelsPath());
+    expect(after).toContain('- low');
+    expect(after).toContain('- high');
+    expect(after).toContain('- medium');
+  });
+
+  test('clearing the last override drops the whole entry', async () => {
+    seedModels();
+    await writeModelOverride({ provider: 'deepseek', modelId: 'chat', reasoningEffort: 'high' });
+    expect(read(modelsPath())).toContain('defaultLevel: high');
+    await writeModelOverride({ provider: 'deepseek', modelId: 'chat', reasoningEffort: null });
+    expect(read(modelsPath())).not.toContain('modelOverrides');
+  });
+
+  test('a malformed modelOverrides node is refused rather than replaced', async () => {
+    write(modelsPath(), 'providers:\n  deepseek:\n    models:\n      - id: chat\n    modelOverrides: not-a-map\n');
+    await expect(writeModelOverride({ provider: 'deepseek', modelId: 'chat', maxTokens: 5 }))
+      .rejects.toThrow(/modelOverrides must be a mapping/);
+    expect(read(modelsPath())).toContain('modelOverrides: not-a-map');
+  });
+});
+
+describe('SCHEMA_EXTRAS', () => {
+  test('every extra is a complete UI row with a known type', () => {
+    for (const [key, entry] of Object.entries(SCHEMA_EXTRAS)) {
+      expect(key.length).toBeGreaterThan(0);
+      expect(['boolean', 'string', 'number', 'enum', 'array', 'record']).toContain(entry.type);
+      expect(entry.ui.tab.length).toBeGreaterThan(0);
+      expect(entry.ui.label.length).toBeGreaterThan(0);
+      expect(entry.ui.description.length).toBeGreaterThan(0);
+    }
+  });
+
+  test('pins the rows whose defaults the panel renders', () => {
+    expect(SCHEMA_EXTRAS['retry.enabled']).toMatchObject({ type: 'boolean', default: true });
+    expect(SCHEMA_EXTRAS['cycleOrder']).toMatchObject({ type: 'array', default: ['smol', 'default', 'slow'] });
+    expect(SCHEMA_EXTRAS['disabledProviders']).toMatchObject({ type: 'array', default: [] });
+    expect(SCHEMA_EXTRAS['compaction.reserveTokens']?.type).toBe('number');
+    expect(SCHEMA_EXTRAS['compaction.reserveTokens']).not.toHaveProperty('default');
+  });
+
+  test('an extra never silently overrides an upstream schema row', () => {
+    const upstream = Object.keys(OMP_SCHEMA.entries);
+    for (const key of Object.keys(SCHEMA_EXTRAS)) {
+      expect(upstream).not.toContain(key);
+    }
+  });
+});

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

@@ -0,0 +1,128 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Read-modify-write of an omp YAML config file: an exclusive Kabmo lock, a
+ * comment-preserving document model, an external-change retry, and an atomic
+ * write that keeps the file's mode and symlink.
+ *
+ * Why the `yaml` document model rather than `Bun.YAML` (plain objects):
+ *
+ * - **Comments survive.** `~/.omp/agent/models.yml` is a hand-authored file —
+ *   its providers carry notes and per-model annotations. `Bun.YAML.parse` +
+ *   `stringify` discards every comment; a single model fetch would delete them.
+ * - **Byte-stable round-trips.** Serializing the live `models.yml` through the
+ *   document model reproduces the file exactly (23210 bytes in, 23210 out).
+ *   `Bun.YAML.stringify(doc, null, 2)` rewrites it in a different style — and,
+ *   worse, emits `key: ` headers with a trailing space, which is not omp's own
+ *   canonical form (`stringifyYamlConfig` strips that space).
+ *
+ * `Bun.YAML` remains the *parser* for read-only probes, where comments and
+ * formatting are irrelevant.
+ *
+ * Concurrency: omp serializes its own config writes with an OS-level `flock(2)`
+ * on `${path}.lock`. That lock is not reachable from Bun (no `flock` binding,
+ * and the lock file omp creates must not be deleted out from under it), so the
+ * Kabmo takes its OWN lock file and closes the remaining window with the
+ * external-change check below: if the file moved between the read and the
+ * write, the edit is replayed against the fresh content instead of clobbering
+ * whatever omp just wrote.
+ */
+
+import { parseDocument, isMap, isScalar, isSeq, type Document, type YAMLSeq } from 'yaml';
+import { withConfigLock } from '@/server/lib/fs/config-lock';
+import { writeFileAtomic } from '@/server/lib/fs/atomic-write';
+
+/** A config file that is not a YAML mapping, or not valid YAML at all. */
+export class OmpConfigError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'OmpConfigError';
+  }
+}
+
+export interface DocumentEdit<T> {
+  result: T;
+  /** `false` when the edit turned out to be a no-op — the file is left as it is. */
+  changed: boolean;
+}
+
+/** The sequence node at `path`, when it is a sequence — `null` otherwise. */
+export function seqAt(doc: Document, path: (string | number)[]): YAMLSeq | null {
+  const node = doc.getIn(path);
+  return isSeq(node) ? node : null;
+}
+
+/**
+ * The plain JavaScript value of a YAML node — never a node.
+ *
+ * `node.get(key, true)` is not enough: the `keepScalar` flag only unwraps
+ * scalars, so a map or sequence still comes back as a node, where
+ * `Array.isArray` is `false` and a naive membership check silently sees an
+ * empty collection.
+ */
+export function plainOf<T = unknown>(doc: Document, node: unknown): T | undefined {
+  if (node === undefined || node === null) return undefined;
+  if (isScalar(node)) return node.value as T;
+  if (isMap(node) || isSeq(node)) return node.toJS(doc) as T;
+  return undefined;
+}
+
+/** The plain JavaScript value at `path` — never a node. */
+export function valueAt<T = unknown>(doc: Document, path: (string | number)[]): T | undefined {
+  return plainOf<T>(doc, doc.getIn(path));
+}
+
+const EXTERNAL_CHANGE_RETRIES = 5;
+
+/** Identity of a file version: absent files hash to `missing`. */
+async function fileGeneration(path: string): Promise<string> {
+  try {
+    const stat = await Bun.file(path).stat();
+    return `${stat.mtimeMs}:${stat.size}`;
+  } catch {
+    return 'missing';
+  }
+}
+
+/**
+ * Edit an omp YAML config in place. `edit` receives a live document, mutates it,
+ * and reports whether anything actually changed; the write only happens when it
+ * did. Replayed when another process writes the file mid-edit, so the edit is
+ * never applied on top of stale content.
+ *
+ * A file created here is `0600`: both omp configs carry plaintext credentials
+ * (`models.yml` holds provider `apiKey`s), and omp opens its own config temp
+ * with `wx, 0o600` for the same reason. An existing file keeps its own mode.
+ */
+export async function withOmpYamlDocument<T>(
+  path: string,
+  edit: (doc: Document) => DocumentEdit<T> | Promise<DocumentEdit<T>>,
+): Promise<T> {
+  // Not `${path}.lock`: that file belongs to omp's own flock lease.
+  return withConfigLock(`${path}.kabmo.lock`, async () => {
+    for (let attempt = 0; ; attempt++) {
+      const before = await fileGeneration(path);
+      const source = (await Bun.file(path).exists()) ? await Bun.file(path).text() : '';
+      const doc = parseDocument(source);
+      if (doc.errors.length > 0) {
+        throw new OmpConfigError(`${path} is not valid YAML: ${doc.errors[0].message.split('\n')[0]}`);
+      }
+      if (doc.contents !== null && !isMap(doc.contents)) {
+        throw new OmpConfigError(`${path} must contain a YAML mapping`);
+      }
+
+      const { result, changed } = await edit(doc);
+      if (!changed) return result;
+      if (attempt < EXTERNAL_CHANGE_RETRIES && (await fileGeneration(path)) !== before) {
+        // Another process rewrote the file while this edit was being computed.
+        // Replay against its content rather than overwrite the newer change.
+        continue;
+      }
+      await writeFileAtomic(path, doc.toString({ indent: 2 }), { createMode: 0o600 });
+      return result;
+    }
+  });
+}