@pi-chamber/web 0.1.8

package/server/lib/pi/session-daemon/supervisor.test.js

@@ -0,0 +1,212 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { mkdtemp, mkdir, readFile, stat, utimes, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { getPiSessionDirectory } from './session-jsonl.js';
+import { createPiSessionDaemonSupervisor } from './supervisor.js';
+
+const waitForExit = async (pid) => {
+  for (let attempt = 0; attempt < 50; attempt += 1) {
+    try {
+      process.kill(pid, 0);
+    } catch (error) {
+      if (error?.code === 'ESRCH') return;
+      throw error;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 20));
+  }
+  throw new Error('The daemon process did not exit.');
+};
+
+describe('Pi session daemon supervisor', () => {
+  let supervisor;
+
+  afterEach(async () => {
+    await supervisor?.stop().catch(() => {});
+    supervisor = undefined;
+  });
+
+  it('recovers a forced daemon crash during the next health probe', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'pichamber-pi-supervisor-'));
+    const cwd = join(root, 'project');
+    const agentDir = join(root, 'agent');
+    await Promise.all([mkdir(cwd), mkdir(agentDir)]);
+    const env = {
+      ...process.env,
+      PI_OFFLINE: '1',
+      PICHAMBER_DATA_DIR: join(root, 'data'),
+      PICHAMBER_PI_AGENT_DIR: agentDir,
+      XDG_RUNTIME_DIR: join(root, 'runtime'),
+    };
+
+    supervisor = createPiSessionDaemonSupervisor({ env, cwd });
+    await supervisor.start();
+    const state = JSON.parse(await readFile(supervisor.paths.stateFile, 'utf8'));
+    process.kill(state.pid, 'SIGKILL');
+    await waitForExit(state.pid);
+
+    await expect(supervisor.health()).resolves.toMatchObject({ state: 'ready' });
+  }, 20_000);
+
+  it('reports malformed Pi session JSONL as a stable startup failure', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'pichamber-pi-supervisor-'));
+    const cwd = join(root, 'project');
+    const agentDir = join(root, 'agent');
+    await Promise.all([mkdir(cwd), mkdir(agentDir)]);
+    const sessionDirectory = getPiSessionDirectory({ cwd, agentDir });
+    await mkdir(sessionDirectory, { recursive: true });
+    await writeFile(join(sessionDirectory, 'corrupt.jsonl'), '{"type":"session"}\nnot-json\n');
+    const env = {
+      ...process.env,
+      PI_OFFLINE: '1',
+      PICHAMBER_DATA_DIR: join(root, 'data'),
+      PICHAMBER_PI_AGENT_DIR: agentDir,
+      XDG_RUNTIME_DIR: join(root, 'runtime'),
+    };
+
+    supervisor = createPiSessionDaemonSupervisor({ env, cwd });
+    await expect(supervisor.start()).rejects.toMatchObject({ code: 'MALFORMED_SESSION_JSONL' });
+    await expect(supervisor.health()).resolves.toMatchObject({
+      state: 'unavailable',
+      error: { code: 'MALFORMED_SESSION_JSONL' },
+    });
+  }, 20_000);
+
+  it('starts, reuses, health-checks, and stops a private daemon without exposing its credential', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'pichamber-pi-supervisor-'));
+    const cwd = join(root, 'project');
+    const agentDir = join(root, 'agent');
+    await Promise.all([mkdir(cwd), mkdir(agentDir)]);
+    const env = {
+      ...process.env,
+      PI_OFFLINE: '1',
+      PICHAMBER_DATA_DIR: join(root, 'data'),
+      PICHAMBER_PI_AGENT_DIR: agentDir,
+      XDG_RUNTIME_DIR: join(root, 'runtime'),
+    };
+
+    supervisor = createPiSessionDaemonSupervisor({ env, cwd });
+    await expect(supervisor.start()).resolves.toMatchObject({ state: 'ready', reused: false, protocolVersion: 1 });
+    await expect(supervisor.start()).resolves.toMatchObject({ state: 'ready', reused: true, protocolVersion: 1 });
+    await expect(supervisor.health()).resolves.toEqual({
+      state: 'ready',
+      protocolVersion: 1,
+      capabilities: expect.arrayContaining(['projects.list', 'projects.select', 'sessions.list', 'sessions.create', 'sessions.open', 'sessions.rename', 'sessions.delete', 'sessions.tree', 'sessions.navigate', 'sessions.fork', 'sessions.clone', 'sessions.prompt', 'sessions.steer', 'sessions.followUp', 'sessions.abort', 'sessions.setModel', 'sessions.setThinking', 'sessions.compact', 'providers.list', 'providers.config.get', 'providers.models.set', 'providers.status', 'providers.login', 'providers.login.respond', 'providers.login.status', 'providers.logout', 'settings.get', 'settings.set', 'resources.list', 'resources.update', 'resources.prompts.create', 'resources.prompts.delete']),
+    });
+    await expect(supervisor.request('sessions.list')).resolves.toMatchObject({ sessions: expect.any(Array) });
+
+    const credential = await readFile(supervisor.paths.credentialFile, 'utf8');
+    expect(credential.trim()).toHaveLength(64);
+    if (process.platform !== 'win32') {
+      expect((await stat(supervisor.paths.credentialFile)).mode & 0o777).toBe(0o600);
+    }
+    expect(JSON.stringify(await supervisor.health())).not.toContain(credential.trim());
+
+    await expect(supervisor.stop()).resolves.toEqual({ state: 'stopped' });
+    await expect(supervisor.health()).resolves.toMatchObject({
+      state: 'unavailable',
+      error: { code: 'DAEMON_UNAVAILABLE' },
+    });
+  }, 20_000);
+
+  it('spawns the daemon as Node when the parent process is Electron', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'pichamber-pi-supervisor-electron-'));
+    const cwd = join(root, 'project');
+    const agentDir = join(root, 'agent');
+    await Promise.all([mkdir(cwd), mkdir(agentDir)]);
+    const env = {
+      ...process.env,
+      PI_OFFLINE: '1',
+      PICHAMBER_DATA_DIR: join(root, 'data'),
+      PICHAMBER_PI_AGENT_DIR: agentDir,
+      XDG_RUNTIME_DIR: join(root, 'runtime'),
+    };
+    let spawnEnv;
+    supervisor = createPiSessionDaemonSupervisor({
+      env,
+      cwd,
+      processLike: {
+        versions: { electron: '41.2.1' },
+        execPath: process.execPath,
+        pid: process.pid,
+        kill() {
+          const error = new Error('ESRCH');
+          error.code = 'ESRCH';
+          throw error;
+        },
+      },
+      spawn: (_command, _args, options) => {
+        spawnEnv = options.env;
+        return { pid: 1, unref() {} };
+      },
+      wait: async () => {},
+      startupTimeoutMs: 50,
+      daemonReadyTimeoutMs: 50,
+      request: async () => {
+        const error = new Error('refused');
+        error.code = 'DAEMON_CONNECTION_REFUSED';
+        throw error;
+      },
+    });
+
+    await expect(supervisor.start()).rejects.toMatchObject({ code: 'DAEMON_START_TIMEOUT' });
+    expect(spawnEnv?.ELECTRON_RUN_AS_NODE).toBe('1');
+  });
+
+  it('uses a per-user Windows named pipe instead of a filesystem socket', () => {
+    const windowsSupervisor = createPiSessionDaemonSupervisor({
+      env: {
+        PICHAMBER_DATA_DIR: join(tmpdir(), 'pichamber-win-data'),
+        PICHAMBER_PI_AGENT_DIR: join(tmpdir(), 'pichamber-win-agent'),
+      },
+      cwd: join(tmpdir(), 'pichamber-win-project'),
+      platform: 'win32',
+    });
+    expect(windowsSupervisor.paths.endpoint).toMatch(/^\\\\\.\\pipe\\pichamber-pi-session-daemon-[0-9a-f]{16}$/);
+  });
+
+  it('recovers from a leftover empty daemon lock instead of failing as unavailable', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'pichamber-pi-supervisor-empty-lock-'));
+    const cwd = join(root, 'project');
+    const agentDir = join(root, 'agent');
+    const dataDir = join(root, 'data');
+    await Promise.all([mkdir(cwd), mkdir(agentDir), mkdir(join(dataDir, 'pi'), { recursive: true })]);
+    const lockFile = join(dataDir, 'pi', 'session-daemon.lock');
+    await writeFile(lockFile, '');
+    const past = new Date(Date.now() - 1_000);
+    await utimes(lockFile, past, past);
+    const env = {
+      ...process.env,
+      PI_OFFLINE: '1',
+      PICHAMBER_DATA_DIR: dataDir,
+      PICHAMBER_PI_AGENT_DIR: agentDir,
+      XDG_RUNTIME_DIR: join(root, 'runtime'),
+    };
+
+    supervisor = createPiSessionDaemonSupervisor({ env, cwd });
+    await expect(supervisor.start()).resolves.toMatchObject({ state: 'ready', reused: false });
+  }, 20_000);
+
+  it('recovers from a malformed daemon lock instead of failing as unavailable', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'pichamber-pi-supervisor-bad-lock-'));
+    const cwd = join(root, 'project');
+    const agentDir = join(root, 'agent');
+    const dataDir = join(root, 'data');
+    await Promise.all([mkdir(cwd), mkdir(agentDir), mkdir(join(dataDir, 'pi'), { recursive: true })]);
+    const lockFile = join(dataDir, 'pi', 'session-daemon.lock');
+    await writeFile(lockFile, '{');
+    const past = new Date(Date.now() - 1_000);
+    await utimes(lockFile, past, past);
+    const env = {
+      ...process.env,
+      PI_OFFLINE: '1',
+      PICHAMBER_DATA_DIR: dataDir,
+      PICHAMBER_PI_AGENT_DIR: agentDir,
+      XDG_RUNTIME_DIR: join(root, 'runtime'),
+    };
+
+    supervisor = createPiSessionDaemonSupervisor({ env, cwd });
+    await expect(supervisor.start()).resolves.toMatchObject({ state: 'ready', reused: false });
+  }, 20_000);
+});

package/server/lib/pi/session-folders-store.js

@@ -0,0 +1,74 @@
+import { randomUUID } from 'node:crypto';
+import { chmod, mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+
+import { resolvePiChamberDataDir } from '../pichamber-data-dir.js';
+
+const MAX_FILE_BYTES = 2 * 1024 * 1024;
+const MAX_KEY_LENGTH = 2_048;
+const MAX_NAME_LENGTH = 500;
+const FORBIDDEN_KEYS = new Set(['__proto__', 'prototype', 'constructor']);
+
+const invalid = () => new Error('SESSION_FOLDERS_INVALID');
+const isRecord = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const validString = (value, max = MAX_KEY_LENGTH) => typeof value === 'string' && value.length > 0 && value.length <= max;
+
+const validateSnapshot = (value) => {
+  if (!isRecord(value) || value.version !== 1 || !isRecord(value.foldersMap)
+    || !Array.isArray(value.collapsedFolderIds) || !Number.isFinite(value.updatedAt) || value.updatedAt < 0) throw invalid();
+
+  for (const [scopeKey, folders] of Object.entries(value.foldersMap)) {
+    if (!validString(scopeKey) || FORBIDDEN_KEYS.has(scopeKey) || !Array.isArray(folders)) throw invalid();
+    for (const folder of folders) {
+      if (!isRecord(folder) || !validString(folder.id) || !validString(folder.name, MAX_NAME_LENGTH)
+        || !Array.isArray(folder.sessionIds) || !Number.isFinite(folder.createdAt)
+        || (folder.parentId !== undefined && folder.parentId !== null && !validString(folder.parentId))) throw invalid();
+      if (folder.sessionIds.some((sessionId) => !validString(sessionId))) throw invalid();
+    }
+  }
+  if (value.collapsedFolderIds.some((folderId) => !validString(folderId))) throw invalid();
+
+  const snapshot = {
+    version: 1,
+    foldersMap: value.foldersMap,
+    collapsedFolderIds: value.collapsedFolderIds,
+    updatedAt: value.updatedAt,
+  };
+  if (Buffer.byteLength(JSON.stringify(snapshot)) > MAX_FILE_BYTES) throw invalid();
+  return snapshot;
+};
+
+export const createPiSessionFoldersStore = ({
+  file = join(resolvePiChamberDataDir(), 'pi', 'session-folders.json'),
+  fs = { chmod, mkdir, readFile, rename, writeFile },
+} = {}) => {
+  let mutation = Promise.resolve();
+
+  const read = async () => {
+    try {
+      const raw = await fs.readFile(file, 'utf8');
+      if (Buffer.byteLength(raw) > MAX_FILE_BYTES) throw invalid();
+      return { exists: true, ...validateSnapshot(JSON.parse(raw)) };
+    } catch (error) {
+      if (error?.code === 'ENOENT') return { exists: false };
+      throw invalid();
+    }
+  };
+
+  const write = async (value) => {
+    const snapshot = validateSnapshot(value);
+    const operation = mutation.then(async () => {
+      const parent = dirname(file);
+      await fs.mkdir(parent, { recursive: true, mode: 0o700 });
+      const temporary = `${file}.tmp-${process.pid}-${randomUUID()}`;
+      await fs.writeFile(temporary, `${JSON.stringify(snapshot, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+      await fs.rename(temporary, file);
+      if (process.platform !== 'win32') await fs.chmod(file, 0o600);
+      return { exists: true, ...snapshot };
+    });
+    mutation = operation.catch(() => {});
+    return operation;
+  };
+
+  return { file, read, write };
+};

package/server/lib/pi/session-folders-store.test.js

@@ -0,0 +1,45 @@
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { createPiSessionFoldersStore } from './session-folders-store.js';
+
+const directories = [];
+
+afterEach(async () => {
+  await Promise.all(directories.splice(0).map((directory) => rm(directory, { recursive: true, force: true })));
+});
+
+const snapshot = {
+  version: 1,
+  foldersMap: {
+    '/workspace': [{ id: 'folder-1', name: 'Current', sessionIds: ['session-1'], createdAt: 1, parentId: null }],
+  },
+  collapsedFolderIds: ['folder-1'],
+  updatedAt: 2,
+};
+
+describe('Pi session folders store', () => {
+  it('distinguishes a missing snapshot and atomically round-trips a valid snapshot', async () => {
+    const directory = await mkdtemp(join(tmpdir(), 'pichamber-session-folders-'));
+    directories.push(directory);
+    const file = join(directory, 'pi', 'session-folders.json');
+    const store = createPiSessionFoldersStore({ file });
+
+    await expect(store.read()).resolves.toEqual({ exists: false });
+    await expect(store.write(snapshot)).resolves.toEqual({ exists: true, ...snapshot });
+    await expect(store.read()).resolves.toEqual({ exists: true, ...snapshot });
+    expect(JSON.parse(await readFile(file, 'utf8'))).toEqual(snapshot);
+  });
+
+  it('rejects malformed snapshots without replacing valid data', async () => {
+    const directory = await mkdtemp(join(tmpdir(), 'pichamber-session-folders-'));
+    directories.push(directory);
+    const store = createPiSessionFoldersStore({ file: join(directory, 'session-folders.json') });
+    await store.write(snapshot);
+
+    await expect(store.write({ ...snapshot, foldersMap: { '/workspace': [{ id: '', name: 'bad', sessionIds: [], createdAt: 1 }] } })).rejects.toThrow('SESSION_FOLDERS_INVALID');
+    await expect(store.read()).resolves.toEqual({ exists: true, ...snapshot });
+  });
+});

package/server/lib/pi/session-lifecycle.integration.test.js

@@ -0,0 +1,197 @@
+import { afterEach, describe, expect, it } from 'bun:test';
+import { createConnection } from 'node:net';
+import { mkdir, mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createSessionDaemon } from './session-daemon/session-daemon.js';
+
+const credential = 'integration-secret';
+
+const connectClient = (endpoint) => {
+  const socket = createConnection({ path: endpoint });
+  let buffer = '';
+  const waiters = [];
+
+  const publish = (frame) => {
+    for (let index = 0; index < waiters.length; index += 1) {
+      if (waiters[index].predicate(frame)) {
+        const [match] = waiters.splice(index, 1);
+        match.resolve(frame);
+        return;
+      }
+    }
+  };
+
+  socket.on('data', (chunk) => {
+    buffer += chunk.toString('utf8');
+    for (;;) {
+      const newline = buffer.indexOf('\n');
+      if (newline === -1) break;
+      const line = buffer.slice(0, newline).trim();
+      buffer = buffer.slice(newline + 1);
+      if (line) publish(JSON.parse(line));
+    }
+  });
+
+  socket.on('close', () => {
+    for (const waiter of waiters.splice(0)) waiter.reject(new Error('Daemon connection closed'));
+  });
+
+  const next = (predicate, timeoutMs = 2_000) => new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      const index = waiters.findIndex((waiter) => waiter.resolve === resolve);
+      if (index !== -1) waiters.splice(index, 1);
+      reject(new Error('Timed out waiting for daemon frame'));
+    }, timeoutMs);
+    waiters.push({
+      predicate,
+      resolve: (frame) => {
+        clearTimeout(timer);
+        resolve(frame);
+      },
+      reject,
+    });
+  });
+
+  return {
+    socket,
+    next,
+    async authenticate(value = credential, { sessionId, fromSequence } = {}) {
+      await new Promise((resolve, reject) => {
+        socket.once('connect', resolve);
+        socket.once('error', reject);
+      });
+      const authPromise = next((frame) => frame.event === 'session.snapshot' || frame.kind === 'error');
+      socket.write(`${JSON.stringify({
+        protocolVersion: 1,
+        kind: 'authenticate',
+        credential: value,
+        ...(sessionId ? { sessionId } : {}),
+        ...(fromSequence !== undefined ? { fromSequence } : {}),
+      })}\n`);
+      return authPromise;
+    },
+    async request(command, payload) {
+      const requestId = `req-${Math.random()}`;
+      const responsePromise = next((frame) => frame.requestId === requestId);
+      socket.write(`${JSON.stringify({
+        protocolVersion: 1,
+        kind: 'request',
+        requestId,
+        command,
+        ...(payload !== undefined ? { payload } : {}),
+      })}\n`);
+      return responsePromise;
+    },
+    close: () => new Promise((resolve) => {
+      socket.once('close', () => resolve());
+      socket.destroy();
+    }),
+  };
+};
+
+describe('Pi session lifecycle multi-directory integration test', () => {
+  let tempRoot;
+  let daemon;
+
+  afterEach(async () => {
+    if (daemon) {
+      await daemon.stop().catch(() => {});
+      daemon = null;
+    }
+    if (tempRoot) {
+      await rm(tempRoot, { recursive: true, force: true }).catch(() => {});
+      tempRoot = null;
+    }
+  });
+
+  it('handles multi-directory isolation, deterministic first-send titling, and clean deletion without unsolicited sessions', async () => {
+    const previousOffline = process.env.PI_OFFLINE;
+    process.env.PI_OFFLINE = '1';
+
+    try {
+      tempRoot = await mkdtemp(join(tmpdir(), 'pichamber-integration-'));
+      const dirA = join(tempRoot, 'project-a');
+      const dirB = join(tempRoot, 'project-b');
+      const agentDir = join(tempRoot, 'agent');
+      const endpoint = process.platform === 'win32'
+        ? `\\\\.\\pipe\\pichamber-integration-${process.pid}`
+        : join(tempRoot, 'daemon.sock');
+
+      await Promise.all([
+        mkdir(dirA, { recursive: true }),
+        mkdir(dirB, { recursive: true }),
+        mkdir(agentDir, { recursive: true }),
+      ]);
+
+      daemon = createSessionDaemon({
+        endpoint,
+        credential,
+        cwd: dirA,
+        agentDir,
+      });
+      await daemon.start();
+
+      const client = connectClient(endpoint);
+      const snapshot = await client.authenticate();
+      expect(snapshot.payload.directory).toBe(dirA);
+
+      // 1. Projects list should show known directory
+      const projects = await client.request('projects.list');
+      expect(projects.result.projects).toEqual(expect.arrayContaining([
+        expect.objectContaining({ directory: dirA }),
+      ]));
+
+      // 2. Initial sessions list in dirA should be empty (no unsolicited session generated on startup)
+      const initialListA = await client.request('sessions.list', { directory: dirA });
+      expect(initialListA.result.sessions).toEqual([]);
+
+      // 3. Create a session in dirA without title
+      const createdA = await client.request('sessions.create', { cwd: dirA });
+      const sessionAId = createdA.result.session.id;
+      expect(typeof sessionAId).toBe('string');
+      expect(createdA.result.session.directory).toBe(dirA);
+
+      // 4. Create a session in dirB with explicit title
+      const createdB = await client.request('sessions.create', { cwd: dirB, title: 'Project B Workflow' });
+      const sessionBId = createdB.result.session.id;
+      expect(typeof sessionBId).toBe('string');
+      expect(createdB.result.session.directory).toBe(dirB);
+      expect(createdB.result.session.title).toBe('Project B Workflow');
+
+      // 5. Multi-directory isolation: dirA lists only session A; dirB lists only session B
+      const listA = await client.request('sessions.list', { directory: dirA });
+      expect(listA.result.sessions.map((s) => s.session.id)).toEqual([sessionAId]);
+
+      const listB = await client.request('sessions.list', { directory: dirB });
+      expect(listB.result.sessions.map((s) => s.session.id)).toEqual([sessionBId]);
+      expect(listB.result.sessions[0].session.title).toBe('Project B Workflow');
+
+      // 6. Rename session in dirA
+      await client.request('sessions.rename', {
+        directory: dirA,
+        sessionId: sessionAId,
+        title: 'Renamed Project A Session',
+      });
+      const updatedListA = await client.request('sessions.list', { directory: dirA });
+      expect(updatedListA.result.sessions[0].session.title).toBe('Renamed Project A Session');
+
+      // 7. Delete session in dirA and verify it leaves dirA empty without generating a replacement
+      await client.request('sessions.delete', {
+        directory: dirA,
+        sessionId: sessionAId,
+      });
+      const afterDeleteListA = await client.request('sessions.list', { directory: dirA });
+      expect(afterDeleteListA.result.sessions).toEqual([]);
+
+      // 8. Session B in dirB remains unaffected
+      const intactListB = await client.request('sessions.list', { directory: dirB });
+      expect(intactListB.result.sessions.map((s) => s.session.id)).toEqual([sessionBId]);
+
+      await client.close();
+    } finally {
+      if (previousOffline === undefined) delete process.env.PI_OFFLINE;
+      else process.env.PI_OFFLINE = previousOffline;
+    }
+  });
+});

package/server/lib/pi/settings-store.js

@@ -0,0 +1,133 @@
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+
+import { resolvePiChamberDataDir } from '../pichamber-data-dir.js';
+import { isPiThinkingLevel } from './thinking-levels.js';
+
+const invalidSettings = () => {
+  const error = new Error('PiChamber Pi settings are invalid.');
+  error.code = 'PI_SETTINGS_INVALID';
+  return error;
+};
+
+const normalizeModel = (value) => {
+  if (value === undefined || value === null) return undefined;
+  if (!value || typeof value !== 'object' || typeof value.providerId !== 'string' || typeof value.modelId !== 'string'
+    || value.providerId.trim().length === 0 || value.modelId.trim().length === 0
+    || value.providerId.length > 256 || value.modelId.length > 512) {
+    throw invalidSettings();
+  }
+  return { providerId: value.providerId.trim(), modelId: value.modelId.trim() };
+};
+
+const parseThinkingModelKey = (value) => {
+  if (typeof value !== 'string' || value.length === 0 || value.length > 768) return undefined;
+  const separator = value.indexOf('/');
+  if (separator <= 0 || separator >= value.length - 1) return undefined;
+  const providerId = value.slice(0, separator).trim();
+  const modelId = value.slice(separator + 1).trim();
+  if (!providerId || !modelId || providerId.length > 256 || modelId.length > 512) return undefined;
+  return `${providerId}/${modelId}`;
+};
+
+const normalizeThinkingByModel = (value) => {
+  if (value === undefined || value === null) return {};
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw invalidSettings();
+  const entries = Object.entries(value);
+  if (entries.length > 256) throw invalidSettings();
+  const result = {};
+  for (const [rawKey, level] of entries) {
+    if (level === null || level === '') continue;
+    const key = parseThinkingModelKey(rawKey);
+    if (!key || !isPiThinkingLevel(level)) throw invalidSettings();
+    result[key] = level;
+  }
+  return result;
+};
+
+const mergeThinkingByModel = (current, incoming) => {
+  if (incoming === null) return {};
+  if (incoming === undefined) return { ...current };
+  if (!incoming || typeof incoming !== 'object' || Array.isArray(incoming)) throw invalidSettings();
+  const next = { ...current };
+  for (const [rawKey, level] of Object.entries(incoming)) {
+    const key = parseThinkingModelKey(rawKey);
+    if (!key) throw invalidSettings();
+    if (level === null || level === '') {
+      delete next[key];
+      continue;
+    }
+    if (!isPiThinkingLevel(level)) throw invalidSettings();
+    next[key] = level;
+  }
+  return next;
+};
+
+const normalize = (value) => {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw invalidSettings();
+  const model = normalizeModel(value.defaultModel);
+  const smallModel = normalizeModel(value.smallModel);
+  const walkthroughModel = normalizeModel(value.walkthroughModel);
+  const thinking = value.defaultThinking === null ? undefined : value.defaultThinking;
+  if (thinking !== undefined && !isPiThinkingLevel(thinking)) throw invalidSettings();
+  const thinkingByModel = normalizeThinkingByModel(value.defaultThinkingByModel);
+  let fallbackThinking = thinking;
+  if (fallbackThinking && model) {
+    const key = `${model.providerId}/${model.modelId}`;
+    if (!thinkingByModel[key]) thinkingByModel[key] = fallbackThinking;
+    fallbackThinking = undefined;
+  }
+  return {
+    version: 1,
+    ...(model ? { defaultModel: model } : {}),
+    ...(smallModel ? { smallModel } : {}),
+    ...(walkthroughModel ? { walkthroughModel } : {}),
+    ...(Object.keys(thinkingByModel).length > 0 ? { defaultThinkingByModel: thinkingByModel } : {}),
+    ...(fallbackThinking ? { defaultThinking: fallbackThinking } : {}),
+  };
+};
+
+/**
+ * PiChamber-owned new-session defaults. This is intentionally separate from
+ * Pi's settings.json: Pi remains authoritative when no PiChamber override is
+ * configured, and credentials never enter this sidecar.
+ */
+export const createPiSettingsStore = ({ file = join(resolvePiChamberDataDir(), 'pi', 'settings.json') } = {}) => {
+  let writeChain = Promise.resolve();
+
+  const read = async () => {
+    try {
+      return normalize(JSON.parse(await readFile(file, 'utf8')));
+    } catch (error) {
+      if (error?.code === 'ENOENT') return { version: 1 };
+      if (error?.code === 'PI_SETTINGS_INVALID') throw error;
+      throw invalidSettings();
+    }
+  };
+
+  const update = async (patch) => {
+    if (!patch || typeof patch !== 'object' || Array.isArray(patch)) throw invalidSettings();
+    const operation = writeChain.then(async () => {
+      const current = await read();
+      const next = normalize({
+        ...current,
+        ...(Object.hasOwn(patch, 'defaultModel') ? { defaultModel: patch.defaultModel } : {}),
+        ...(Object.hasOwn(patch, 'defaultThinking') ? { defaultThinking: patch.defaultThinking } : {}),
+        ...(Object.hasOwn(patch, 'smallModel') ? { smallModel: patch.smallModel } : {}),
+        ...(Object.hasOwn(patch, 'walkthroughModel') ? { walkthroughModel: patch.walkthroughModel } : {}),
+        defaultThinkingByModel: Object.hasOwn(patch, 'defaultThinkingByModel')
+          ? mergeThinkingByModel(current.defaultThinkingByModel ?? {}, patch.defaultThinkingByModel)
+          : (current.defaultThinkingByModel ?? {}),
+      });
+      await mkdir(dirname(file), { recursive: true, mode: 0o700 });
+      const temporary = `${file}.tmp`;
+      await writeFile(temporary, JSON.stringify(next), { mode: 0o600 });
+      await rename(temporary, file);
+      return next;
+    });
+    writeChain = operation.catch(() => {});
+    return operation;
+  };
+
+  return { read, update };
+};