ompchamber 0.3.0

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

@@ -0,0 +1,118 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * 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.
+ */
+
+import fs from 'fs';
+import { join } from 'path';
+import { getAgentDir, pathExists } from '@/server/lib/omp/core/paths';
+import { writeFileAtomic } from '@/server/lib/fs/atomic-write';
+import { parseFrontmatter } from '@/server/lib/omp/config/yaml';
+
+const MAX_SKILL_MD_BYTES = 512 * 1024;
+
+export interface DiscoveredSkill {
+  id: string;
+  name: string;
+  description: string;
+  /** Which disk root the skill was discovered from. */
+  sourceRoot: 'user' | 'project';
+  filePath: string;
+}
+
+async function parseSkillMd(filePath: string, sourceRoot: 'user' | 'project'): Promise<DiscoveredSkill | undefined> {
+  try {
+    const file = Bun.file(filePath);
+    if ((await file.stat()).size > MAX_SKILL_MD_BYTES) return undefined;
+    const text = await file.text();
+    const { data } = parseFrontmatter(text);
+    const name = data.name || filePath.split('/').slice(-2, -1)[0] || '';
+    if (!name) return undefined;
+    return {
+      id: `omp-${sourceRoot}-${name}`,
+      name,
+      description: data.description || '',
+      sourceRoot,
+      filePath,
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * 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);
+    }
+  } catch {
+    // Unreadable root yields no skills rather than throwing.
+  }
+  return found;
+}
+
+/**
+ * Discover native skills from user + optional project roots. User skills win
+ * over project skills with the same folder name. Never throws.
+ */
+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);
+    }
+  }
+  return [...byName.values()];
+}
+
+/**
+ * Atomically toggle `disableModelInvocation` in a SKILL.md frontmatter —
+ * read-modify-write via temp+rename, preserving the rest of the file.
+ */
+export async function setSkillModelInvocation(filePath: string, disable: boolean): Promise<boolean> {
+  try {
+    const file = Bun.file(filePath);
+    if (!(await file.exists()) || (await file.stat()).size > MAX_SKILL_MD_BYTES) return false;
+    const text = await file.text();
+    const flag = `disableModelInvocation: ${disable}`;
+    let next: string;
+    if (/^---\r?\n[\s\S]*?\r?\n---/.test(text)) {
+      if (/^disableModelInvocation:/m.test(text)) {
+        next = text.replace(/^disableModelInvocation:.*$/m, flag);
+      } else {
+        // Insert before the closing --- of the frontmatter.
+        next = text.replace(/^---\r?\n([\s\S]*?)\r?\n---/, (full, front) => {
+          void full;
+          return `---\n${front}\n${flag}\n---`;
+        });
+      }
+    } else {
+      next = `---\n${flag}\n---\n\n${text}`;
+    }
+    if (next === text) return false;
+    await writeFileAtomic(filePath, next);
+    return true;
+  } catch {
+    return false;
+  }
+}

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

@@ -0,0 +1,48 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Shared YAML/config helpers for the native OMP config files: the canonical
+ * `~/.omp/agent/config.yml` path, a top-level-mapping assertion, and the minimal
+ * frontmatter parser used by agent and skill markdown files.
+ */
+
+import { join } from 'path';
+import { getAgentDir } from '@/server/lib/omp/core/paths';
+import { isRecord } from '@/shared/lib/util/guards';
+
+/** Native OMP user config path: ~/.omp/agent/config.yml. */
+export function getOmpConfigPath(): string {
+  return join(getAgentDir(), 'config.yml');
+}
+
+/** Parses a YAML file that must be a top-level mapping; throws otherwise. */
+export function asMapping(parsed: unknown, path: string): Record<string, unknown> {
+  if (!isRecord(parsed)) throw new Error(`${path} must contain a YAML mapping`);
+  return parsed;
+}
+
+/**
+ * Minimal YAML frontmatter (---\nkey: value\n---) parser for agent/skill files.
+ * Only top-level keys belong to the map; indented lines are nested block
+ * content (e.g. an `output:` JSON schema) and must not override top-level keys.
+ */
+export function parseFrontmatter(text: string): { data: Record<string, string>; body: string } {
+  const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(text);
+  if (!match) return { data: {}, body: text };
+  const data: Record<string, string> = {};
+  for (const line of match[1].split(/\r?\n/)) {
+    if (/^\s/.test(line)) continue;
+    const idx = line.indexOf(':');
+    if (idx <= 0) continue;
+    const key = line.slice(0, idx).trim();
+    let value = line.slice(idx + 1).trim();
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+    if (key) data[key] = value;
+  }
+  return { data, body: text.slice(match[0].length) };
+}

package/src/server/lib/omp/core/auth-credentials.ts

@@ -0,0 +1,87 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Read-only access to the omp agent's stored provider credentials
+ * (~/.omp/agent/models.yml `providers.<slug>.apiKey`, then
+ * ~/.omp/agent/agent.db `auth_credentials`). These are omp's own secrets —
+ * chamber only reads them to build usage reports and never writes, mutates,
+ * logs, or echoes them back over HTTP.
+ */
+
+import { join } from 'path';
+import { Database } from 'bun:sqlite';
+import { getAgentDir } from '@/server/lib/omp/core/paths';
+import { getModelsConfigPath } from '@/server/lib/omp/config/providers';
+import { isRecord } from '@/shared/lib/util/guards';
+
+const AUTH_CREDENTIALS_TABLE = 'auth_credentials';
+const API_KEY_CREDENTIAL_TYPE = 'api_key';
+
+/** `providers.<slug>.apiKey` from models.yml, or null when absent/blank. */
+async function readModelsYmlApiKey(slug: string): Promise<string | null> {
+  const path = await getModelsConfigPath();
+  if (!(await Bun.file(path).exists())) return null;
+  try {
+    const data = Bun.YAML.parse(await Bun.file(path).text());
+    if (!isRecord(data)) return null;
+    const providers = data.providers;
+    if (!isRecord(providers)) return null;
+    const entry = providers[slug];
+    if (!isRecord(entry)) return null;
+    const apiKey = entry.apiKey;
+    return typeof apiKey === 'string' && apiKey.trim().length > 0 ? apiKey.trim() : null;
+  } catch {
+    return null; // no-excuse-ok: catch — a malformed models.yml is a soft miss
+  }
+}
+
+/** The `key` field of a JSON credential blob, or null when absent/non-string. */
+function keyFromCredentialJson(data: string): string | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(data);
+  } catch {
+    return null; // no-excuse-ok: catch — malformed credential blob is a soft miss
+  }
+  if (!isRecord(parsed)) return null;
+  const key = parsed.key;
+  return typeof key === 'string' && key.trim().length > 0 ? key.trim() : null;
+}
+
+/** A live, enabled api_key credential for `slug` from agent.db, or null. */
+async function readAgentDbApiKey(slug: string): Promise<string | null> {
+  const dbPath = join(getAgentDir(), 'agent.db');
+  if (!(await Bun.file(dbPath).exists())) return null;
+  let db: Database | null = null;
+  try {
+    db = new Database(dbPath, { readonly: true });
+    const row = db
+      .query<{ data?: string }, [string, string]>(
+        `SELECT data FROM ${AUTH_CREDENTIALS_TABLE}
+       WHERE provider = ? AND credential_type = ? AND disabled_cause IS NULL
+       LIMIT 1`,
+      )
+      .get(slug, API_KEY_CREDENTIAL_TYPE);
+    if (!row || typeof row.data !== 'string' || row.data.length === 0) return null;
+    return keyFromCredentialJson(row.data);
+  } catch {
+    return null; // no-excuse-ok: catch — best-effort read of an external store
+  } finally {
+    db?.close();
+  }
+}
+
+/**
+ * Resolve a provider's API key from omp's own stores (models.yml, then
+ * agent.db), without consulting the app DB. Returns null when no live
+ * credential exists. The raw key never leaves omp-domain code — callers must
+ * not log or serialize it.
+ */
+export async function readOmpProviderApiKey(slug: string): Promise<string | null> {
+  const fromYml = await readModelsYmlApiKey(slug);
+  if (fromYml) return fromYml;
+  return readAgentDbApiKey(slug);
+}

package/src/server/lib/omp/core/cli.ts

@@ -0,0 +1,69 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Locating the user's installed `omp` CLI. OMPChamber never embeds the
+ * (Bun-only) @oh-my-pi SDK — every live-agent capability goes through the
+ * omp binary, so its absence is a first-class, user-visible state.
+ *
+ * Faithful port of omp-web/lib/omp/omp-cli.ts (binary resolution only; the
+ * version probe is not needed by the chamber).
+ */
+
+import { existsSync } from 'fs';
+import { homedir } from 'os';
+import { delimiter, join } from 'path';
+
+let cachedBin: string | null = null;
+let binMissAt = 0;
+
+const BIN_NAME = process.platform === 'win32' ? 'omp.exe' : 'omp';
+// Only successes are cached for the process lifetime. omp may be installed (or
+// PATH repaired) while the server runs; a permanently cached "not found" would
+// keep the UI reporting a missing binary until restart.
+const MISS_TTL_MS = 30_000;
+
+/** Clear probes after an explicit `omp update` so the next request rechecks it. */
+export function invalidateOmpCliCache(): void {
+  cachedBin = null;
+  binMissAt = 0;
+}
+
+function probeOmpBin(): string | null {
+  const override = Bun.env.OMP_WEB_OMP_BIN;
+  if (override) return existsSync(override) ? override : null;
+
+  const onPath = Bun.which(BIN_NAME);
+  if (onPath) return onPath;
+
+  // GUI-launched processes often miss homebrew/bun dirs in PATH; probe the
+  // usual install locations before giving up.
+  const fallbackPath = [
+    '/opt/homebrew/bin',
+    '/usr/local/bin',
+    join(homedir(), '.bun', 'bin'),
+    join(homedir(), '.local', 'bin'),
+  ].join(delimiter);
+  return Bun.which(BIN_NAME, { PATH: fallbackPath });
+}
+
+/** Resolve the omp binary: OMP_WEB_OMP_BIN override, then PATH lookup. Returns
+ * null when omp is not installed. A hit is cached for the process lifetime; a
+ * miss is re-probed after MISS_TTL_MS. */
+export function resolveOmpBin(): string | null {
+  // A global Bun/npm update can replace or remove its launcher while this
+  // server process is still alive. Never keep returning a stale cache entry.
+  if (cachedBin && existsSync(cachedBin)) return cachedBin;
+  cachedBin = null;
+  if (Date.now() - binMissAt < MISS_TTL_MS) return null;
+  const found = probeOmpBin();
+  if (found) {
+    cachedBin = found;
+    binMissAt = 0;
+    return found;
+  }
+  binMissAt = Date.now();
+  return null;
+}

package/src/server/lib/omp/core/paths.ts

@@ -0,0 +1,154 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Read-only port of omp-web's agent-directory resolution
+ * (omp-web/lib/omp/paths.ts → oh-my-pi packages/utils/src/dirs.ts).
+ *
+ * Resolves where oh-my-pi keeps its agent state so OMPChamber can *discover*
+ * the same workspaces and sessions the omp agent writes, without owning or
+ * mutating them. Covered: PI_CODING_AGENT_DIR override, PI_CONFIG_DIR rename,
+ * and the XDG data layout (used only when $XDG_DATA_HOME/omp already exists).
+ */
+
+import { existsSync, realpathSync } from 'fs';
+import { homedir, tmpdir } from 'os';
+import * as path from 'path';
+
+const APP_NAME = 'omp';
+const CONFIG_DIR_NAME = '.omp';
+
+/** Config root name (~/.omp), honoring the PI_CONFIG_DIR rename. */
+export function getConfigDirName(): string {
+  return Bun.env.PI_CONFIG_DIR || CONFIG_DIR_NAME;
+}
+
+/** Config root: ~/.omp (plus PI_CONFIG_DIR rename). */
+export function getConfigRoot(): string {
+  return path.join(homedir(), getConfigDirName());
+}
+
+/** The agent state directory (~/.omp/agent). PI_CODING_AGENT_DIR overrides it. */
+export function getAgentDir(): string {
+  const override = Bun.env.PI_CODING_AGENT_DIR;
+  if (override) return path.resolve(override);
+  return path.join(getConfigRoot(), 'agent');
+}
+
+function isDefaultAgentDir(): boolean {
+  const override = Bun.env.PI_CODING_AGENT_DIR;
+  if (override) {
+    return path.resolve(override) === path.join(getConfigRoot(), 'agent');
+  }
+  return true;
+}
+
+/** XDG data root for the default agent dir: only honored on linux/darwin when
+ *  $XDG_DATA_HOME/omp already exists — omp treats the XDG layout as opt-in via
+ *  `omp config init-xdg`. XDG flattens the `agent/` prefix:
+ *  ~/.omp/agent/sessions → $XDG_DATA_HOME/omp/sessions. */
+function xdgDataAgentRoot(): string | undefined {
+  if (process.platform !== 'linux' && process.platform !== 'darwin') return undefined;
+  if (!isDefaultAgentDir()) return undefined;
+  const value = Bun.env.XDG_DATA_HOME;
+  if (!value) return undefined;
+  try {
+    const appRoot = path.join(value, APP_NAME);
+    return existsSync(appRoot) ? appRoot : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function agentDataSubdir(subdir: string): string {
+  const xdg = xdgDataAgentRoot();
+  return path.join(xdg ?? getAgentDir(), subdir);
+}
+
+/** ~/.omp/agent/sessions (or $XDG_DATA_HOME/omp/sessions). */
+export function getSessionsDir(): string {
+  return agentDataSubdir('sessions');
+}
+
+/** ~/.omp/agent/projects.json — omp-web's managed-project registry. */
+export function getProjectsRegistryPath(): string {
+  return path.join(getAgentDir(), 'projects.json');
+}
+
+/** Best-effort canonicalization (resolve symlinks when the path exists). */
+export function canonicalize(value: string): string {
+  try {
+    return realpathSync.native(value);
+  } catch {
+    return value;
+  }
+}
+
+/**
+ * True when a path exists — directory, file, or resolvable symlink. Use this
+ * instead of `Bun.file(p).exists()`: that method answers for regular files and
+ * FIFOs only and reports false for a directory that exists, so a directory
+ * guard silently empties every scan behind it. That asymmetry is documented
+ * (BunFile.exists: "returns true for regular files and FIFOs, false for
+ * directories") and tracked as open bug oven-sh/bun#21537, unfixed as of
+ * Bun 1.4.2 — so this is the standing behaviour to code against, not a
+ * regression to wait out.
+ *
+ * `stat()` follows symlinks like `existsSync` and throws for missing or
+ * dangling paths.
+ */
+export async function pathExists(target: string): Promise<boolean> {
+  try {
+    await Bun.file(target).stat();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Comparison key for a project path. Realpath resolution alone is not enough
+ * to match two spellings of the same directory: macOS reports `/var/...` while
+ * its realpath is `/private/var/...`, and a tombstone written before the path
+ * existed keeps its unresolved form. Canonicalizing both sides plus a
+ * trailing-separator strip makes the two forms comparable.
+ */
+export function projectPathKey(value: string): string {
+  const canonical = canonicalize(value);
+  const withoutTrailingSeparators = canonical.replace(/\/+$/, '');
+  return withoutTrailingSeparators || canonical;
+}
+
+/**
+ * Session directory slug for a cwd — faithful port of
+ * getDefaultSessionDirName (oh-my-pi session-paths.ts):
+ * - under $HOME: "-" + relative path with [/\:] replaced by dashes ("-" for $HOME itself)
+ * - under tmpdir: "-tmp" (+ "-" + dashed relative path)
+ * - otherwise: legacy absolute encoding "--abs-path-dashed--"
+ */
+export function getSessionDirNameForCwd(cwd: string): string {
+  const canonicalCwd = canonicalize(path.resolve(cwd));
+  const canonicalHome = canonicalize(homedir());
+  const canonicalTmp = canonicalize(tmpdir());
+  const homeRelative = path.relative(canonicalHome, canonicalCwd);
+  const tempRelative = path.relative(canonicalTmp, canonicalCwd);
+  if (homeRelative === '' || (!homeRelative.startsWith('..') && !path.isAbsolute(homeRelative))) {
+    return encodeRelativeSessionDirName('-', homeRelative);
+  }
+  if (tempRelative === '' || (!tempRelative.startsWith('..') && !path.isAbsolute(tempRelative))) {
+    return encodeRelativeSessionDirName('-tmp', tempRelative);
+  }
+  return encodeLegacyAbsoluteSessionDirName(canonicalCwd);
+}
+
+function encodeRelativeSessionDirName(prefix: string, relative: string): string {
+  const encoded = relative.replace(/[/\\:]/g, '-');
+  return encoded ? (prefix.endsWith('-') ? `${prefix}${encoded}` : `${prefix}-${encoded}`) : prefix;
+}
+
+function encodeLegacyAbsoluteSessionDirName(cwd: string): string {
+  const resolvedCwd = path.resolve(cwd);
+  return `--${resolvedCwd.replace(/^[/\\]/, '').replace(/[/\\:]/g, '-')}--`;
+}

package/src/server/lib/omp/core/registry.ts

@@ -0,0 +1,140 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Read-only port of omp-web's managed-project registry
+ * (omp-web/lib/project-registry.ts) — enough to reproduce how the omp-web
+ * sidebar composes its workspace list:
+ *
+ *   1. read ~/.omp/agent/projects.json (registered projects with alias /
+ *      sortOrder / hidden presentation state),
+ *   2. discover every project that has sessions on disk
+ *      (session-discovered projects, e.g. before omp-web registered them),
+ *   3. merge: registered first (sortOrder, then most-recently-added), hidden
+ *      entries excluded, discovered extras follow sorted by path.
+ *
+ * OMPChamber only READS this file — it never writes the agent's registry.
+ */
+
+import { canonicalize, getProjectsRegistryPath } from '@/server/lib/omp/core/paths';
+import type { OmpProject } from '@/shared/types/omp/session';
+
+/** Error carrying a stable code (errors.* key) for client localization. */
+export class ProjectPathError extends Error {
+  code: string;
+  constructor(code: string, message: string) {
+    super(message);
+    this.name = 'ProjectPathError';
+    this.code = code;
+  }
+}
+
+export interface OmpProjectRegistryEntry {
+  /** Canonical project path (worktrees resolve to their main repo root). */
+  path: string;
+  /** ISO timestamp of the most recent explicit add. */
+  addedAt?: string;
+  /** True when the user removed the project from the sidebar. Hidden entries
+   *  suppress session re-discovery until the project is added again. */
+  hidden?: boolean;
+  /** Optional display-only workspace name. */
+  alias?: string;
+  /** Explicit sidebar position; lower values appear first. */
+  sortOrder?: number;
+}
+
+export interface OmpProjectRegistryFile {
+  version: 1;
+  projects: OmpProjectRegistryEntry[];
+}
+
+const EMPTY_REGISTRY: OmpProjectRegistryFile = { version: 1, projects: [] };
+
+function comparableProjectPath(value: string): string {
+  let normalized = value.replace(/\\/g, '/');
+  const windowsForm = /^[a-zA-Z]:[\\/]/.test(normalized) || /^\/\//.test(normalized);
+  normalized = normalized.replace(/\/{2,}/g, '/').replace(/\/+$/, '');
+  return windowsForm ? normalized.toLowerCase() : normalized;
+}
+
+/** Parse registry JSON; missing, corrupt, or foreign-shaped input yields an
+ *  empty registry rather than failing the whole sidebar. */
+export function parseProjectRegistry(raw: string): OmpProjectRegistryFile {
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return EMPTY_REGISTRY;
+    if (!('projects' in parsed) || !Array.isArray(parsed.projects)) return EMPTY_REGISTRY;
+    const entries: OmpProjectRegistryEntry[] = [];
+    for (const item of parsed.projects) {
+      if (!item || typeof item !== 'object' || Array.isArray(item)) continue;
+      if (!('path' in item) || typeof item.path !== 'string' || !item.path.trim()) continue;
+      const record = item as Record<string, unknown>;
+      entries.push({
+        path: canonicalize(record.path as string),
+        addedAt: typeof record.addedAt === 'string' ? record.addedAt : undefined,
+        hidden: record.hidden === true,
+        alias: typeof record.alias === 'string' && record.alias.trim() ? record.alias.trim() : undefined,
+        sortOrder:
+          typeof record.sortOrder === 'number' && Number.isFinite(record.sortOrder) ? record.sortOrder : undefined,
+      });
+    }
+    return { version: 1, projects: entries };
+  } catch {
+    return EMPTY_REGISTRY;
+  }
+}
+
+/** Load ~/.omp/agent/projects.json (missing/corrupt → empty registry). */
+export async function loadProjectRegistry(registryPath: string = getProjectsRegistryPath()): Promise<OmpProjectRegistryFile> {
+  if (!(await Bun.file(registryPath).exists())) return EMPTY_REGISTRY;
+  try {
+    return parseProjectRegistry(await Bun.file(registryPath).text());
+  } catch {
+    return EMPTY_REGISTRY;
+  }
+}
+
+/**
+ * Merge registered projects with session-discovered ones, excluding hidden
+ * entries. Registered projects come first in most-recently-added order (or
+ * explicit sortOrder); discovered projects follow sorted by path.
+ */
+export function mergeProjects(registry: OmpProjectRegistryFile, discovered: Iterable<string>): OmpProject[] {
+  const hidden = new Set(
+    registry.projects.filter((p) => p.hidden).map((p) => comparableProjectPath(p.path)),
+  );
+  const registered: OmpProject[] = [];
+  const registeredSeen = new Set<string>();
+  for (const p of registry.projects
+    .filter((entry) => !entry.hidden)
+    .sort((a, b) => {
+      const aOrder = a.sortOrder ?? Number.POSITIVE_INFINITY;
+      const bOrder = b.sortOrder ?? Number.POSITIVE_INFINITY;
+      if (aOrder !== bOrder) return aOrder - bOrder;
+      return (b.addedAt ?? '').localeCompare(a.addedAt ?? '');
+    })) {
+    const key = comparableProjectPath(p.path);
+    if (registeredSeen.has(key)) continue; // tolerate hand-edited duplicates
+    registeredSeen.add(key);
+    registered.push({
+      path: p.path,
+      addedAt: p.addedAt,
+      alias: p.alias,
+      sortOrder: p.sortOrder,
+      discovered: false,
+    });
+  }
+
+  const extra: OmpProject[] = [];
+  const extraSeen = new Set<string>();
+  for (const raw of new Set([...discovered].filter(Boolean).map(canonicalize))) {
+    const key = comparableProjectPath(raw);
+    if (hidden.has(key) || registeredSeen.has(key) || extraSeen.has(key)) continue;
+    extraSeen.add(key);
+    extra.push({ path: raw, discovered: true });
+  }
+  extra.sort((a, b) => a.path.localeCompare(b.path));
+  return [...registered, ...extra];
+}