@chatpanel/gateway 0.6.76 → 0.6.78

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chatpanel/gateway",
-  "version": "0.6.76",
+  "version": "0.6.78",
   "description": "Local privacy gateway \u2014 redacts PII out of OpenAI/Anthropic API traffic before it reaches a model, then restores it in the reply. Point opencode, codex, aider, Claude Code, etc. at it.",
   "type": "module",
   "bin": {

package/src/prefs-store.js

@@ -0,0 +1,149 @@
+// CLIENT PREFERENCES — the settings every ChatPanel client shares, held here because the
+// gateway is the one address the extension and the desktop both have.
+//
+// A document of SECTIONS (the MCP server list, the skills, the search engines — see
+// @chatpanel/events/client-prefs.js), each stamped with when it was last written. A client
+// pushes the sections it changed with its own stamps; the store keeps the newer stamp per
+// section and tells the pusher which of its sections lost, so it can take the other side's
+// copy. Per-section last-writer-wins: a section is one screen a person edits, and merging two
+// edits of one list key by key would make a list neither of them made.
+//
+// ENCRYPTED AT REST with the same device key as memory and history — an MCP server entry can
+// carry an Authorization header, and this file must not be the plaintext copy of it.
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, renameSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import os from 'node:os';
+import { randomBytes, createCipheriv, createDecipheriv } from 'node:crypto';
+
+const DIR = join(os.homedir(), '.chatpanel');
+const STORE_PATH = process.env.CHATPANEL_PREFS_STORE || join(DIR, 'prefs-store.enc');
+const KEY_PATH = process.env.CHATPANEL_HISTORY_KEY || join(DIR, 'history-key');
+
+/** A section id is a short word; anything else is refused before it is stored. */
+const SECTION_ID_RE = /^[a-zA-Z][a-zA-Z0-9_-]{0,63}$/;
+/** One section's JSON, serialized — a list of a thousand MCP servers is not a preference. */
+const MAX_SECTION_BYTES = 512 * 1024;
+
+function loadOrCreateKey() {
+  try {
+    if (existsSync(KEY_PATH)) return Buffer.from(readFileSync(KEY_PATH, 'utf8').trim(), 'base64');
+  } catch { /* regenerate below */ }
+  const key = randomBytes(32);
+  mkdirSync(dirname(KEY_PATH), { recursive: true, mode: 0o700 });
+  writeFileSync(KEY_PATH, key.toString('base64'), { mode: 0o600 });
+  return key;
+}
+
+function encrypt(key, buf) {
+  const iv = randomBytes(12);
+  const cipher = createCipheriv('aes-256-gcm', key, iv);
+  const ct = Buffer.concat([cipher.update(buf), cipher.final()]);
+  return { v: 1, iv: iv.toString('base64'), tag: cipher.getAuthTag().toString('base64'), ct: ct.toString('base64') };
+}
+
+function decrypt(key, env) {
+  const d = createDecipheriv('aes-256-gcm', key, Buffer.from(env.iv, 'base64'));
+  d.setAuthTag(Buffer.from(env.tag, 'base64'));
+  return Buffer.concat([d.update(Buffer.from(env.ct, 'base64')), d.final()]);
+}
+
+export class PrefsStore {
+  constructor({ storePath = STORE_PATH } = {}) {
+    this.path = storePath;
+    this._key = null;
+    this.sections = {}; // id -> { value, updatedAt, by }
+    this.revision = 0;   // bumps on every accepted write, so a client can ask "anything new?"
+  }
+
+  load() {
+    this._key = loadOrCreateKey();
+    try {
+      if (existsSync(this.path)) {
+        const env = JSON.parse(readFileSync(this.path, 'utf8'));
+        const doc = JSON.parse(decrypt(this._key, env).toString('utf8'));
+        this.sections = doc?.sections && typeof doc.sections === 'object' ? doc.sections : {};
+        this.revision = Number(doc?.revision) || 0;
+      }
+    } catch {
+      // An unreadable store is an empty one, never a crash: the clients still hold their own
+      // copies and will push them back on the next change.
+      this.sections = {};
+      this.revision = 0;
+    }
+    return this;
+  }
+
+  save() {
+    mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 });
+    const env = encrypt(this._key, Buffer.from(JSON.stringify({ v: 1, revision: this.revision, sections: this.sections }), 'utf8'));
+    // Write beside, then rename: a crash mid-write leaves the old file, not half of a new one.
+    const tmp = `${this.path}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(env), { mode: 0o600 });
+    renameSync(tmp, this.path);
+  }
+
+  /** Every section, or one. Values are the caller's to keep — they are copies. */
+  get(id = '') {
+    if (id) {
+      const s = this.sections[id];
+      return s ? { [id]: { value: clone(s.value), updatedAt: s.updatedAt, by: s.by || '' } } : {};
+    }
+    const out = {};
+    for (const [k, s] of Object.entries(this.sections)) out[k] = { value: clone(s.value), updatedAt: s.updatedAt, by: s.by || '' };
+    return out;
+  }
+
+  /** Just the stamps — enough for a client to decide whether it needs the values. */
+  stamps() {
+    const out = {};
+    for (const [k, s] of Object.entries(this.sections)) out[k] = s.updatedAt;
+    return out;
+  }
+
+  /**
+   * Merge a client's stamped sections in. A section is taken when its stamp is newer than
+   * the one held (or nothing is held); otherwise the client is told it lost and gets the
+   * held copy back. Returns `{ applied, kept, sections }` where `sections` holds the current
+   * copies of everything the client sent — the client writes `kept` ones over its own.
+   */
+  put(incoming, { by = '' } = {}) {
+    const applied = [];
+    const kept = [];
+    const sections = {};
+    for (const [id, entry] of Object.entries(incoming || {})) {
+      if (!SECTION_ID_RE.test(id)) continue;
+      const updatedAt = Number(entry?.updatedAt) || 0;
+      if (!updatedAt || entry?.value === undefined) continue;
+      let bytes;
+      try { bytes = Buffer.byteLength(JSON.stringify(entry.value), 'utf8'); } catch { continue; }
+      if (bytes > MAX_SECTION_BYTES) continue;
+      const held = this.sections[id];
+      if (!held || updatedAt > held.updatedAt) {
+        this.sections[id] = { value: clone(entry.value), updatedAt, by: String(by || '').slice(0, 40) };
+        applied.push(id);
+      } else {
+        kept.push(id);
+      }
+      const cur = this.sections[id];
+      sections[id] = { value: clone(cur.value), updatedAt: cur.updatedAt, by: cur.by || '' };
+    }
+    if (applied.length) { this.revision += 1; this.save(); }
+    return { applied, kept, sections, revision: this.revision };
+  }
+
+  /** Forget one section entirely — the user removed the feature's settings, not just emptied them. */
+  remove(id) {
+    if (!this.sections[id]) return false;
+    delete this.sections[id];
+    this.revision += 1;
+    this.save();
+    return true;
+  }
+}
+
+const clone = (v) => (v === undefined ? undefined : JSON.parse(JSON.stringify(v)));
+
+export function createPrefsStore(opts) {
+  return new PrefsStore(opts).load();
+}

package/src/server.js

@@ -33,6 +33,8 @@ import { startNer, ensureNer } from './ner.js';
 import { installTimestampedConsole } from './log.js';
 import { saveBackupSecret, clearBackupSecret, loadBackupSecret, hasBackupSecret } from './history-store.js';
 import { createMemoryStore } from './memory-store.js';
+import { createPrefsStore } from './prefs-store.js';
+import { createTeamStore } from './team-store.js';
 import { createHistoryStore } from './sqlite-store.js';
 import { ingestBackups } from './backup-ingest.js';
 import * as nerEngine from './ner-engine.js';
@@ -56,7 +58,7 @@ import * as openai from './openai.js';
 import * as responses from './responses.js';
 import * as anthropic from './anthropic.js';
 
-export const VERSION = '0.6.76';
+export const VERSION = '0.6.78';
 
 // WARM search tier — SQLite + FTS5 record store (falls back to an encrypted-JSON
 // store if SQLite can't load), fed by the extension's ingest sync + backup-ingest.
@@ -64,6 +66,12 @@ export const VERSION = '0.6.76';
 // See docs/architecture-data-tiers.
 const historyStore = await createHistoryStore();
 const memoryStore = await createMemoryStore();
+const prefsStore = createPrefsStore();
+const teamStore = createTeamStore();
+// Who is watching prefs change — a client with a live subscription is told the moment a
+// section is written by the other client, instead of waiting for its next focus.
+const prefsWatchers = new Set();
+const notifyPrefs = (applied, by) => { for (const fn of prefsWatchers) { try { fn({ applied, by, revision: prefsStore.revision }); } catch { /* gone */ } } };
 
 // OBSERVABILITY — a ring of "which agent read what, when", persisted across restarts (the
 // gateway updates often; an empty panel after each restart reads as "nothing is set up").
@@ -128,7 +136,7 @@ function originAllowed(origin, cfg) {
 
 function setCors(res, origin) {
   res.setHeader('Access-Control-Allow-Origin', origin || '*');
-  res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+  res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
   res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization, X-ChatPanel-Token');
   res.setHeader('Vary', 'Origin');
 }
@@ -693,6 +701,12 @@ export function createGateway(cfg = loadConfig()) {
       && req.method === 'POST' && !isAdminAuthorized(req)) {
       return sendJson(res, 403, { error: { message: 'memory write — extension origin or gateway token required', type: 'forbidden' } });
     }
+    // Client preferences travel between the extension and the desktop through here, and an
+    // MCP server entry can carry an Authorization header — so READS are gated too, unlike
+    // history and memory. A drive-by page must not learn what tools the user connected.
+    if ((pathname === '/v1/prefs' || pathname.startsWith('/v1/prefs/') || pathname.startsWith('/v1/teams')) && !isAdminAuthorized(req)) {
+      return sendJson(res, 403, { error: { message: 'prefs: extension origin or gateway token required', type: 'forbidden' } });
+    }
     // The access log is who-read-what — sensitive, and writable only by the local MCP
     // process (which sends the gateway token). Extension Origin or token for both the
     // read (dashboard) and the report (MCP child); a drive-by page has neither.
@@ -764,6 +778,110 @@ export function createGateway(cfg = loadConfig()) {
         return sendJson(res, 400, { error: { message: `ingest failed: ${e.message}`, type: 'ingest_error' } });
       }
     }
+    // --- CLIENT PREFERENCES — the settings every client shares (prefs-store.js).
+    //   GET  /v1/prefs[?section=id][&stamps=1] → { ok, revision, sections: { id: { value, updatedAt, by } } }
+    //   POST /v1/prefs { sections: { id: { value, updatedAt } }, by } → { ok, revision, applied, kept, sections }
+    //   DELETE /v1/prefs?section=id → { ok, removed }
+    if (pathname === '/v1/prefs' && req.method === 'GET') {
+      const section = String(url.searchParams.get('section') || '');
+      if (url.searchParams.get('stamps')) return sendJson(res, 200, { ok: true, revision: prefsStore.revision, stamps: prefsStore.stamps() });
+      return sendJson(res, 200, { ok: true, revision: prefsStore.revision, sections: prefsStore.get(section) });
+    }
+    if (pathname === '/v1/prefs' && (req.method === 'POST' || req.method === 'PUT')) {
+      try {
+        const body = JSON.parse((await readBody(req, cfg.maxBodyBytes)).toString('utf8')) || {};
+        const out = prefsStore.put(body.sections || {}, { by: body.by || '' });
+        if (out.applied.length) notifyPrefs(out.applied, body.by || '');
+        return sendJson(res, 200, { ok: true, ...out });
+      } catch (e) {
+        return sendJson(res, 400, { error: { message: `prefs write failed: ${e.message}`, type: 'prefs_error' } });
+      }
+    }
+    if (pathname === '/v1/prefs' && req.method === 'DELETE') {
+      const section = String(url.searchParams.get('section') || '');
+      const removed = section ? prefsStore.remove(section) : false;
+      if (removed) notifyPrefs([section], '');
+      return sendJson(res, 200, { ok: true, removed });
+    }
+    // Live prefs: one SSE stream a client keeps open, told which sections the OTHER client
+    // wrote. Without it a team defined on the desktop reached the extension at its next
+    // focus; with it, at once. `{ type: 'hello', revision }` first, so a reader knows where
+    // it stands; a heartbeat keeps proxies from closing an idle stream.
+    if (pathname === '/v1/prefs/events' && req.method === 'GET') {
+      res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-cache', connection: 'keep-alive' });
+      const sendEv = (ev) => res.write(`data: ${JSON.stringify(ev)}\n\n`);
+      sendEv({ type: 'hello', revision: prefsStore.revision, stamps: prefsStore.stamps() });
+      const fn = (ev) => sendEv({ type: 'changed', ...ev });
+      prefsWatchers.add(fn);
+      const beat = setInterval(() => { try { res.write(': keep-alive\n\n'); } catch { /* closed */ } }, 25_000);
+      res.on('close', () => { prefsWatchers.delete(fn); clearInterval(beat); });
+      return undefined;
+    }
+
+    // --- TEAM RUNS. The board every client can read (team-store.js).
+    //   GET  /v1/teams/runs[?limit&team]     → { ok, runs }            newest first, no boards
+    //   POST /v1/teams/runs { id, team, request, client } → { ok, run }
+    //   GET  /v1/teams/runs/:id[?events=1]   → { ok, run }             the board, the tasks, the proposal
+    //   POST /v1/teams/runs/:id/events { events: [...] } → { ok, run } the running client appends
+    //   GET  /v1/teams/runs/:id/events[?after=seq] (SSE)              replay from `after`, then live
+    //   POST /v1/teams/runs/:id/stop         → { ok, run }             a stop request any client may make
+    //   DELETE /v1/teams/runs/:id            → { ok, removed }
+    if (pathname === '/v1/teams/runs' && req.method === 'GET') {
+      return sendJson(res, 200, { ok: true, runs: teamStore.list({ limit: url.searchParams.get('limit') || 50, team: url.searchParams.get('team') || '' }) });
+    }
+    if (pathname === '/v1/teams/runs' && req.method === 'POST') {
+      try {
+        const body = JSON.parse((await readBody(req, cfg.maxBodyBytes)).toString('utf8')) || {};
+        return sendJson(res, 200, { ok: true, run: teamStore.create({ id: body.id, client: body.client, team: body.team, request: body.request }) });
+      } catch (e) {
+        return sendJson(res, 400, { error: { message: `team run: ${e.message}`, type: 'team_error' } });
+      }
+    }
+    {
+      const m = /^\/v1\/teams\/runs\/([a-zA-Z0-9_-]{4,64})(\/events|\/stop)?$/.exec(pathname);
+      if (m) {
+        const id = m[1];
+        const sub = m[2] || '';
+        if (!sub && req.method === 'GET') {
+          const run = teamStore.get(id, { events: url.searchParams.get('events') === '1' });
+          return run ? sendJson(res, 200, { ok: true, run }) : sendJson(res, 404, { error: { message: `no run ${id}`, type: 'not_found' } });
+        }
+        if (!sub && req.method === 'DELETE') return sendJson(res, 200, { ok: true, removed: teamStore.remove(id) });
+        if (sub === '/stop' && req.method === 'POST') {
+          const run = teamStore.stop(id);
+          return run ? sendJson(res, 200, { ok: true, run }) : sendJson(res, 404, { error: { message: `no run ${id}`, type: 'not_found' } });
+        }
+        if (sub === '/events' && req.method === 'POST') {
+          try {
+            const body = JSON.parse((await readBody(req, cfg.maxBodyBytes)).toString('utf8')) || {};
+            return sendJson(res, 200, { ok: true, run: teamStore.append(id, body.events || []) });
+          } catch (e) {
+            return sendJson(res, e.message.startsWith('no run') ? 404 : 400, { error: { message: `team run: ${e.message}`, type: 'team_error' } });
+          }
+        }
+        if (sub === '/events' && req.method === 'GET') {
+          if (!teamStore.get(id)) return sendJson(res, 404, { error: { message: `no run ${id}`, type: 'not_found' } });
+          res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-cache', connection: 'keep-alive' });
+          const sendEv = (ev) => res.write(`data: ${JSON.stringify(ev)}\n\n`);
+          // `Number(null)` is 0, not NaN: an absent `after` must mean "from the start" (-1),
+          // or the first event of every run is skipped.
+          const after = url.searchParams.has('after') ? Number(url.searchParams.get('after')) : NaN;
+          // The record as it stands, FIRST — it flushes the headers (writeHead alone sends
+          // nothing, and a reader whose fetch has not resolved can miss the opening events),
+          // and a late reader gets the board without a second request. Then replay from
+          // `after`, then tail; the watcher is registered before the replay is read and
+          // duplicates are dropped by seq, so nothing lands in the gap.
+          let last = Number.isFinite(after) ? after : -1;
+          sendEv({ seq: -1, type: 'hello', at: Date.now(), payload: { run: teamStore.get(id), after: last } });
+          const off = teamStore.watch(id, (ev) => { if (ev.seq > last) { last = ev.seq; sendEv(ev); } });
+          for (const ev of teamStore.eventsSince(id, last)) { last = ev.seq; sendEv(ev); }
+          const beat = setInterval(() => { try { res.write(': keep-alive\n\n'); } catch { /* closed */ } }, 25_000);
+          res.on('close', () => { off(); clearInterval(beat); });
+          return undefined;
+        }
+      }
+    }
+
     // --- MEMORY. Small, durable facts about the user, reachable by every local agent.
     //   GET  /v1/memory/list                      → { memories }
     //   POST /v1/memory/recall  { text, scopes }  → { memories, block }

package/src/team-store.js

@@ -0,0 +1,196 @@
+// TEAM RUNS — the board every client can read, held here because the gateway is the one
+// address the extension and the desktop both have.
+//
+// A run happens in ONE client (its models, its tools, its guards), but the extension cannot
+// read the desktop's database and vice versa. So the running client APPENDS the run's
+// events here as they happen — planned, started, a finding, done — and any client can read
+// the run: list it, open its board, follow it live (SSE), and stop it. The store is the
+// truth about what a team did; the client that ran it is just the first reader.
+//
+// Events are the unit, applied to a run record as they arrive (the shape @chatpanel/events
+// team-run.js emits), so a reader that joins late replays and one that is watching tails.
+// A run whose writer went quiet is reported as such: `staleAfterMs` past its last event a
+// `running` run is marked stale, never silently kept "running" forever. Stop is a flag the
+// running client sees on its own SSE stream and honours; the store cannot kill anything.
+//
+// Encrypted at rest with the device key like memory and prefs — a board carries the user's
+// own findings — and bounded: the newest runs are kept, the oldest evicted.
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, renameSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import os from 'node:os';
+import { randomBytes, createCipheriv, createDecipheriv } from 'node:crypto';
+
+const DIR = join(os.homedir(), '.chatpanel');
+const STORE_PATH = process.env.CHATPANEL_TEAMS_STORE || join(DIR, 'team-runs.enc');
+const KEY_PATH = process.env.CHATPANEL_HISTORY_KEY || join(DIR, 'history-key');
+
+export const MAX_RUNS = 200;
+export const MAX_EVENTS_PER_RUN = 2000;
+export const MAX_EVENT_BYTES = 64 * 1024;
+export const STALE_AFTER_MS = 5 * 60_000;
+const RUN_ID_RE = /^[a-zA-Z0-9_-]{4,64}$/;
+const LIVE = new Set(['planning', 'running', 'merging']);
+
+function loadOrCreateKey() {
+  try { if (existsSync(KEY_PATH)) return Buffer.from(readFileSync(KEY_PATH, 'utf8').trim(), 'base64'); } catch { /* regenerate */ }
+  const key = randomBytes(32);
+  mkdirSync(dirname(KEY_PATH), { recursive: true, mode: 0o700 });
+  writeFileSync(KEY_PATH, key.toString('base64'), { mode: 0o600 });
+  return key;
+}
+function encrypt(key, buf) {
+  const iv = randomBytes(12);
+  const cipher = createCipheriv('aes-256-gcm', key, iv);
+  const ct = Buffer.concat([cipher.update(buf), cipher.final()]);
+  return { v: 1, iv: iv.toString('base64'), tag: cipher.getAuthTag().toString('base64'), ct: ct.toString('base64') };
+}
+function decrypt(key, env) {
+  const d = createDecipheriv('aes-256-gcm', key, Buffer.from(env.iv, 'base64'));
+  d.setAuthTag(Buffer.from(env.tag, 'base64'));
+  return Buffer.concat([d.update(Buffer.from(env.ct, 'base64')), d.final()]);
+}
+const clone = (v) => (v === undefined ? undefined : JSON.parse(JSON.stringify(v)));
+
+/** Apply one event to a run record. The record is the fold of its events. */
+export function applyEvent(run, ev) {
+  const type = String(ev?.type || '');
+  const p = ev?.payload && typeof ev.payload === 'object' ? ev.payload : {};
+  run.lastEventAt = ev.at;
+  switch (type) {
+    case 'run.started':
+      run.team = p.team || run.team; run.request = p.request ?? run.request; run.budget = p.budget || run.budget;
+      run.roles = Array.isArray(p.roles) ? p.roles : run.roles; run.status = 'planning'; run.startedAt = run.startedAt || ev.at;
+      break;
+    case 'plan.ready':
+      run.plan = { by: p.by || 'fixed', tasks: Array.isArray(p.tasks) ? p.tasks : [] };
+      run.tasks = run.plan.tasks.map((t) => ({ id: t.id, role: t.role, title: t.title, status: 'pending', findings: 0 }));
+      run.status = 'running';
+      break;
+    case 'task.started': { const t = run.tasks.find((x) => x.id === p.taskId); if (t) { t.status = 'running'; t.startedAt = ev.at; } run.status = 'running'; break; }
+    case 'task.delta': { const t = run.tasks.find((x) => x.id === p.taskId); if (t) t.text = String(p.text || '').slice(0, 20_000); break; }
+    case 'task.finding':
+      if (p.finding && p.finding.text) { run.board.push({ ...p.finding, at: ev.at }); const t = run.tasks.find((x) => x.id === p.taskId); if (t) t.findings += 1; }
+      break;
+    case 'task.done':
+    case 'task.failed': { const t = run.tasks.find((x) => x.id === p.taskId); if (t) { t.status = p.status || (type === 'task.done' ? 'ok' : 'failed'); t.error = p.error || null; t.ms = p.ms; } break; }
+    case 'run.merging': run.status = 'merging'; break;
+    case 'run.done':
+      run.status = p.status || 'completed'; run.usage = p.usage || run.usage; run.proposal = p.proposal ?? run.proposal; run.endedAt = ev.at;
+      break;
+    case 'run.stop-requested': run.stopRequested = ev.at; break;
+    default: break;
+  }
+  return run;
+}
+
+export class TeamStore {
+  constructor({ storePath = STORE_PATH, now = () => Date.now(), staleAfterMs = STALE_AFTER_MS } = {}) {
+    this.path = storePath;
+    this.now = now;
+    this.staleAfterMs = staleAfterMs;
+    this._key = null;
+    this.runs = new Map(); // id -> { id, client, createdAt, events: [], ...folded record }
+    this.watchers = new Map(); // id -> Set<fn(ev)>
+  }
+  load() {
+    this._key = loadOrCreateKey();
+    try {
+      if (existsSync(this.path)) {
+        const env = JSON.parse(readFileSync(this.path, 'utf8'));
+        const doc = JSON.parse(decrypt(this._key, env).toString('utf8'));
+        for (const r of Array.isArray(doc?.runs) ? doc.runs : []) if (r?.id) this.runs.set(r.id, r);
+      }
+    } catch { this.runs = new Map(); }
+    return this;
+  }
+  save() {
+    mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 });
+    const env = encrypt(this._key, Buffer.from(JSON.stringify({ v: 1, runs: [...this.runs.values()] }), 'utf8'));
+    const tmp = `${this.path}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(env), { mode: 0o600 });
+    renameSync(tmp, this.path);
+  }
+  _fresh(id, { client = '' } = {}) {
+    return { id, client: String(client || '').slice(0, 40), createdAt: this.now(), lastEventAt: this.now(), status: 'planning', team: '', request: '', roles: [], plan: null, tasks: [], board: [], proposal: null, usage: null, stopRequested: null, events: [] };
+  }
+  _evict() {
+    if (this.runs.size <= MAX_RUNS) return;
+    const byAge = [...this.runs.values()].sort((a, b) => a.createdAt - b.createdAt);
+    for (const r of byAge.slice(0, this.runs.size - MAX_RUNS)) this.runs.delete(r.id);
+  }
+  /** The record with liveness judged NOW, never as it was last written. */
+  _view(run, { events = false } = {}) {
+    const v = clone({ ...run, events: undefined });
+    delete v.events;
+    v.stale = LIVE.has(run.status) && this.now() - run.lastEventAt > this.staleAfterMs;
+    if (events) v.events = clone(run.events);
+    return v;
+  }
+  create({ id, client, team, request } = {}) {
+    if (!RUN_ID_RE.test(String(id || ''))) throw new Error('run id: 4–64 of [a-zA-Z0-9_-]');
+    if (this.runs.has(id)) throw new Error(`run ${id} already exists`);
+    const run = this._fresh(id, { client });
+    run.team = String(team || '').slice(0, 64);
+    run.request = String(request || '').slice(0, 4000);
+    this.runs.set(id, run);
+    this._evict();
+    this.save();
+    return this._view(run);
+  }
+  /** Append events (the runner's `emit` shape: `{ type, at, ...payload }`). Returns the view. */
+  append(id, events) {
+    const run = this.runs.get(String(id || ''));
+    if (!run) throw new Error(`no run ${id}`);
+    const list = Array.isArray(events) ? events : [events];
+    let seq = run.events.length;
+    for (const e of list) {
+      if (!e || typeof e !== 'object' || !e.type) continue;
+      let bytes; try { bytes = Buffer.byteLength(JSON.stringify(e), 'utf8'); } catch { continue; }
+      if (bytes > MAX_EVENT_BYTES) continue;
+      if (run.events.length >= MAX_EVENTS_PER_RUN) break;
+      const { type, at, runId: _r, ...payload } = e;
+      const ev = { seq: seq++, type: String(type), at: Number(at) || this.now(), payload };
+      run.events.push(ev);
+      applyEvent(run, ev);
+      for (const fn of this.watchers.get(run.id) || []) { try { fn(ev); } catch { /* a dead watcher */ } }
+    }
+    this.save();
+    return this._view(run);
+  }
+  get(id, opts) { const r = this.runs.get(String(id || '')); return r ? this._view(r, opts) : null; }
+  /** Newest first, without boards — the list a lens shows. */
+  list({ limit = 50, team = '' } = {}) {
+    return [...this.runs.values()]
+      .filter((r) => !team || r.team === team)
+      .sort((a, b) => b.createdAt - a.createdAt)
+      .slice(0, Math.max(1, Math.min(200, Number(limit) || 50)))
+      .map((r) => { const v = this._view(r); return { ...v, board: undefined, tasks: v.tasks.map((t) => ({ ...t, text: undefined })), findings: r.board.length }; });
+  }
+  /** Ask the running client to stop. Recorded as an event, so watchers (the runner) see it. */
+  stop(id) {
+    const run = this.runs.get(String(id || ''));
+    if (!run) return null;
+    if (!LIVE.has(run.status)) return this._view(run);
+    return this.append(id, [{ type: 'run.stop-requested', at: this.now() }]);
+  }
+  /** Events from `after` (a seq) onward, for a late reader's replay. */
+  eventsSince(id, after = -1) {
+    const run = this.runs.get(String(id || ''));
+    if (!run) return [];
+    return run.events.filter((e) => e.seq > after).map(clone);
+  }
+  watch(id, fn) {
+    if (!this.watchers.has(id)) this.watchers.set(id, new Set());
+    this.watchers.get(id).add(fn);
+    return () => this.watchers.get(id)?.delete(fn);
+  }
+  remove(id) {
+    const had = this.runs.delete(String(id || ''));
+    if (had) this.save();
+    return had;
+  }
+  get size() { return this.runs.size; }
+}
+
+export function createTeamStore(opts) { return new TeamStore(opts).load(); }