@ravefox/space 0.0.0-stage → 0.2.1

package/src/lib/seat-runtime-controls.js

@@ -0,0 +1,61 @@
+// D247: the model and effort a seat spawns with.
+//
+// Two rules live here so the run loop and its tests share them:
+//
+// 1. A listener seat (`agent run` with no daemon behind it) reads the model and
+//    effort its owner saved in Settings or on the add page from
+//    GET /api/agents/runtime/installations before each turn. A saved value
+//    replaces the one in the local record; an absent one leaves it alone, so an
+//    older server changes nothing.
+// 2. An effort is dropped only when the device reported a NON-EMPTY list of
+//    levels that leaves it out. A device that reported nothing says nothing
+//    about the level, so the level is passed through and the harness decides.
+
+const isControl = (value) => typeof value === 'string' && value.length > 0 && value.length <= 256;
+
+const controlsOf = (row) => {
+  const controls = {};
+  if (isControl(row.runtimeControls.model)) controls.model = row.runtimeControls.model;
+  if (isControl(row.runtimeControls.effort)) controls.effort = row.runtimeControls.effort;
+  return Object.keys(controls).length ? controls : null;
+};
+
+/**
+ * The saved controls for this seat, or null when none are reported.
+ *
+ * A server that names `runtimeSourcePodId` (the installation Settings reads)
+ * is followed exactly: that row's controls, or null when it has none or the
+ * server names no source. An older server names none, and the seat reads its
+ * own pod's row, then any row of this instance that has controls.
+ */
+export const savedRuntimeControls = ({ installations, podId, instanceId, runtimeSourcePodId } = {}) => {
+  if (!Array.isArray(installations)) return null;
+  const rows = installations.filter((row) => row?.type === 'installation'
+    && row.runtimeControls && typeof row.runtimeControls === 'object');
+  const wantedInstance = String(instanceId || 'default');
+  if (runtimeSourcePodId !== undefined) {
+    const source = runtimeSourcePodId === null ? null
+      : rows.find((entry) => String(entry.podId || '') === String(runtimeSourcePodId)
+        && String(entry.instanceId || 'default') === wantedInstance);
+    return source ? controlsOf(source) : null;
+  }
+  // /installations returns runtimeControls on every row, `{}` when nothing is
+  // saved, so both matches require a value: an empty row in this pod must not
+  // hide the controls saved on the identity's other installation.
+  const hasControls = (entry) => isControl(entry.runtimeControls.model) || isControl(entry.runtimeControls.effort);
+  const row = rows.find((entry) => String(entry.podId || '') === String(podId || '')
+    && String(entry.instanceId || 'default') === wantedInstance && hasControls(entry))
+    || rows.find((entry) => String(entry.instanceId || 'default') === wantedInstance && hasControls(entry));
+  return row ? controlsOf(row) : null;
+};
+
+/** The environment with saved controls laid over it. A null environment stays null. */
+export const withSavedRuntimeControls = (environment, controls) => {
+  if (!environment || typeof environment !== 'object' || !controls) return environment;
+  return { ...environment, ...controls };
+};
+
+/** True only when the device listed its effort levels and this one is not among them. */
+export const effortRefusedByDevice = (inventory, effort) => Boolean(effort)
+  && Array.isArray(inventory?.efforts) && inventory.efforts.length > 0
+  && !inventory.efforts.includes(effort);

package/src/lib/seat-stop.js

@@ -0,0 +1,97 @@
+/**
+ * How `agent run` stops on a signal while supervised process groups may be
+ * live (see @commonlyai/seats/process-group).
+ *
+ * SIGTERM keeps the in-flight turn: the run loop stops polling and lets the
+ * turn finish. A launchd seat is SIGKILLed ExitTimeOut seconds after SIGTERM,
+ * and that SIGKILL cannot be caught, so a supervised group (outside the seat's
+ * own group, which launchd kills) would outlive the seat. So on a launchd
+ * seat, SIGTERM also arms a deadline a margin before ExitTimeOut, and the exit
+ * path kills whatever groups are left when the turn ends first.
+ *
+ * The deadline is armed only when the seat's plist exists. A seat without one
+ * (the daemon spawns it) is stopped with SIGTERM and never SIGKILLed, so it
+ * relies on the exit path alone, and a reassignment or config change does not
+ * cut the in-flight turn.
+ *
+ * ExitTimeOut is read from the seat's plist and never written. In a plist that
+ * exists, an unset, zero or unreadable value is launchd's default of 20 s,
+ * because launchd will SIGKILL that seat.
+ */
+import { spawnSync } from 'child_process';
+import { existsSync, readFileSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+import { armSupervisedGroupDeadline, killSupervisedGroups } from '@commonlyai/seats/process-group';
+
+export const DEFAULT_EXIT_TIMEOUT_S = 20;
+const MAX_MARGIN_MS = 5000;
+// `@` joins an agent and its instance in a second instance's key (F306).
+const SEAT_NAME = /^[A-Za-z0-9][A-Za-z0-9._@-]*$/;
+
+/** The seat's launchd plist path, or null for a name that cannot be a file name. */
+export const seatPlistPath = (name, home = homedir()) => (typeof name === 'string' && SEAT_NAME.test(name)
+  ? join(home, 'Library', 'LaunchAgents', `me.commonly.seat-${name}.plist`)
+  : null);
+
+const positive = (value) => (Number.isFinite(value) && value > 0 ? value : null);
+
+/**
+ * ExitTimeOut in seconds, or null when the plist is missing, has none, or
+ * holds a value launchd would not use as a timeout. An XML plist is read
+ * directly; a binary one through `plutil -extract` (read-only).
+ */
+export const readExitTimeOut = (path, { readFile = readFileSync, run = spawnSync } = {}) => {
+  if (!path) return null;
+  let raw;
+  try { raw = readFile(path); } catch { return null; }
+  const text = Buffer.isBuffer(raw) ? raw.toString('utf8') : String(raw);
+  if (text.startsWith('bplist')) {
+    try {
+      const out = run('plutil', ['-extract', 'ExitTimeOut', 'raw', '-o', '-', path], { encoding: 'utf8', timeout: 5000 });
+      return out.status === 0 ? positive(Number(String(out.stdout).trim())) : null;
+    } catch { return null; }
+  }
+  const match = /<key>\s*ExitTimeOut\s*<\/key>\s*<(integer|real)>\s*([0-9.]+)\s*<\/\1>/.exec(text);
+  return match ? positive(Number(match[2])) : null;
+};
+
+/**
+ * Whether the seat's plist exists, and its ExitTimeOut (null when unset or
+ * unreadable). Only an existing plist means launchd will SIGKILL this seat.
+ */
+export const readSeatPlist = (path, { exists = existsSync, ...deps } = {}) => {
+  if (!path || !exists(path)) return { present: false, exitTimeOut: null };
+  return { present: true, exitTimeOut: readExitTimeOut(path, deps) };
+};
+
+/** Milliseconds after SIGTERM to kill the groups: ExitTimeOut less a margin of 5 s or a quarter, whichever is less. */
+export const groupKillDeadlineMs = (exitTimeOutS) => {
+  const totalMs = (positive(exitTimeOutS) ?? DEFAULT_EXIT_TIMEOUT_S) * 1000;
+  return Math.floor(totalMs - Math.min(MAX_MARGIN_MS, totalMs / 4));
+};
+
+/**
+ * `requestStop(signal)` stops the run loop and, on SIGTERM to a seat with a
+ * plist, arms the group deadline; `onExit` kills the groups left at exit.
+ * `deps` is a test seam.
+ */
+export const createSeatStop = ({ name, stop, home, deps = {} } = {}) => {
+  const {
+    arm = armSupervisedGroupDeadline,
+    kill = killSupervisedGroups,
+    readPlist = readSeatPlist,
+  } = deps;
+  return {
+    requestStop(signal) {
+      stop();
+      if (signal !== 'SIGTERM') return null;
+      const plist = readPlist(seatPlistPath(name, home));
+      if (!plist.present) return null;
+      const deadlineMs = groupKillDeadlineMs(plist.exitTimeOut);
+      arm(deadlineMs);
+      return deadlineMs;
+    },
+    onExit() { kill(); },
+  };
+};

package/src/lib/server-skills.js

@@ -0,0 +1,32 @@
+// Agent-scoped catalog skills arrive from Commonly at each turn start. The
+// wrapper gives their instructions to either adapter as prompt text, so a
+// browser add/remove changes the next spawn without touching local files.
+const MAX_BYTES = 64 * 1024;
+const PREAMBLE = 'Installed skills for this agent and pod. Follow the applicable instructions below.';
+const FRONTMATTER = /^---\r?\n[\s\S]*?\r?\n---[ \t]*\r?\n?/;
+
+export const compileServerSkills = (items = []) => {
+  const sections = [];
+  const mounted = [];
+  const conflicted = [];
+  let bytes = Buffer.byteLength(PREAMBLE);
+  for (const item of items) {
+    const name = String(item?.name || '').replace(/[\r\n]/g, ' ').trim();
+    const content = String(item?.content || '').replace(FRONTMATTER, '').trim();
+    if (!name || !content) continue;
+    const section = `## Skill: ${name}\n\n${content}`;
+    const nextBytes = Buffer.byteLength(section) + 2;
+    if (bytes + nextBytes > MAX_BYTES) {
+      conflicted.push(name);
+      continue;
+    }
+    sections.push(section);
+    mounted.push(name);
+    bytes += nextBytes;
+  }
+  return {
+    text: sections.length ? `${PREAMBLE}\n\n${sections.join('\n\n')}` : null,
+    mounted,
+    conflicted,
+  };
+};

package/src/lib/session-recycle.js

@@ -0,0 +1,219 @@
+/**
+ * At-wake session recycle (TASK-440).
+ *
+ * A seat resumes its CLI session on every wake, so a long-lived seat drags a
+ * large cold context into each turn. When a wake finds the seat idle long
+ * enough that the prompt cache is cold AND the last session's context is big
+ * enough to matter, start a fresh session instead, seeded with a short
+ * restart note. Otherwise resume exactly as before.
+ *
+ * F392: a seat woken every few minutes is never idle long enough for that
+ * rule, so its context grew without bound. Past a hard ceiling it starts fresh
+ * whatever the idle time.
+ *
+ * Thresholds are per-install: COMMONLY_SESSION_RECYCLE_IDLE_MINUTES,
+ * COMMONLY_SESSION_RECYCLE_CONTEXT_TOKENS and
+ * COMMONLY_SESSION_RECYCLE_MAX_CONTEXT_TOKENS override the defaults below.
+ *
+ * Context size is what the last model request of the turn was sent: claude and
+ * codex from the transcript the child CLI wrote, under the env it ran with; pi
+ * and dsh from the usage on their own JSON stream (F404). An adapter that
+ * reports nothing keeps resuming, as before this module existed.
+ */
+
+import {
+  closeSync, existsSync, fstatSync, openSync, readdirSync, readSync,
+} from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+export const RECYCLE_DEFAULTS = Object.freeze({
+  idleMinutes: 60,
+  contextTokens: 128000,
+  maxContextTokens: 256000,
+});
+
+// Read this many bytes from the end of a transcript. The last assistant
+// usage record sits near the end; a full read of a long-lived transcript
+// would cost more than the recycle saves.
+const TRANSCRIPT_TAIL_BYTES = 4 * 1024 * 1024;
+
+const positiveNumber = (raw, fallback) => {
+  const value = Number(raw);
+  return Number.isFinite(value) && value > 0 ? value : fallback;
+};
+
+export const recycleThresholds = (env = process.env) => ({
+  idleMinutes: positiveNumber(env.COMMONLY_SESSION_RECYCLE_IDLE_MINUTES, RECYCLE_DEFAULTS.idleMinutes),
+  contextTokens: positiveNumber(env.COMMONLY_SESSION_RECYCLE_CONTEXT_TOKENS, RECYCLE_DEFAULTS.contextTokens),
+  maxContextTokens: positiveNumber(env.COMMONLY_SESSION_RECYCLE_MAX_CONTEXT_TOKENS, RECYCLE_DEFAULTS.maxContextTokens),
+});
+
+// Pure decision: 'cold' (idle long enough AND large), 'size' (past the hard
+// ceiling, however recent), or null to resume. No evidence (no last turn, no
+// measured context) means resume.
+export const recycleReason = ({
+  lastTurn,
+  contextTokens,
+  now = Date.now(),
+  thresholds = RECYCLE_DEFAULTS,
+}) => {
+  if (!lastTurn || !Number.isFinite(contextTokens)) return null;
+  const last = Date.parse(lastTurn);
+  if (!Number.isFinite(last)) return null;
+  if (now - last >= thresholds.idleMinutes * 60_000 && contextTokens >= thresholds.contextTokens) return 'cold';
+  const ceiling = thresholds.maxContextTokens ?? RECYCLE_DEFAULTS.maxContextTokens;
+  return contextTokens >= ceiling ? 'size' : null;
+};
+
+export const shouldStartFreshSession = (args) => recycleReason(args) !== null;
+
+export const idleMinutesSince = (lastTurn, now = Date.now()) => {
+  const last = Date.parse(lastTurn);
+  return Number.isFinite(last) ? Math.floor((now - last) / 60_000) : null;
+};
+
+// The restart note. The memory head and the pod focus are NOT repeated here:
+// a fresh claude session already receives the full long_term memory through
+// its preamble, and the pod focus is already in the wake prompt.
+export const buildRecycleBriefing = ({
+  agentName, reason = 'cold', idleMinutes, contextTokens, maxContextTokens = RECYCLE_DEFAULTS.maxContextTokens,
+}) => [
+  '=== Session restart ===',
+  reason === 'size'
+    ? `This wake starts a fresh session. The previous session had grown to about ${contextTokens}`
+      + ` context tokens, past the ${maxContextTokens}-token ceiling, so it was not resumed.`
+    : `This wake starts a fresh session. The previous session was idle ${idleMinutes} min`
+      + ` with about ${contextTokens} context tokens, so it was not resumed.`,
+  `Role: ${agentName}. Your saved memory and the pod focus follow below.`,
+].join('\n');
+
+// The config dir the CHILD claude process uses. A public seat runs claude
+// under an isolated HOME, so reading the operator's ~/.claude would find no
+// transcript and the recycle would never fire.
+export const claudeConfigDirFor = (env = process.env) => (
+  env?.CLAUDE_CONFIG_DIR || join(env?.HOME || homedir(), '.claude')
+);
+
+// Claude Code stores a session at
+// <config>/projects/<cwd with every non-alphanumeric character as '-'>/<id>.jsonl
+export const claudeTranscriptPath = ({ cwd, sessionId, configDir = claudeConfigDirFor() }) => {
+  if (!cwd || !sessionId) return null;
+  const encoded = cwd.replace(/[^a-zA-Z0-9]/g, '-');
+  return join(configDir, 'projects', encoded, `${sessionId}.jsonl`);
+};
+
+const readTail = (file) => {
+  const fd = openSync(file, 'r');
+  try {
+    const size = fstatSync(fd).size;
+    const length = Math.min(size, TRANSCRIPT_TAIL_BYTES);
+    const buffer = Buffer.alloc(length);
+    readSync(fd, buffer, 0, length, size - length);
+    return buffer.toString('utf8');
+  } finally {
+    closeSync(fd);
+  }
+};
+
+// Context tokens of the most recent assistant turn: uncached input plus the
+// cache creation and cache read that make up the prompt sent that turn.
+export const contextTokensFromTranscript = (text) => {
+  const lines = text.split('\n');
+  for (let index = lines.length - 1; index >= 0; index -= 1) {
+    const line = lines[index].trim();
+    if (!line) continue;
+    let record;
+    try {
+      record = JSON.parse(line);
+    } catch {
+      continue; // the first line of a tail read can be cut mid-record
+    }
+    const usage = record?.message?.usage;
+    if (record?.type === 'assistant' && usage && typeof usage === 'object') {
+      return (usage.input_tokens || 0)
+        + (usage.cache_creation_input_tokens || 0)
+        + (usage.cache_read_input_tokens || 0);
+    }
+  }
+  return null;
+};
+
+/**
+ * The prompt one request was sent, from a usage block that counts cached tokens
+ * apart from `input` (pi's message usage, dsh's step usage). Null when `input`
+ * is missing, so a stream without usage reads as unknown, not as zero.
+ */
+export const promptTokens = ({ input, cacheRead, cacheWrite } = {}) => {
+  if (!Number.isFinite(input)) return null;
+  return input + (Number.isFinite(cacheRead) ? cacheRead : 0) + (Number.isFinite(cacheWrite) ? cacheWrite : 0);
+};
+
+// F404. codex keeps a session as <home>/sessions/YYYY/MM/DD/rollout-<time>-<id>.jsonl,
+// dated by when it began; `exec resume` appends to that same file. Newest day
+// first, so a live session is found after a few directory reads.
+const newestFirst = (dir) => {
+  try {
+    return readdirSync(dir).sort().reverse();
+  } catch {
+    return [];
+  }
+};
+
+export const codexHomeFor = (env = process.env) => env?.CODEX_HOME || join(env?.HOME || homedir(), '.codex');
+
+export const codexRolloutPath = ({ codexHome = codexHomeFor(), sessionId }) => {
+  if (!sessionId) return null;
+  const root = join(codexHome, 'sessions');
+  const suffix = `-${sessionId}.jsonl`;
+  for (const year of newestFirst(root)) {
+    for (const month of newestFirst(join(root, year))) {
+      for (const day of newestFirst(join(root, year, month))) {
+        const name = newestFirst(join(root, year, month, day)).find((file) => file.endsWith(suffix));
+        if (name) return join(root, year, month, day, name);
+      }
+    }
+  }
+  return null;
+};
+
+// The last request's prompt from codex's own `token_count` record. Its
+// `input_tokens` already includes the cached part (`cached_input_tokens` is a
+// subset), and `last_token_usage` is one request, where `total_token_usage` and
+// the stream's `turn.completed` sum every request in the turn.
+export const contextTokensFromCodexRollout = (text) => {
+  const lines = text.split('\n');
+  for (let index = lines.length - 1; index >= 0; index -= 1) {
+    const line = lines[index].trim();
+    if (!line || !line.includes('token_count')) continue;
+    let record;
+    try {
+      record = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    const input = record?.payload?.type === 'token_count'
+      ? record.payload.info?.last_token_usage?.input_tokens : undefined;
+    if (Number.isFinite(input)) return input;
+  }
+  return null;
+};
+
+export const codexContextTokens = ({ codexHome = codexHomeFor(), sessionId }) => {
+  try {
+    const file = codexRolloutPath({ codexHome, sessionId });
+    return file ? contextTokensFromCodexRollout(readTail(file)) : null;
+  } catch {
+    return null;
+  }
+};
+
+export const claudeContextTokens = ({ cwd, sessionId, configDir = claudeConfigDirFor() }) => {
+  const file = claudeTranscriptPath({ cwd, sessionId, configDir });
+  if (!file || !existsSync(file)) return null;
+  try {
+    return contextTokensFromTranscript(readTail(file));
+  } catch {
+    return null;
+  }
+};

package/src/lib/session-store.js

@@ -0,0 +1,215 @@
+/**
+ * Session store — per-(agent, pod) session IDs at ~/.commonly/sessions/<agent>.json.
+ *
+ * Used by the local-CLI wrapper driver (ADR-005). Wrapped CLIs that support
+ * conversation session IDs (claude --session-id, codex --session, …) call
+ * getSession / setSession around each spawn so the next turn continues where
+ * the previous one left off.
+ *
+ * One file per agent so two `commonly agent run` processes for different
+ * agents never race on the same file (ADR-005 §Spawning semantics permits
+ * parallel agents). Shape on disk:
+ *   {
+ *     "<podId>": { "sessionId": "abc123", "lastTurn": "2026-04-14T18:00:00Z" }
+ *   }
+ *
+ * CLIs without sessions simply never call setSession — getSession returns null.
+ *
+ * Handled runtime-event IDs are intentionally persisted in a separate
+ * `<agent>.events.json` file. Keeping the bounded event ring separate means
+ * session-map readers retain their existing on-disk shape while a wrapper
+ * restart can still suppress a re-delivered event whose ack previously failed.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync, rmSync, renameSync, chmodSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+const sessionsDir = () => join(homedir(), '.commonly', 'sessions');
+const sessionsFile = (agentName) => join(sessionsDir(), `${agentName}.json`);
+const handledEventsFile = (agentName) => join(sessionsDir(), `${agentName}.events.json`);
+const noticesFile = (agentName) => join(sessionsDir(), `${agentName}.notices.json`);
+const MAX_HANDLED_EVENTS = 500;
+const handledEventsCache = new Map();
+
+// Everything under ~/.commonly is private (D275). These files hold per-(agent,
+// pod) session IDs and event rings; keep the dir and its files owner-only, and
+// tighten an existing dir or file that a pre-0.1.309 CLI left group/world-
+// readable. A mode arg applies only when the path is created, so each write
+// chmods after — the same belt-and-braces config.js uses for the token file.
+const ensureSessionsDir = () => {
+  const dir = sessionsDir();
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 });
+  try { chmodSync(dir, 0o700); } catch { /* a dir we don't own: leave it */ }
+  return dir;
+};
+
+const writeSessionFile = (file, data) => {
+  writeFileSync(file, data, { encoding: 'utf8', mode: 0o600 });
+  try { chmodSync(file, 0o600); } catch { /* best effort to tighten an existing file */ }
+};
+
+const readAgent = (agentName) => {
+  const file = sessionsFile(agentName);
+  if (!existsSync(file)) return {};
+  try {
+    return JSON.parse(readFileSync(file, 'utf8'));
+  } catch {
+    return {};
+  }
+};
+
+const writeAgent = (agentName, state) => {
+  ensureSessionsDir();
+  writeSessionFile(sessionsFile(agentName), JSON.stringify(state, null, 2));
+};
+
+const readHandledEvents = (agentName) => {
+  const file = handledEventsFile(agentName);
+  if (!existsSync(file)) return [];
+  try {
+    const parsed = JSON.parse(readFileSync(file, 'utf8'));
+    if (!Array.isArray(parsed)) return [];
+    return parsed
+      .filter((eventId) => typeof eventId === 'string' && eventId.length > 0)
+      .slice(-MAX_HANDLED_EVENTS);
+  } catch {
+    return [];
+  }
+};
+
+const getHandledEvents = (agentName) => {
+  const file = handledEventsFile(agentName);
+  // Tests, detach, or an operator may remove the file while this process is
+  // alive. Reset the mirror rather than retaining IDs that no longer exist on
+  // disk; a fresh process likewise hydrates from the persisted ring.
+  if (!existsSync(file)) {
+    const empty = { ids: [], set: new Set() };
+    handledEventsCache.set(agentName, empty);
+    return empty;
+  }
+  if (!handledEventsCache.has(agentName)) {
+    const ids = readHandledEvents(agentName);
+    handledEventsCache.set(agentName, { ids, set: new Set(ids) });
+  }
+  return handledEventsCache.get(agentName);
+};
+
+const writeHandledEvents = (agentName, ids) => {
+  ensureSessionsDir();
+  writeSessionFile(handledEventsFile(agentName), JSON.stringify(ids, null, 2));
+};
+
+export const getSession = (agentName, podId, { binding = null } = {}) => {
+  if (!agentName || !podId) return null;
+  const entry = readAgent(agentName)[podId];
+  if (binding !== null && entry?.binding !== binding) return null;
+  return entry?.sessionId || null;
+};
+
+// The whole per-pod entry (sessionId, lastTurn, contextTokens), for the
+// at-wake recycle decision. getSession stays the resume-only reader.
+export const getSessionEntry = (agentName, podId, { binding = null } = {}) => {
+  if (!agentName || !podId) return null;
+  const entry = readAgent(agentName)[podId];
+  if (!entry || (binding !== null && entry.binding !== binding)) return null;
+  return entry;
+};
+
+// Read-only diagnostic projection used by the daemon operator surface. A
+// wrapper may serve several pods, so return the newest completed turn.
+export const getLastTurn = (agentName) => {
+  if (!agentName) return null;
+  const state = readAgent(agentName);
+  return Object.values(state)
+    .map((entry) => entry?.lastTurn)
+    .filter((value) => typeof value === 'string')
+    .sort()
+    .at(-1) || null;
+};
+
+export const setSession = (agentName, podId, sessionId, { binding = null, contextTokens = null } = {}) => {
+  if (!agentName || !podId) return;
+  const state = readAgent(agentName);
+  state[podId] = {
+    sessionId,
+    lastTurn: new Date().toISOString(),
+    ...(binding !== null ? { binding } : {}),
+    ...(Number.isFinite(contextTokens) ? { contextTokens } : {}),
+  };
+  writeAgent(agentName, state);
+};
+
+// One pod's session, for a thread that can't be resumed any more.
+export const clearSession = (agentName, podId) => {
+  if (!agentName || !podId) return;
+  const state = readAgent(agentName);
+  if (!(podId in state)) return;
+  delete state[podId];
+  writeAgent(agentName, state);
+};
+
+export const wasEventHandled = (agentName, eventId) => {
+  if (!agentName || !eventId) return false;
+  return getHandledEvents(agentName).set.has(String(eventId));
+};
+
+export const recordHandledEvent = (agentName, eventId) => {
+  if (!agentName || !eventId) return;
+  const normalizedId = String(eventId);
+  const current = getHandledEvents(agentName);
+  if (current.set.has(normalizedId)) return;
+
+  const ids = [...current.ids, normalizedId].slice(-MAX_HANDLED_EVENTS);
+  writeHandledEvents(agentName, ids);
+  handledEventsCache.set(agentName, { ids, set: new Set(ids) });
+};
+
+// F178: when the wrapper last posted a rate-limited pod notice, by key, so a
+// notice is not repeated every turn and a restarted seat remembers it.
+// Shape on disk: { "<key>": "<ISO time>" }.
+const readNotices = (agentName) => {
+  const file = noticesFile(agentName);
+  if (!existsSync(file)) return {};
+  try {
+    const parsed = JSON.parse(readFileSync(file, 'utf8'));
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+};
+
+/** True when no notice under `key` was recorded within the last `windowMs`. */
+export const noticeDue = (agentName, key, windowMs, now = Date.now()) => {
+  if (!agentName || !key) return false;
+  const last = Date.parse(readNotices(agentName)[key]);
+  return !Number.isFinite(last) || now - last >= windowMs || last > now;
+};
+
+export const recordNotice = (agentName, key, now = Date.now()) => {
+  if (!agentName || !key) return;
+  const state = readNotices(agentName);
+  state[key] = new Date(now).toISOString();
+  ensureSessionsDir();
+  // Temp file then rename, so a crash mid-write never leaves a torn file, and
+  // 0600 because the record says which models this seat's key cannot use.
+  const file = noticesFile(agentName);
+  const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    writeFileSync(tmp, JSON.stringify(state, null, 2), { encoding: 'utf8', mode: 0o600 });
+    renameSync(tmp, file);
+  } catch (error) {
+    rmSync(tmp, { force: true });
+    throw error;
+  }
+};
+
+export const clearSessions = (agentName) => {
+  const file = sessionsFile(agentName);
+  if (existsSync(file)) rmSync(file);
+  const eventsFile = handledEventsFile(agentName);
+  if (existsSync(eventsFile)) rmSync(eventsFile);
+  const notices = noticesFile(agentName);
+  if (existsSync(notices)) rmSync(notices);
+  handledEventsCache.delete(agentName);
+};