@oar-sh/oar 0.9.16 → 0.9.18

package/server/services/claude-billing-switch-service.mjs

@@ -0,0 +1,343 @@
+'use strict';
+
+/**
+ * The Claude billing switch: a Claude chat moves between the host's Claude
+ * subscription (`claude`) and the API key saved in Settings → Providers →
+ * Claude API (`claude-api`), and keeps its Claude Code session: both run the
+ * same CLI on the same `~/.claude`.
+ *
+ * The chat's billing is `runtime_sessions.provider_type`. A switch, in one
+ * transaction:
+ * - checks the target: the provider usable (a key for the API, the Claude
+ *   provider on for the subscription), the monthly cap, the chat's model in
+ *   the target's list, and the history rule of decision 23;
+ * - writes the billing, when and by whom;
+ * - re-stamps the chat's rows that have not started (`queue.provider`), so
+ *   they run on the new billing; a row already running finishes on its own;
+ * - to the API key, releases a turn held at the subscription's usage limit;
+ * - leaves one note in the transcript (a second switch before the next turn
+ *   rewrites it);
+ * - and, for an agent's `send`, enqueues its message (`enqueue`).
+ *
+ * The worker swap itself is the delivery's (claude-billing-swap-service.mjs):
+ * the next row of the new billing is not handed to a worker of the old kind,
+ * which is replaced once it is idle.
+ */
+
+import { randomUUID } from 'node:crypto';
+
+import { claudeBaseModelId, isClaudeLongContextModelId } from '../../shared/model-id.mjs';
+
+export const CLAUDE_BILLING_PROVIDERS = Object.freeze(['claude', 'claude-api']);
+export const CLAUDE_BILLING_NOTE_KIND = 'billing-switch';
+export const CLAUDE_BILLING_SWITCHED_BY = Object.freeze(['user', 'agent', 'usage-limit']);
+
+// Decision 23: whether a chat with turns on the other billing may move to
+// this one. Set from the WP3 live check (a subscription session's history on
+// the key, and back); 'blocked' disables the switch for such chats.
+export const CLAUDE_BILLING_HISTORY_RULE = Object.freeze({
+  'claude-api': 'allowed',
+  claude: 'allowed',
+});
+
+export const CLAUDE_BILLING_LABELS = Object.freeze({
+  claude: 'Subscription',
+  'claude-api': 'API key',
+});
+
+export function normalizeClaudeBilling(value) {
+  const billing = String(value || '').trim().toLowerCase();
+  return CLAUDE_BILLING_PROVIDERS.includes(billing) ? billing : '';
+}
+
+export function otherClaudeBilling(billing) {
+  return normalizeClaudeBilling(billing) === 'claude' ? 'claude-api' : 'claude';
+}
+
+/** The transcript note for a switch. */
+export function buildClaudeBillingNoteText({ to, by = 'user' } = {}) {
+  const who = by === 'agent' ? ' (switched by an agent)' : (by === 'usage-limit' ? ' (switched at the usage limit)' : '');
+  if (normalizeClaudeBilling(to) === 'claude-api') {
+    return `💳 Billing: this chat runs on the Claude API key from the next turn${who}. `
+      + 'The first turn on the key has no prompt cache and costs more.';
+  }
+  return `💳 Billing: this chat runs on the Claude subscription from the next turn${who}.`;
+}
+
+function refusal(status, code, error, extra = {}) {
+  return { ok: false, status, code, error, ...extra };
+}
+
+function modelListFor(settings) {
+  return new Set([
+    String(settings?.model || '').trim(),
+    ...(Array.isArray(settings?.availableModels) ? settings.availableModels : []),
+    ...(Array.isArray(settings?.models) ? settings.models : []),
+  ].map((value) => String(value || '').trim().toLowerCase()).filter(Boolean));
+}
+
+export function createClaudeBillingSwitchService({
+  db,
+  stmts,
+  emit = () => {},
+  getClaudeProviderSettings = () => null,
+  getClaudeApiProviderSettings = () => null,
+  // The monthly cap: `{ reached, error? }`, from the runtime's
+  // getClaudeApiCapState seam (the claim check asks the same one; WP5 fills
+  // it in). Not reached by default.
+  getClaudeApiCapState = () => ({ reached: false }),
+  historyRule = CLAUDE_BILLING_HISTORY_RULE,
+  // Releases a turn held at the subscription's usage limit
+  // (usage-limit-pause-service.mjs); runs inside the switch's transaction.
+  releaseUsageLimitPause = null,
+  // The runtime row → what the worker swap waits for (claude-billing-swap-
+  // service.mjs, pendingFor), or null.
+  getPending = () => null,
+  onQueueChanged = () => {},
+  now = () => Date.now(),
+  logger = console,
+} = {}) {
+  if (!db || !stmts) throw new Error('createClaudeBillingSwitchService requires db and stmts');
+
+  const runtimeColumns = new Set(db.prepare(`PRAGMA table_info(runtime_sessions)`).all().map((column) => column.name));
+  const queueColumns = new Set(db.prepare(`PRAGMA table_info(queue)`).all().map((column) => column.name));
+  const messageColumns = new Set(db.prepare(`PRAGMA table_info(messages)`).all().map((column) => column.name));
+  const recordsSwitch = runtimeColumns.has('billing_switched_at') && runtimeColumns.has('billing_switched_by');
+
+  const getRuntime = db.prepare(`SELECT * FROM runtime_sessions WHERE conversation_id = ? LIMIT 1`);
+  const setBilling = recordsSwitch
+    ? db.prepare(`
+        UPDATE runtime_sessions
+        SET provider_type = ?, billing_switched_at = ?, billing_switched_by = ?, last_used_at = ?
+        WHERE id = ?
+      `)
+    : db.prepare(`UPDATE runtime_sessions SET provider_type = ?, last_used_at = ? WHERE id = ?`);
+  const setModel = db.prepare(`UPDATE runtime_sessions SET provider_model = ?, model = ? WHERE id = ?`);
+  const restampRows = queueColumns.has('provider')
+    ? db.prepare(`UPDATE queue SET provider = ? WHERE conversation_id = ? AND status IN ('pending', 'parked')`)
+    : null;
+  const countUnstartedRows = db.prepare(`
+    SELECT COUNT(*) AS n FROM queue WHERE conversation_id = ? AND status IN ('pending', 'parked')
+  `);
+  // The turns that ran on a billing other than `?`: replies with a recorded
+  // provider. A reply from before it was recorded (or a relay note) names
+  // none and does not count: an old chat is judged by the turns it has run
+  // since, and a history the API still refuses meets the turn's own refusal.
+  const countOtherBillingTurns = messageColumns.has('executed_provider')
+    ? db.prepare(`
+        SELECT COUNT(*) AS n FROM messages
+        WHERE conversation_id = ? AND role = 'assistant'
+          AND executed_provider IS NOT NULL AND LOWER(executed_provider) != ?
+      `)
+    : null;
+  const latestMessage = messageColumns.has('kind')
+    ? db.prepare(`SELECT id, role, kind, timestamp FROM messages WHERE conversation_id = ? ORDER BY timestamp DESC, rowid DESC LIMIT 1`)
+    : null;
+  const rewriteNote = db.prepare(`UPDATE messages SET text = ?, timestamp = ? WHERE id = ?`);
+
+  function readSettings(read) {
+    try {
+      const settings = read();
+      return settings && typeof settings === 'object' ? settings : {};
+    } catch {
+      return {};
+    }
+  }
+
+  function chatModel(runtime) {
+    return String(runtime?.provider_model || runtime?.model || '').trim();
+  }
+
+  /**
+   * Whether the chat may move to `to` now: `{ ok: true, runtime, from, to,
+   * model }`, or a refusal `{ ok: false, status, code, error }`. `model` is a
+   * model asked for with the switch, checked in place of the chat's own.
+   */
+  function checkSwitch({ conversationId, to, model = '' } = {}) {
+    const convId = String(conversationId || '').trim();
+    const target = normalizeClaudeBilling(to);
+    if (!target) return refusal(400, 'CLAUDE_BILLING_INVALID', 'Billing must be "claude" (subscription) or "claude-api" (API key)');
+    const runtime = convId ? (getRuntime.get(convId) || null) : null;
+    if (!runtime) return refusal(404, 'CONVERSATION_NOT_FOUND', 'Conversation not found');
+    const from = normalizeClaudeBilling(runtime.provider_type);
+    if (!from) {
+      return refusal(409, 'CLAUDE_BILLING_NOT_CLAUDE', 'Only a Claude chat can switch between the subscription and the API key', {
+        provider: String(runtime.provider_type || '').trim().toLowerCase() || 'github',
+      });
+    }
+    if (from === target) return { ok: true, runtime, from, to: target, model: chatModel(runtime), changed: false };
+    const settings = target === 'claude-api'
+      ? readSettings(getClaudeApiProviderSettings)
+      : readSettings(getClaudeProviderSettings);
+    if (target === 'claude-api' && settings.enabled !== true) {
+      return refusal(409, 'CLAUDE_API_NOT_CONFIGURED', settings.configured === true
+        ? 'Claude API is switched off. Switch it on in Settings → Providers → Claude API.'
+        : 'Claude API has no key. Save one in Settings → Providers → Claude API.');
+    }
+    if (target === 'claude' && settings.enabled !== true) {
+      return refusal(409, 'CLAUDE_NOT_CONFIGURED', 'The Claude provider is switched off. Switch it on in Settings → Providers → Claude.');
+    }
+    if (target === 'claude-api') {
+      let cap = null;
+      // A cap that cannot be read is taken as reached: the key's bill is at stake.
+      try { cap = getClaudeApiCapState() || null; } catch { cap = { reached: true }; }
+      if (cap?.reached === true) {
+        return refusal(409, 'CLAUDE_API_CAP_REACHED', String(cap.error || '').trim()
+          || "This month's Claude API spend has reached the cap set in Settings → Providers → Claude API.");
+      }
+    }
+    const wanted = String(model || '').trim() || chatModel(runtime);
+    if (wanted) {
+      const list = modelListFor(settings);
+      const exact = list.has(wanted.toLowerCase());
+      // A `[1m]` model needs its long-context variant listed; a plain id is
+      // also taken by its base.
+      const listed = exact || (!isClaudeLongContextModelId(wanted) && list.has(claudeBaseModelId(wanted).toLowerCase()));
+      if (!listed) {
+        return refusal(409, 'CLAUDE_BILLING_MODEL_UNAVAILABLE',
+          `${wanted} is not in the ${target === 'claude-api' ? 'Claude API' : 'Claude'} model list. Pick a model it has, then switch.`,
+          { model: wanted });
+      }
+    }
+    if (String(historyRule?.[target] || 'allowed') === 'blocked' && countOtherBillingTurns) {
+      const turns = Number(countOtherBillingTurns.get(runtime.conversation_id, target)?.n || 0);
+      if (turns > 0) {
+        return refusal(409, 'CLAUDE_BILLING_HISTORY', target === 'claude-api'
+          ? 'This chat already has subscription turns, and the API refuses that history. Start a new Claude API chat.'
+          : 'This chat already has API key turns, and the subscription refuses that history. Start a new Claude chat.');
+      }
+    }
+    return { ok: true, runtime, from, to: target, model: wanted, changed: true };
+  }
+
+  /** What the composer's toggle and the usage-limit note read about a chat's billing. */
+  function billingState(conversationId) {
+    const runtime = getRuntime.get(String(conversationId || '').trim()) || null;
+    const provider = normalizeClaudeBilling(runtime?.provider_type);
+    if (!provider) return null;
+    const to = otherClaudeBilling(provider);
+    const check = checkSwitch({ conversationId, to });
+    let pending = null;
+    try { pending = getPending(runtime) || null; } catch { pending = null; }
+    return {
+      provider,
+      pending,
+      switchedAt: runtime?.billing_switched_at || null,
+      switchedBy: runtime?.billing_switched_by || null,
+      switchable: {
+        to,
+        allowed: check.ok === true,
+        code: check.ok ? null : check.code,
+        reason: check.ok ? null : check.error,
+      },
+    };
+  }
+
+  /**
+   * Switch the chat's billing. `enqueue({ runtime, billing })` runs inside
+   * the transaction after the switch (an agent's message), also when the
+   * chat already has that billing; a throw undoes the switch. A switch to
+   * the key releases a turn held at the subscription's usage limit.
+   */
+  function switchBilling({ conversationId, to, by = 'user', model = '', enqueue = null, deferAnnounce = false } = {}) {
+    const who = CLAUDE_BILLING_SWITCHED_BY.includes(by) ? by : 'user';
+    let outcome = null;
+    let note = null;
+    let released = null;
+    let enqueued = null;
+    const run = db.transaction(() => {
+      const check = checkSwitch({ conversationId, to, model });
+      if (!check.ok) {
+        outcome = check;
+        return;
+      }
+      const at = new Date(now()).toISOString();
+      const { runtime } = check;
+      if (check.changed) {
+        if (recordsSwitch) setBilling.run(check.to, at, who, at, runtime.id);
+        else setBilling.run(check.to, at, runtime.id);
+        if (String(model || '').trim() && check.model !== chatModel(runtime)) setModel.run(check.model, check.model, runtime.id);
+        restampRows?.run(check.to, runtime.conversation_id);
+        note = writeNote(runtime.conversation_id, check.to, who, at);
+        if (check.to === 'claude-api' && typeof releaseUsageLimitPause === 'function') {
+          released = releaseUsageLimitPause({ conversationId: runtime.conversation_id, by: 'billing-switch' }) || null;
+        }
+      }
+      if (typeof enqueue === 'function') enqueued = enqueue({ runtime, billing: check.to }) ?? null;
+      outcome = {
+        ok: true,
+        changed: check.changed,
+        conversationId: runtime.conversation_id,
+        provider: check.to,
+        from: check.from,
+        at,
+        queuedRows: Number(countUnstartedRows.get(runtime.conversation_id)?.n || 0),
+      };
+    });
+    run();
+    if (!outcome?.ok) return outcome;
+    const result = {
+      ...outcome,
+      noteMessageId: note?.messageId || null,
+      released: released ? { messageId: released.messageId || null } : null,
+      enqueued,
+    };
+    // Called inside a caller's transaction (the send route's persist step),
+    // the switch is not committed yet: the caller announces it once it is.
+    if (deferAnnounce) return { ...result, announce: () => announce(outcome, note, released, who) };
+    announce(outcome, note, released, who);
+    return result;
+  }
+
+  // What the clients and the queue hear of a committed switch.
+  function announce(outcome, note, released, who) {
+    try { released?.announce?.(); } catch {}
+    if (note) {
+      try {
+        emit(note.created ? 'assistant_message' : 'message_updated', {
+          conversationId: outcome.conversationId,
+          messageId: note.messageId,
+          message: {
+            id: note.messageId,
+            role: 'assistant',
+            text: note.text,
+            kind: CLAUDE_BILLING_NOTE_KIND,
+            model: null,
+            mode: null,
+            attachments: [],
+            timestamp: note.timestamp,
+          },
+        });
+      } catch {}
+    }
+    if (outcome.changed) {
+      try {
+        logger.log?.(`[claude-billing] conv=${outcome.conversationId.slice(0, 8)} ${outcome.from} → ${outcome.provider} by ${who}; ${outcome.queuedRows} queued row(s) re-stamped`);
+      } catch {}
+      try { emit('conversation_billing', { conversationId: outcome.conversationId, billing: billingState(outcome.conversationId) }); } catch {}
+      try { onQueueChanged('claude-billing-switch'); } catch {}
+    }
+  }
+
+  // One note per run of switches: one written since the chat's last message
+  // is rewritten in place, so a switch there and back leaves one line.
+  function writeNote(conversationId, to, by, at) {
+    const text = buildClaudeBillingNoteText({ to, by });
+    const latest = latestMessage?.get(conversationId) || null;
+    if (latest && latest.role === 'assistant' && latest.kind === CLAUDE_BILLING_NOTE_KIND) {
+      rewriteNote.run(text, at, latest.id);
+      return { messageId: latest.id, text, timestamp: at, created: false };
+    }
+    const messageId = randomUUID();
+    stmts.insertMsg.run(messageId, conversationId, 'assistant', text, null, null, null, at, null, null, null);
+    stmts.setMessageKind?.run?.(CLAUDE_BILLING_NOTE_KIND, messageId);
+    stmts.updateConvTime?.run?.(at, conversationId);
+    return { messageId, text, timestamp: at, created: true };
+  }
+
+  return {
+    checkSwitch,
+    billingState,
+    switchBilling,
+  };
+}

package/server/services/claude-session-leftovers.mjs

@@ -0,0 +1,226 @@
+// What a Claude Code session leaves in its config directory besides the
+// transcript, removed when the relay deletes the conversation.
+//
+// Only for a config directory the relay owns (DeepSeek's `deepseek-claude`
+// in the data folder), never the host's ~/.claude: the user's own CLI keeps
+// its sessions there. The relay stops the worker before it deletes anything,
+// and a stopped CLI is killed without its exit cleanup, so it leaves (the
+// bundled CLI, checked 2026-10-25):
+// - `session-env/<session id>/`, the session's hook environment files;
+// - `sessions/<pid>.json`, the process's registration (`{ pid, sessionId,
+//   cwd, startedAt, ... }`), and `sessions/<pid>.<sha256>.key`, its
+//   messaging key;
+// - `shell-snapshots/snapshot-<shell>-<ms>-<random>.sh`, the shell snapshot
+//   the process took at its start, whose name carries no session id: it is
+//   matched by the time in its name against the session's CLI starts;
+// - `projects/<slug(cwd)>/` with an empty `memory/`, once its last session
+//   is gone.
+// What belongs to another session stays: a registration of a live process,
+// a snapshot that also lies in the start window of another session's CLI,
+// and a project folder that still holds anything but an empty `memory/`.
+//
+// A CLI that exits on its own removes its registration but not always its
+// snapshot: the registration goes in a synchronous `exit` handler, the
+// snapshot only in the CLI's asynchronous cleanup, which a stop does not
+// wait for (a worker restart left the first CLI's snapshot behind with no
+// registration to match it). So the relay records every CLI start of a
+// session itself (recordClaudeCliStart, from the worker's report at the
+// CLI's first init) in `oar-cli-starts.json` in the config dir, and the
+// delete matches snapshots against those starts as well as against the
+// registrations. Every recorded start of another session protects its
+// window, as a registration does.
+
+import nodeFs from 'node:fs';
+import nodePath from 'node:path';
+
+const SESSION_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const REGISTRATION_PATTERN = /^(\d{1,10})\.json$/;
+const SNAPSHOT_PATTERN = /^snapshot-[a-z]+-(\d{10,16})-[A-Za-z0-9]+(?:-[A-Za-z0-9-]+)?\.sh$/;
+// The snapshot is taken while the CLI starts, around its registration.
+const SNAPSHOT_WINDOW_BEFORE_MS = 60_000;
+const SNAPSHOT_WINDOW_AFTER_MS = 120_000;
+const MAX_ENTRIES = 2_000;
+// The relay's record of CLI starts: one file, keyed by session id inside it.
+const CLI_STARTS_FILE = 'oar-cli-starts.json';
+const MAX_STARTS_PER_SESSION = 200;
+const MAX_SESSIONS_RECORDED = 5_000;
+
+function defaultIsPidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code === 'EPERM';
+  }
+}
+
+function readDir(fs, dir) {
+  try {
+    return fs.readdirSync(dir).slice(0, MAX_ENTRIES);
+  } catch {
+    return [];
+  }
+}
+
+function remove(fs, target, removed) {
+  try {
+    fs.rmSync(target, { recursive: true, force: true });
+    removed.push(target);
+  } catch {}
+}
+
+/** The registrations in `sessions/`: `{ pid, sessionId, startedAt, file }`. */
+function readRegistrations(fs, path, sessionsDir) {
+  const registrations = [];
+  for (const name of readDir(fs, sessionsDir)) {
+    const match = REGISTRATION_PATTERN.exec(name);
+    if (!match) continue;
+    let parsed = null;
+    try {
+      parsed = JSON.parse(fs.readFileSync(path.join(sessionsDir, name), 'utf8'));
+    } catch {
+      continue;
+    }
+    const startedAt = Number(parsed?.startedAt);
+    registrations.push({
+      pid: Number(match[1]),
+      sessionId: String(parsed?.sessionId ?? ''),
+      startedAt: Number.isFinite(startedAt) ? startedAt : null,
+      file: name,
+    });
+  }
+  return registrations;
+}
+
+/** `{ [sessionId]: [startedAt ms, ...] }` from the relay's record, or `{}`. */
+function readCliStarts(fs, file) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    const sessions = parsed?.sessions && typeof parsed.sessions === 'object' ? parsed.sessions : {};
+    const starts = {};
+    for (const [id, list] of Object.entries(sessions)) {
+      if (!SESSION_ID_PATTERN.test(id) || !Array.isArray(list)) continue;
+      starts[id] = list.map(Number).filter(Number.isFinite);
+    }
+    return starts;
+  } catch {
+    return {};
+  }
+}
+
+function writeCliStarts(fs, file, starts) {
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify({ version: 1, sessions: starts }), { encoding: 'utf8', mode: 0o600 });
+  fs.renameSync(tmp, file);
+}
+
+/**
+ * Note that a CLI started for `nativeSessionId` at `startedAt` (ms), under
+ * the relay's own config dir. Best-effort; returns whether it was noted.
+ */
+export function recordClaudeCliStart({ configRoot, nativeSessionId, startedAt, fs = nodeFs, path = nodePath } = {}) {
+  const root = String(configRoot || '').trim();
+  const sessionId = String(nativeSessionId || '').trim();
+  const at = Number(startedAt);
+  if (!root || !SESSION_ID_PATTERN.test(sessionId) || !Number.isFinite(at) || at <= 0) return false;
+  try {
+    const resolvedRoot = path.resolve(root);
+    fs.mkdirSync(resolvedRoot, { recursive: true });
+    const file = path.join(resolvedRoot, CLI_STARTS_FILE);
+    const starts = readCliStarts(fs, file);
+    const list = starts[sessionId] || [];
+    if (!list.includes(at)) list.push(at);
+    starts[sessionId] = list.slice(-MAX_STARTS_PER_SESSION);
+    // A record that outgrows its cap drops the sessions started longest ago.
+    const ids = Object.keys(starts);
+    if (ids.length > MAX_SESSIONS_RECORDED) {
+      const newest = (id) => Math.max(...starts[id], 0);
+      for (const id of ids.sort((a, b) => newest(a) - newest(b)).slice(0, ids.length - MAX_SESSIONS_RECORDED)) delete starts[id];
+    }
+    writeCliStarts(fs, file, starts);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function inStartWindow(time, startedAt) {
+  return startedAt !== null && time >= startedAt - SNAPSHOT_WINDOW_BEFORE_MS && time <= startedAt + SNAPSHOT_WINDOW_AFTER_MS;
+}
+
+/**
+ * Remove what the session `nativeSessionId` left under `configRoot`, and
+ * `projectDirPath` when nothing but an empty `memory/` is left in it.
+ * Returns the paths removed. Best-effort: a path that will not go stays.
+ */
+export function removeClaudeSessionLeftovers({
+  configRoot,
+  nativeSessionId,
+  projectDirPath = '',
+  fs = nodeFs,
+  path = nodePath,
+  isPidAlive = defaultIsPidAlive,
+} = {}) {
+  const removed = [];
+  const root = String(configRoot || '').trim();
+  const sessionId = String(nativeSessionId || '').trim();
+  if (!root || !SESSION_ID_PATTERN.test(sessionId)) return removed;
+  const resolvedRoot = path.resolve(root);
+
+  const sessionEnv = path.join(resolvedRoot, 'session-env', sessionId);
+  if (fs.existsSync(sessionEnv)) remove(fs, sessionEnv, removed);
+
+  const sessionsDir = path.join(resolvedRoot, 'sessions');
+  const registrations = readRegistrations(fs, path, sessionsDir);
+  const stale = registrations.filter((entry) => entry.sessionId === sessionId && !isPidAlive(entry.pid));
+  const others = registrations.filter((entry) => !stale.includes(entry));
+  const files = readDir(fs, sessionsDir);
+  for (const entry of stale) {
+    remove(fs, path.join(sessionsDir, entry.file), removed);
+    const keyPrefix = `${entry.pid}.`;
+    for (const name of files) {
+      if (name.startsWith(keyPrefix) && name.endsWith('.key')) remove(fs, path.join(sessionsDir, name), removed);
+    }
+  }
+
+  // The session's CLI starts: its dead registrations and every start the
+  // relay recorded. Another session's: its registrations and its recorded
+  // starts, whose windows are never touched.
+  const startsFile = path.join(resolvedRoot, CLI_STARTS_FILE);
+  const recorded = readCliStarts(fs, startsFile);
+  const ownStarts = [...stale.map((entry) => entry.startedAt), ...(recorded[sessionId] || [])];
+  const otherStarts = [
+    ...others.map((entry) => entry.startedAt),
+    ...Object.entries(recorded).filter(([id]) => id !== sessionId).flatMap(([, list]) => list),
+  ];
+  const snapshotsDir = path.join(resolvedRoot, 'shell-snapshots');
+  for (const name of readDir(fs, snapshotsDir)) {
+    const match = SNAPSHOT_PATTERN.exec(name);
+    if (!match) continue;
+    const takenAt = Number(match[1]);
+    if (!ownStarts.some((startedAt) => inStartWindow(takenAt, startedAt))) continue;
+    if (otherStarts.some((startedAt) => inStartWindow(takenAt, startedAt))) continue;
+    remove(fs, path.join(snapshotsDir, name), removed);
+  }
+  if (recorded[sessionId]) {
+    delete recorded[sessionId];
+    try {
+      writeCliStarts(fs, startsFile, recorded);
+    } catch {}
+  }
+
+  const projectDir = String(projectDirPath || '').trim() ? path.resolve(projectDirPath) : '';
+  if (projectDir && path.dirname(projectDir) === path.join(resolvedRoot, 'projects')) {
+    const entries = readDir(fs, projectDir);
+    const isEmptyDir = (dir) => {
+      try {
+        return fs.statSync(dir).isDirectory() && fs.readdirSync(dir).length === 0;
+      } catch {
+        return false;
+      }
+    };
+    const onlyEmptyMemory = entries.every((name) => name === 'memory' && isEmptyDir(path.join(projectDir, name)));
+    if (fs.existsSync(projectDir) && onlyEmptyMemory) remove(fs, projectDir, removed);
+  }
+  return removed;
+}

package/server/services/deepseek-balance-service.mjs

@@ -0,0 +1,102 @@
+'use strict';
+
+// The DeepSeek account balance for the usage card: `GET /user/balance` with
+// the saved key and base URL (shared/deepseek-api.mjs), only while DeepSeek
+// is on. An answer is kept for a minute, a failure for 15 seconds, and a
+// changed key or endpoint is read afresh. Never throws: a failure is an
+// answer of its own, `{ ok: false, code, error }`, whose text never holds the
+// key, with the last good answer beside it as `previous`.
+
+import { createDeepSeekApiClient } from '../../shared/deepseek-api.mjs';
+
+const DEFAULT_TTL_MS = 60_000;
+const DEFAULT_ERROR_TTL_MS = 15_000;
+// The usage modal waits for its slowest read, so this one is kept short.
+const DEFAULT_TIMEOUT_MS = 5_000;
+
+function redact(text, apiKey) {
+  const value = String(text ?? '');
+  const key = String(apiKey ?? '').trim();
+  return key ? value.split(key).join('[redacted]') : value;
+}
+
+export function createDeepSeekBalanceService({
+  getSettings = () => null,
+  fetchImpl = globalThis.fetch,
+  createClient = createDeepSeekApiClient,
+  now = () => Date.now(),
+  ttlMs = DEFAULT_TTL_MS,
+  errorTtlMs = DEFAULT_ERROR_TTL_MS,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+} = {}) {
+  let cache = null; // { identity, entry, expiresAt }
+  let lastGood = null; // { identity, entry }
+  let inflight = null; // { identity, promise }
+
+  function readSettings() {
+    try {
+      return getSettings() || null;
+    } catch {
+      return null;
+    }
+  }
+
+  async function read(settings) {
+    const fetchedAt = new Date(now()).toISOString();
+    if (!settings.apiKey) {
+      return { ok: false, code: 'not_configured', error: 'DeepSeek API key is not configured', fetchedAt };
+    }
+    try {
+      const client = createClient({ baseUrl: settings.baseUrl, apiKey: settings.apiKey, fetchImpl, timeoutMs });
+      const { isAvailable, balances } = await client.getBalance();
+      return { ok: true, isAvailable: isAvailable === true, balances: Array.isArray(balances) ? balances : [], fetchedAt };
+    } catch (error) {
+      return {
+        ok: false,
+        code: String(error?.code || 'error'),
+        error: redact(error?.message || error || 'DeepSeek balance check failed', settings.apiKey).slice(0, 300),
+        fetchedAt,
+      };
+    }
+  }
+
+  /**
+   * The balance, or null while DeepSeek is off. `{ force: true }` skips the
+   * cache (a fresh read is still shared with one already running).
+   */
+  async function getBalance({ force = false } = {}) {
+    const settings = readSettings();
+    if (settings?.enabled !== true) return null;
+    const identity = `${settings.baseUrl || ''}\n${settings.apiKey || ''}`;
+    const answer = (entry, cached) => (entry.ok || lastGood?.identity !== identity
+      ? { ...entry, cached }
+      : { ...entry, cached, previous: lastGood.entry });
+    if (!force && cache && cache.identity === identity && cache.expiresAt > now()) {
+      return answer(cache.entry, true);
+    }
+    if (!inflight || inflight.identity !== identity) {
+      const promise = read(settings).then((entry) => {
+        cache = { identity, entry, expiresAt: now() + (entry.ok ? ttlMs : errorTtlMs) };
+        if (entry.ok) lastGood = { identity, entry };
+        return entry;
+      }).finally(() => {
+        if (inflight?.promise === promise) inflight = null;
+      });
+      inflight = { identity, promise };
+    }
+    return answer(await inflight.promise, false);
+  }
+
+  /**
+   * The last good answer for the saved key and endpoint, without reading
+   * anew; null when there is none (or DeepSeek is off).
+   */
+  function peekBalance() {
+    const settings = readSettings();
+    if (settings?.enabled !== true) return null;
+    const identity = `${settings.baseUrl || ''}\n${settings.apiKey || ''}`;
+    return lastGood?.identity === identity ? lastGood.entry : null;
+  }
+
+  return { getBalance, peekBalance };
+}