ompchamber 0.3.0

package/src/server/lib/chat/session-store.server.ts

@@ -0,0 +1,61 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Shared session-message source resolution for the telemetry endpoints.
+ * Source priority: omp session JSONL on disk, then the chamber DB copy for
+ * chat-created sessions, then mock data — so /api/telemetry/context and
+ * /api/telemetry/raw-messages always agree on where a session's turns live.
+ */
+
+import { getDb } from '@/server/db.server';
+import { isMockMode } from '@/server/mock.server';
+import { getSessionData } from '@/client/data/mock/chat';
+import { findSessionFileById } from '@/server/lib/omp/session/locator';
+
+export interface JsonlSessionSource {
+  kind: 'jsonl';
+  filePath: string;
+}
+
+export interface MessageSessionSource {
+  kind: 'messages';
+  title: string;
+  messages: unknown[];
+}
+
+export type SessionSource = JsonlSessionSource | MessageSessionSource;
+
+export async function loadSessionSource(sessionId: string | null): Promise<SessionSource | null> {
+  if (isMockMode()) {
+    if (!sessionId) return null;
+    const sessionMock = getSessionData(sessionId);
+    if (sessionMock && sessionMock.messages && sessionMock.messages.length > 0) {
+      return { kind: 'messages', title: sessionMock.title, messages: sessionMock.messages };
+    }
+    return null;
+  }
+
+  const db = await getDb();
+  if (!sessionId) return null;
+
+  // JSONL-first: omp sessions live on disk, so the raw panel shows full entries.
+  const filePath = await findSessionFileById(sessionId);
+  if (filePath) return { kind: 'jsonl', filePath };
+
+  // Chat-created sessions have no JSONL on disk — fall back to the DB copy.
+  const existing = await db.get('SELECT * FROM chat_sessions WHERE session_id = ?', [sessionId]);
+  if (existing) {
+    let parsedMessages: unknown[] = [];
+    try {
+      const parsed: unknown = JSON.parse(existing.messages);
+      if (Array.isArray(parsed)) parsedMessages = parsed;
+    } catch {
+      parsedMessages = [];
+    }
+    return { kind: 'messages', title: existing.title || `Session ${sessionId}`, messages: parsedMessages };
+  }
+  return null;
+}

package/src/server/lib/db/client.ts

@@ -0,0 +1,55 @@
+import { Database } from 'bun:sqlite';
+
+/**
+ * `bun:sqlite` compatibility client. The promise surface mirrors the retired
+ * `sqlite` package so the 38 existing consumers keep compiling unchanged, and
+ * the `T = any` defaults match that package's own signatures.
+ */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+export interface DbClient {
+  get<T = any>(sql: string, params?: any[]): Promise<T | undefined>;
+  all<T = any>(sql: string, params?: any[]): Promise<T[]>;
+  run(sql: string, params?: any[]): Promise<{ changes: number; lastID: number }>;
+  exec(sql: string): Promise<void>;
+  raw: Database;
+}
+
+/**
+ * Open a database and return the compatibility client.
+ *
+ * Statements are prepared once and cached: `bun:sqlite` statements are
+ * reusable, and the app issues thousands of small queries per request cycle
+ * (sidebar scans, telemetry probes, file listings).
+ */
+export function createDb(path: string): DbClient {
+  const raw = new Database(path, { create: true });
+  raw.exec('PRAGMA journal_mode = WAL');
+  raw.exec('PRAGMA foreign_keys = ON');
+
+  const stmts = new Map<string, ReturnType<Database['query']>>();
+  const prep = (sql: string) => {
+    let stmt = stmts.get(sql);
+    if (!stmt) {
+      stmt = raw.query(sql);
+      stmts.set(sql, stmt);
+    }
+    return stmt;
+  };
+
+  return {
+    async get<T>(sql: string, params: any[] = []) {
+      return prep(sql).get(...(params as never[])) as T | undefined;
+    },
+    async all<T>(sql: string, params: any[] = []) {
+      return prep(sql).all(...(params as never[])) as T[];
+    },
+    async run(sql: string, params: any[] = []) {
+      const result = raw.run(sql, params as never);
+      return { changes: result.changes, lastID: Number(result.lastInsertRowid) };
+    },
+    async exec(sql: string) {
+      raw.exec(sql);
+    },
+    raw,
+  };
+}

package/src/server/lib/db/settings-store.ts

@@ -0,0 +1,148 @@
+import type { DbClient } from '@/server/lib/db/client';
+import { isMockMode } from '@/server/mock.server';
+
+/**
+ * Shared persistence helpers for the `app_settings` key/value table. Every
+ * settings route used to hand-roll the same SELECT → JSON.parse → Array.isArray
+ * → INSERT OR REPLACE state machine; this module owns it once.
+ *
+ * SQL is intentionally identical to the call sites it replaces: same table,
+ * same columns, same `INSERT OR REPLACE` (no schema change, no migration).
+ */
+
+const SELECT_VALUE_SQL = 'SELECT value FROM app_settings WHERE key = ?';
+const SELECT_ALL_SQL = 'SELECT * FROM app_settings';
+const UPSERT_VALUE_SQL = 'INSERT OR REPLACE INTO app_settings (key, value) VALUES (?, ?)';
+
+/** Read + parse one settings key, falling back on an absent or malformed row. */
+export async function readSettingsJson<T>(db: DbClient, key: string, fallback: T): Promise<T> {
+  const row = await db.get<{ value?: string }>(SELECT_VALUE_SQL, [key]);
+  if (!row?.value) return fallback;
+  try {
+    return JSON.parse(row.value);
+  } catch {
+    return fallback;
+  }
+}
+
+/** Persist one settings key as JSON (matches the historical `JSON.stringify`). */
+export async function writeSettingsJson(db: DbClient, key: string, value: unknown): Promise<void> {
+  await db.run(UPSERT_VALUE_SQL, [key, JSON.stringify(value)]);
+}
+
+/** Persist one settings key as a raw string (settings/root.ts scalar branch). */
+export async function writeSettingsRaw(db: DbClient, key: string, value: string): Promise<void> {
+  await db.run(UPSERT_VALUE_SQL, [key, value]);
+}
+
+/** Read every settings row, parsing JSON where possible and keeping raw text otherwise. */
+export async function readAllSettingsJson(db: DbClient): Promise<Record<string, unknown>> {
+  const rows = await db.all<{ key: string; value: string }>(SELECT_ALL_SQL);
+  const settings: Record<string, unknown> = {};
+  for (const row of rows) {
+    try {
+      settings[row.key] = JSON.parse(row.value);
+    } catch {
+      settings[row.key] = row.value;
+    }
+  }
+  return settings;
+}
+
+interface StoredListOptions<T> {
+  /** Used when the row is absent or malformed. */
+  absent?: T[];
+  /** Used when the stored value parses to an empty array. */
+  empty?: T[];
+}
+
+export interface SettingsListStore<T> {
+  key: string;
+  /** Loader semantics: mock default, first-read seeding in mock mode, array-guarded parse. */
+  read(db: DbClient): Promise<T[]>;
+  /** Action semantics: no seeding; `absent`/`empty` control the fallbacks. */
+  readStored(db: DbClient, options?: StoredListOptions<T>): Promise<T[]>;
+  write(db: DbClient, items: T[]): Promise<void>;
+  /** Array | { <plural>: [...] } | { <singular>: item } → resulting list (not persisted). */
+  upsert(db: DbClient, body: unknown, options?: StoredListOptions<T>): Promise<T[]>;
+  /** Merge one item by identity into the stored list (not persisted). */
+  upsertItem(db: DbClient, item: T, options?: StoredListOptions<T>): Promise<T[]>;
+  /** Filter one item out by identity and persist the result. */
+  remove(db: DbClient, id: string, options?: StoredListOptions<T>): Promise<T[]>;
+}
+
+/**
+ * Build a JSON-list store for one `app_settings` key. `mockDefaults` is seeded
+ * on first read in mock mode and returned whenever the row is absent or
+ * unparseable; `idOf`/`singular`/`plural` drive the upsert + remove shapes.
+ */
+export function createSettingsListStore<T>(options: {
+  key: string;
+  mockDefaults: T[];
+  idOf: (item: T) => string;
+  singular: string;
+  plural: string;
+}): SettingsListStore<T> {
+  const { key, mockDefaults, idOf, singular, plural } = options;
+
+  async function read(db: DbClient): Promise<T[]> {
+    const mock = isMockMode();
+    const row = await db.get<{ value?: string }>(SELECT_VALUE_SQL, [key]);
+    if (row?.value) {
+      try {
+        const parsed = JSON.parse(row.value);
+        if (Array.isArray(parsed)) return parsed;
+      } catch {}
+      return mock ? mockDefaults : [];
+    }
+    if (mock) {
+      await db.run(UPSERT_VALUE_SQL, [key, JSON.stringify(mockDefaults)]);
+      return mockDefaults;
+    }
+    return [];
+  }
+
+  async function readStored(db: DbClient, options: StoredListOptions<T> = {}): Promise<T[]> {
+    const row = await db.get<{ value?: string }>(SELECT_VALUE_SQL, [key]);
+    let list: T[] | null = null;
+    if (row?.value) {
+      try {
+        const parsed = JSON.parse(row.value);
+        if (Array.isArray(parsed)) list = parsed;
+      } catch {}
+    }
+    if (list === null) return options.absent ?? (isMockMode() ? mockDefaults : []);
+    if (list.length === 0 && options.empty) return options.empty;
+    return list;
+  }
+
+  async function write(db: DbClient, items: T[]): Promise<void> {
+    await db.run(UPSERT_VALUE_SQL, [key, JSON.stringify(items)]);
+  }
+
+  async function upsertItem(db: DbClient, item: T, options: StoredListOptions<T> = {}): Promise<T[]> {
+    const list = await readStored(db, options);
+    const index = list.findIndex((entry) => idOf(entry) === idOf(item));
+    if (index >= 0) list[index] = item;
+    else list.push(item);
+    return list;
+  }
+
+  async function upsert(db: DbClient, body: unknown, options: StoredListOptions<T> = {}): Promise<T[]> {
+    if (Array.isArray(body)) return body;
+    if (typeof body === 'object' && body !== null) {
+      const record = body as Record<string, unknown>;
+      if (Array.isArray(record[plural])) return record[plural];
+      if (record[singular]) return upsertItem(db, record[singular] as T, options);
+    }
+    return [];
+  }
+
+  async function remove(db: DbClient, id: string, options: StoredListOptions<T> = {}): Promise<T[]> {
+    const list = (await readStored(db, options)).filter((item) => idOf(item) !== id);
+    await write(db, list);
+    return list;
+  }
+
+  return { key, read, readStored, write, upsert, upsertItem, remove };
+}

package/src/server/lib/fs/atomic-write.ts

@@ -0,0 +1,27 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Atomic file write: a sibling temp file is fully written, then renamed over
+ * the target. rename(2) is atomic on POSIX, so a crash mid-write leaves either
+ * the old file or the new one — never a truncated file. The temp file is
+ * removed (best-effort) when the write or rename fails.
+ */
+
+import fs from 'fs';
+import { dirname } from 'path';
+
+/** Writes `data` to `targetPath` via a sibling temp file then rename (atomic on POSIX). */
+export async function writeFileAtomic(targetPath: string, data: string): Promise<void> {
+  await fs.promises.mkdir(dirname(targetPath), { recursive: true });
+  const tempPath = `${targetPath}.tmp-${process.pid}-${Date.now()}`;
+  try {
+    await Bun.write(tempPath, data);
+    await fs.promises.rename(tempPath, targetPath);
+  } catch (error) {
+    await fs.promises.rm(tempPath, { force: true }).catch(() => undefined);
+    throw error;
+  }
+}

package/src/server/lib/fs/git-diff.ts

@@ -0,0 +1,116 @@
+import path from 'path';
+import type { FileDiffData } from '@/shared/types/git';
+import { runShell, shellOk } from '@/server/lib/fs/shell';
+
+/** Runs one git diff probe and returns its stdout ('' on failure). */
+async function gitOut(command: string, cwd: string, timeout: number): Promise<string> {
+  const result = await runShell(command, { cwd, timeout, maxBuffer: 1024 * 1024 * 2 });
+  return shellOk(result) ? result.stdout : '';
+}
+
+/**
+ * Fetch git diff for a specific file in the working directory or index.
+ */
+export async function fetchWorkingFileDiff(
+  targetDir: string,
+  file: string,
+  staged: boolean = false,
+  requestedStatus?: string
+): Promise<FileDiffData> {
+  const cleanFile = file.replace(/^[./\\]+/, '').replace(/\\/g, '/');
+  const fullPath = path.join(targetDir, cleanFile);
+  let status = requestedStatus && requestedStatus.trim() ? requestedStatus.trim() : 'M';
+  let diff = '';
+  let oldContent = '';
+  let newContent = '';
+  let additions = 0;
+  let deletions = 0;
+
+  try {
+    // Check porcelain status of this file
+    const statusResult = await gitOut(`git status --porcelain=v1 -- "${cleanFile}"`, targetDir, 10000);
+    const statusLine = statusResult.trim();
+    if (statusLine) {
+      status = statusLine.slice(0, 2).trim() || status;
+    }
+
+    // Try reading current new content from disk if it exists
+    try {
+      newContent = await Bun.file(fullPath).text();
+    } catch {
+      newContent = '';
+    }
+
+    // Read old content from index or HEAD
+    oldContent = await gitOut(`git show HEAD:"${cleanFile}"`, targetDir, 5000)
+      || await gitOut(`git show :0:"${cleanFile}"`, targetDir, 5000);
+
+    if (staged) {
+      // 1. Try staged diff (index vs HEAD), 2. HEAD diff, 3. unstaged diff
+      diff = await gitOut(`git diff --cached -- "${cleanFile}"`, targetDir, 10000)
+        || await gitOut(`git diff HEAD -- "${cleanFile}"`, targetDir, 10000)
+        || await gitOut(`git diff -- "${cleanFile}"`, targetDir, 10000);
+    } else if (status === '??' || status === 'U' || status === '?') {
+      // Untracked file: --no-index exits 1 when a diff exists, so read stdout
+      // directly instead of relying on the exit code.
+      const untracked = await runShell(`git diff --no-index /dev/null "${cleanFile}"`, { cwd: targetDir, timeout: 10000, maxBuffer: 1024 * 1024 * 2 });
+      diff = untracked.stdout.trim() ? untracked.stdout : '';
+    } else {
+      // 1. Working tree diff, 2. cached diff, 3. HEAD diff
+      diff = await gitOut(`git diff -- "${cleanFile}"`, targetDir, 10000)
+        || await gitOut(`git diff --cached -- "${cleanFile}"`, targetDir, 10000)
+        || await gitOut(`git diff HEAD -- "${cleanFile}"`, targetDir, 10000);
+    }
+
+    // 4. If git diff is still empty but new content exists:
+    if (!diff.trim()) {
+      if (oldContent && newContent && oldContent !== newContent) {
+        // Synthesize diff from old and new lines
+        const oldLines = oldContent.split(/\r?\n/);
+        const newLines = newContent.split(/\r?\n/);
+        const diffBody = [
+          ...oldLines.map((l) => `-${l}`),
+          ...newLines.map((l) => `+${l}`),
+        ].join('\n');
+        diff = `--- a/${cleanFile}\n+++ b/${cleanFile}\n@@ -1,${oldLines.length} +1,${newLines.length} @@\n${diffBody}`;
+      } else if (newContent) {
+        const lines = newContent.split(/\r?\n/);
+        const prefix = status === 'A' || status === '??' ? '+' : ' ';
+        const diffBody = lines.map((l) => `${prefix}${l}`).join('\n');
+        diff = `--- a/${cleanFile}\n+++ b/${cleanFile}\n@@ -1,${lines.length} +1,${lines.length} @@\n${diffBody}`;
+      }
+    }
+
+    // Count additions and deletions from diff
+    if (diff) {
+      const diffLines = diff.split('\n');
+      for (const line of diffLines) {
+        if (line.startsWith('+++') || line.startsWith('---') || line.startsWith('@@')) continue;
+        if (line.startsWith('+')) additions++;
+        else if (line.startsWith('-')) deletions++;
+      }
+    }
+
+    return {
+      file: cleanFile,
+      diff: diff || (newContent ? `--- a/${cleanFile}\n+++ b/${cleanFile}\n@@ -1,1 +1,1 @@\n ${newContent.slice(0, 100)}` : 'No differences found'),
+      oldContent,
+      newContent,
+      staged,
+      status,
+      additions,
+      deletions,
+    };
+  } catch (error: any) {
+    return {
+      file: cleanFile,
+      diff: `// Unable to compute diff for ${cleanFile}: ${error?.message || 'Unknown error'}`,
+      oldContent: '',
+      newContent,
+      staged,
+      status: 'M',
+      additions: 0,
+      deletions: 0,
+    };
+  }
+}

package/src/server/lib/fs/git-log.ts

@@ -0,0 +1,174 @@
+import path from 'path';
+import type { GitCommit } from '@/shared/types/git';
+import { SAMPLE_GIT_COMMITS } from '@/client/data/mock/git-commits';
+import { runShell, shellOk } from '@/server/lib/fs/shell';
+
+export function parseGitLogOutput(stdout: string): GitCommit[] {
+  const commits: GitCommit[] = [];
+  const lines = stdout.split('\n');
+  let currentCommit: GitCommit | null = null;
+
+  for (const line of lines) {
+    if (line.startsWith('COMMIT_SPLIT|~|')) {
+      if (currentCommit) {
+        commits.push(currentCommit);
+      }
+      const parts = line.split('|~|');
+      const hash = parts[1] || '';
+      const shortHash = parts[2] || hash.slice(0, 8);
+      const author = parts[3] || 'Unknown';
+      const date = parts[4] || '';
+      const message = parts[5] || '';
+      const refStr = parts[6] || '';
+      const parentStr = parts[7] || '';
+
+      const refs = refStr
+        ? refStr
+            .split(',')
+            .map(r => r.trim())
+            .filter(Boolean)
+        : [];
+      const parents = parentStr
+        ? parentStr
+            .split(/\s+/)
+            .map(p => p.trim())
+            .filter(Boolean)
+        : [];
+
+      currentCommit = {
+        hash,
+        shortHash,
+        author,
+        date,
+        message,
+        refs,
+        parents,
+        files: [],
+      };
+    } else if (currentCommit && line.trim()) {
+      const parts = line.split('\t');
+      if (parts.length >= 3) {
+        const additions = parts[0] === '-' ? 0 : parseInt(parts[0], 10) || 0;
+        const deletions = parts[1] === '-' ? 0 : parseInt(parts[1], 10) || 0;
+        let file = parts[2].trim();
+        if (file.startsWith('"') && file.endsWith('"')) {
+          try { file = JSON.parse(file); } catch {}
+        }
+        let status = 'M';
+        if (file.includes(' => ') || file.includes('=>')) {
+          status = 'R';
+        } else if (deletions > 0 && additions === 0) {
+          status = 'D';
+        } else if (additions > 0 && deletions === 0) {
+          status = 'A';
+        }
+        currentCommit.files?.push({
+          file,
+          status,
+          additions,
+          deletions,
+        });
+      }
+    }
+  }
+
+  if (currentCommit) {
+    commits.push(currentCommit);
+  }
+
+  return commits.length > 0 ? commits : SAMPLE_GIT_COMMITS;
+}
+
+export interface FetchCommitsResult {
+  commits: GitCommit[];
+  hasMore: boolean;
+  total?: number;
+}
+
+export async function fetchGitCommits(
+  targetDir: string,
+  limit: number = 50,
+  skip: number = 0
+): Promise<FetchCommitsResult> {
+  try {
+    let total = 0;
+    try {
+      const countOut = await runShell('git rev-list --count HEAD', { cwd: targetDir, timeout: 5000 });
+      if (shellOk(countOut)) total = parseInt(countOut.stdout.trim(), 10) || 0;
+    } catch {
+      total = 0;
+    }
+
+    const result = await runShell(
+      `git log -n ${limit} --skip=${skip} --numstat --date-order --pretty=format:"COMMIT_SPLIT|~|%H|~|%h|~|%an|~|%ad|~|%s|~|%D|~|%p" --date=format:"%b %d, %Y, %I:%M %p"`,
+      { cwd: targetDir, timeout: 15000 }
+    );
+    if (!shellOk(result)) throw new Error(result.stderr || 'git log failed');
+    const commits = parseGitLogOutput(result.stdout);
+    const hasMore = total > 0 ? skip + commits.length < total : commits.length === limit;
+    return { commits, hasMore, total };
+  } catch {
+    const paged = SAMPLE_GIT_COMMITS.slice(skip, skip + limit);
+    return {
+      commits: paged,
+      hasMore: skip + paged.length < SAMPLE_GIT_COMMITS.length,
+      total: SAMPLE_GIT_COMMITS.length,
+    };
+  }
+}
+
+export async function fetchFileDiff(targetDir: string, hash: string, file: string): Promise<string> {
+  let cleanFile = file.replace(/^\.\//, '').trim();
+
+  // If the file in numstat was a rename (e.g. "path/{old.ts => new.ts}" or "old.ts => new.ts")
+  if (cleanFile.includes(' => ')) {
+    if (cleanFile.includes('{') && cleanFile.includes('}')) {
+      cleanFile = cleanFile.replace(/\{.*? => (.*?)\}/, '$1');
+    } else {
+      cleanFile = cleanFile.split(' => ')[1].trim();
+    }
+  }
+
+  // 1. Try standard git show with pretty format patch
+  const showPatch = await runShell(`git show --pretty=format:"" --patch "${hash}" -- "${cleanFile}"`, { cwd: targetDir, timeout: 10000 });
+  if (showPatch.stdout.trim()) return showPatch.stdout.trim();
+
+  // 2. Try git diff-tree with root support
+  const diffTree = await runShell(`git diff-tree -r -p --root "${hash}" -- "${cleanFile}"`, { cwd: targetDir, timeout: 10000 });
+  if (diffTree.stdout.trim()) return diffTree.stdout.trim();
+
+  // 3. If it is an added file or root commit, show file content directly from git blob
+  const showBlob = await runShell(`git show "${hash}:${cleanFile}"`, { cwd: targetDir, timeout: 10000 });
+  if (showBlob.stdout.length > 0) {
+    const lines = showBlob.stdout.split('\n');
+    const diffLines = lines.map((l) => `+${l}`).join('\n');
+    return `@@ -0,0 +1,${lines.length} @@\n${diffLines}`;
+  }
+
+  // 4. Try previous parent blob for deleted file
+  const showParent = await runShell(`git show "${hash}^:${cleanFile}"`, { cwd: targetDir, timeout: 10000 });
+  if (showParent.stdout.length > 0) {
+    const lines = showParent.stdout.split('\n');
+    const diffLines = lines.map((l) => `-${l}`).join('\n');
+    return `@@ -1,${lines.length} +0,0 @@\n${diffLines}`;
+  }
+
+  // 5. Try reading directly from target filesystem if available
+  try {
+    const diskFile = Bun.file(path.join(targetDir, cleanFile));
+    if ((await diskFile.exists()) && !(await diskFile.stat()).isDirectory()) {
+      const content = await diskFile.text();
+      const lines = content.split('\n');
+      const diffLines = lines.map((l) => `+${l}`).join('\n');
+      return `@@ -0,0 +1,${lines.length} @@\n${diffLines}`;
+    }
+  } catch {}
+
+  // 6. Fall back to mock sample data if exists
+  const sample = SAMPLE_GIT_COMMITS.find(c => c.hash === hash || c.shortHash === hash || hash.startsWith(c.shortHash));
+  const sampleFile = sample?.files?.find(f => f.file === file || f.file === cleanFile);
+  if (sampleFile?.diff) return sampleFile.diff;
+
+  // 7. Generate readable sample diff
+  return `@@ -0,0 +1,6 @@\n+// File: ${cleanFile}\n+// Commit: ${hash.slice(0, 8)}\n+// Changes recorded for this commit\n+export const status = "synced";\n+console.log("Commit updated: ${cleanFile}");`;
+}

package/src/server/lib/fs/repo-scope.ts

@@ -0,0 +1,14 @@
+import path from 'path';
+
+export async function scopeToRepo(baseDir: string, repo: string | null | undefined): Promise<string> {
+  if (!repo || repo === '.') return baseDir;
+  const scopeDir = path.resolve(baseDir, repo);
+  if (scopeDir !== baseDir && !scopeDir.startsWith(baseDir + path.sep)) {
+    throw new Error('Invalid repo path');
+  }
+  const stat = await Bun.file(scopeDir).stat().catch(() => null);
+  if (!stat?.isDirectory()) {
+    throw new Error('Invalid repo path');
+  }
+  return scopeDir;
+}

package/src/server/lib/fs/root.ts

@@ -0,0 +1,77 @@
+/**
+ * Server-side helper for resolving the "scoped root" the right-panel developer
+ * tools (Files / Search / Git / Terminal) operate on.
+ *
+ * A session row belongs to a workspace folder; when that folder is bound to an
+ * oh-my-pi project (project_path), selecting one of its sessions should make
+ * every right panel work inside that real project directory instead of the
+ * ompchamber app directory. This module keeps that opt-in capability safe:
+ * arbitrary client paths are rejected — a root is only honored when it is the
+ * app root, a directory below it, or an exact registered workspace project
+ * path from the SQLite database.
+ */
+
+import path from 'path';
+import { getDb } from '@/server/db.server';
+import { pathExists } from '@/server/lib/omp/core/paths';
+
+const APP_ROOT = process.cwd();
+
+/** True when `target` is `root` itself or a path nested beneath it. */
+export function isWithinRoot(root: string, target: string): boolean {
+  return target === root || target.startsWith(root + path.sep);
+}
+
+/** Resolve `rel` under `root`; null when the result escapes the root. */
+export function resolveWithinRoot(root: string, rel: string): string | null {
+  const target = path.resolve(root, rel);
+  return isWithinRoot(root, target) ? target : null;
+}
+
+/**
+ * Default browsing root when no session-bound project is active. Mock/demo
+ * mode browses the bundled `examples` tree; real mode browses the app root.
+ */
+export async function getDefaultFsRoot(mock: boolean): Promise<string> {
+  if (mock) {
+    const examplesDir = path.join(APP_ROOT, 'examples');
+    if (await pathExists(examplesDir)) return examplesDir;
+  }
+  return APP_ROOT;
+}
+
+/**
+ * Resolve a client-supplied `root` (query param or form field) to a directory
+ * the server is allowed to operate on.
+ *
+ * Returns `fallback` when `rawRoot` is missing, does not exist, or is not on
+ * the allow-list (app root / subpath / registered project_path), so existing
+ * callers keep their previous behavior for unscoped requests.
+ */
+export async function resolveRoot(
+  rawRoot: string | null | undefined,
+  fallback: string
+): Promise<string> {
+  if (!rawRoot || !rawRoot.trim()) return fallback;
+
+  const resolved = path.resolve(rawRoot.trim());
+
+  // Fast path: the app root and anything beneath it are always allowed.
+  if (resolved === APP_ROOT || resolved.startsWith(APP_ROOT + path.sep)) {
+    return (await pathExists(resolved)) ? resolved : fallback;
+  }
+
+  // Registered workspaces are user-opted project roots — allow exact matches.
+  try {
+    const db = await getDb();
+    const row = await db.get(
+      'SELECT project_path FROM workspace_folders WHERE project_path IS NOT NULL AND project_path = ? LIMIT 1',
+      [resolved]
+    );
+    if (row && (await pathExists(resolved))) return resolved;
+  } catch {
+    // Database unavailable — fall through to the safe fallback.
+  }
+
+  return fallback;
+}