agent-accelerator 0.5.7 → 0.5.8

package/src/scheduler/store.ts

@@ -1,18 +1,21 @@
 /**
  * Disk layer for scheduled actions. Everything lives under one home folder:
  *
- *   <home>/scheduled_actions/tasks.json         every action, one file
- *   <home>/scheduled_actions/deliveries.json    saved results waiting for their delivery time
- *   <home>/scheduled_actions/<id>/<date>.md     one file per run
+ *   <home>/scheduled/<id>/task.json             the action (`{ version: 2, task }`)
+ *   <home>/scheduled/<id>/delivery.json         its saved results waiting for their delivery time (`{ version: 2, pending }`)
+ *   <home>/scheduled/<id>/<date>.md             one file per run
+ *   <home>/scheduled/<id>/.mutex                short lock held while this action's files change
+ *   <home>/scheduled/<id>/.heartbeat            written while a process is running the action (pid, host; its mtime is refreshed)
  *
- * The files are the source of truth: every write re-reads first (never writes
- * from a stale copy) and goes through `writeFileDurable` (temp file, fsync, `.bak`, rename).
- * Sync `fs`, like the session store.
+ * One folder per action, so processes working on different actions never touch the same file. The files are the
+ * source of truth: every change takes the action's mutex, re-reads first (never writes from a stale copy) and goes
+ * through `writeFileDurable` (temp file, fsync, `.bak`, rename). Sync `fs`, like the session store.
  */
 import * as fs from "node:fs";
+import * as os from "node:os";
 import * as path from "node:path";
 import { z } from "zod";
-import { readWithBackup, writeFileDurable } from "../utils/durable.ts";
+import { readWithBackup, withFileMutex, writeFileDurable } from "../utils/durable.ts";
 import { telemetryBus } from "../telemetry.ts";
 import { resolveHome } from "../utils/home.ts";
 export { resolveHome };
@@ -26,10 +29,10 @@ export const TASK_ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 /** 48-char slug + `-` + 6 random chars. */
 export const MAX_TASK_ID_LENGTH = 55;
 
-/** A saved run waiting for its delivery time (one entry of `deliveries.json`). */
+/** A saved run waiting for its delivery time (one entry of an action's `delivery.json`). */
 export interface PendingDelivery {
   id: string;
-  /** Run file path, relative to `scheduled_actions/`. */
+  /** Run file path, relative to `scheduled/`. */
   file: string;
   status: ScheduledRunStatus;
   readyAt: string;
@@ -72,34 +75,105 @@ export interface RunHeader {
   error?: string;
 }
 
-// The `scheduled_actions` folder of a home; in: the path helpers, out: its path.
-const baseDir = (home: string): string => path.join(home, "scheduled_actions");
-// Path of tasks.json; in: readTasks/updateTasks, out: its path.
-const tasksFile = (home: string): string => path.join(baseDir(home), "tasks.json");
-// Path of deliveries.json; in: readDeliveries/updateDeliveries, out: its path.
-const deliveriesFile = (home: string): string => path.join(baseDir(home), "deliveries.json");
+// The `scheduled` folder of a home; in: the path helpers, out: its path.
+const baseDir = (home: string): string => path.join(home, "scheduled");
 
-/** Absolute path of a run file given its `scheduled_actions/`-relative path. */
-export function runPath(home: string, relativeFile: string): string {
-  return path.resolve(baseDir(home), relativeFile);
+// The folder of one action; refuses anything that is not an action id, so a hand-edited id can never point outside `scheduled/`; in: every per-action helper, out: its path.
+function taskDir(home: string, id: string): string {
+  if (typeof id !== "string" || !TASK_ID_PATTERN.test(id) || id.length > MAX_TASK_ID_LENGTH) {
+    throw new ValidationError(`${JSON.stringify(id)} is not a scheduled action id.`);
+  }
+  return path.join(baseDir(home), id);
+}
+// Path of an action's record; in: the task helpers, out: its path.
+const taskFile = (dir: string): string => path.join(dir, "task.json");
+// Path of an action's saved deliveries; in: the delivery helpers, out: its path.
+const deliveryFile = (dir: string): string => path.join(dir, "delivery.json");
+// Path of the short mutex that serialises every change to one action (record and deliveries); in: updateTask/updateDeliveries/deleteTask, out: its path.
+const mutexFile = (dir: string): string => path.join(dir, ".mutex");
+
+// Path of the file a running action's owner keeps fresh; in: the heartbeat helpers, out: its path.
+const heartbeatFile = (dir: string): string => path.join(dir, ".heartbeat");
+
+/** Who is running an action and how long ago they last said so. */
+export interface Heartbeat {
+  pid: number;
+  host: string;
+  /** Identifies the scheduler instance inside that process. */
+  token: string;
+  ageMs: number;
+}
+
+/** Marks an action as running in this process (pid, host, token); written before the record flips to `cooking`; in: startCook, out: `<id>/.heartbeat`. */
+export function writeHeartbeat(home: string, id: string, token: string): void {
+  fs.writeFileSync(heartbeatFile(taskDir(home, id)), JSON.stringify({ pid: process.pid, host: os.hostname(), token }), { mode: 0o600 });
+}
+
+/** Refreshes the heartbeat's modification time; false when the file is gone; in: the scheduler tick for each run in flight. */
+export function touchHeartbeat(home: string, id: string): boolean {
+  try {
+    const now = new Date();
+    fs.utimesSync(heartbeatFile(taskDir(home, id)), now, now);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** The heartbeat of an action, or undefined when it has none or the file is unreadable; in: the dead-owner checks and `delete`. */
+export function readHeartbeat(home: string, id: string): Heartbeat | undefined {
+  try {
+    const file = heartbeatFile(taskDir(home, id));
+    const raw = JSON.parse(fs.readFileSync(file, "utf8")) as Partial<Heartbeat>;
+    if (typeof raw.pid !== "number" || typeof raw.host !== "string" || typeof raw.token !== "string") return undefined;
+    return { pid: raw.pid, host: raw.host, token: raw.token, ageMs: Date.now() - fs.statSync(file).mtimeMs };
+  } catch {
+    return undefined;
+  }
 }
 
-/** Renames the pre-0.5.0 `scheduled_tasks/` folder to `scheduled_actions/` (once, only when the new one does not exist). */
-export function migrateLegacyFolder(home: string): void {
-  const legacy = path.join(home, "scheduled_tasks");
+/** Removes the heartbeat when a run ends; in: the scheduler after a run, out: nothing. */
+export function clearHeartbeat(home: string, id: string): void {
   try {
-    if (fs.existsSync(legacy) && !fs.existsSync(baseDir(home))) fs.renameSync(legacy, baseDir(home));
+    fs.rmSync(heartbeatFile(taskDir(home, id)), { force: true });
   } catch {
-    // why: best effort; the old folder simply stays where it is.
+    // why: a leftover heartbeat of a finished run is harmless (it is only read for actions that are cooking).
   }
 }
 
+// True for the error of a folder that was removed while we waited for its lock; in: the catch blocks of the mutating helpers, out: a boolean.
+const isMissingFolder = (err: unknown): boolean => (err as { code?: string } | null)?.code === "ENOENT";
+
+// Deletes the leftover temp files of a task.json / delivery.json write that never finished (a killed process); only called while holding the action's mutex, which is what makes it safe (run files are written outside the mutex, so they are never touched); in: the three mutating helpers, out: nothing.
+function sweepShardTemps(dir: string): void {
+  try {
+    for (const name of fs.readdirSync(dir)) if (/^(task|delivery)\.json\.tmp-\d+-[0-9a-z]+$/.test(name)) fs.rmSync(path.join(dir, name), { force: true });
+  } catch {
+    // why: an unreadable folder or an undeletable leftover is harmless.
+  }
+}
+
+/** Absolute path of a run file given its `scheduled/`-relative path. */
+export function runPath(home: string, relativeFile: string): string {
+  return path.resolve(baseDir(home), relativeFile);
+}
+
 type Raw = Record<string, unknown>;
 
-// Parses a `{ version, <key>: [...] }` file into its object entries; undefined when the text is not that shape; in: raw file text, out: readList.
-function parseList(text: string, key: "tasks" | "pending"): Raw[] | undefined {
+// Parses `{ version, task: {...} }` into the record; undefined when the text is not that shape; in: readShard, out: the record.
+function parseTask(text: string): Raw | undefined {
   try {
-    const list = (JSON.parse(text) as Raw | null)?.[key];
+    const task = (JSON.parse(text) as Raw | null)?.["task"];
+    return task && typeof task === "object" && !Array.isArray(task) ? (task as Raw) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+// Parses `{ version, pending: [...] }` into its object entries; undefined when the text is not that shape; in: readShard, out: the entries.
+function parsePending(text: string): Raw[] | undefined {
+  try {
+    const list = (JSON.parse(text) as Raw | null)?.["pending"];
     if (!Array.isArray(list)) return undefined;
     return list.filter((x): x is Raw => !!x && typeof x === "object" && !Array.isArray(x));
   } catch {
@@ -108,21 +182,21 @@ function parseList(text: string, key: "tasks" | "pending"): Raw[] | undefined {
 }
 
 /**
- * Reads a `{ version, <key>: [...] }` file. Missing = empty. A damaged file is renamed `*.corrupt-<ts>`; if its `.bak`
- * (the last good version) is valid it is restored, else the list starts empty.
+ * Reads one JSON file of an action. Missing = undefined. A damaged file is renamed `*.corrupt-<ts>`; if its `.bak`
+ * (the last good version) is valid it is restored and returned, else undefined (the action is treated as absent).
  */
-function readList(file: string, key: "tasks" | "pending"): Raw[] {
-  const read = readWithBackup(file, (t) => parseList(t, key) !== undefined);
-  if (!read) return [];
-  const list = parseList(read.text, key);
-  if (list && !read.fromBackup) return list;
+function readShard<T>(file: string, parse: (text: string) => T | undefined): T | undefined {
+  const read = readWithBackup(file, (t) => parse(t) !== undefined);
+  if (!read) return undefined;
+  const value = parse(read.text);
+  if (value !== undefined && !read.fromBackup) return value;
   const moved = `${file}.corrupt-${Date.now()}`;
   try {
     fs.renameSync(file, moved);
   } catch {
     // why: quarantine is best-effort; the file is ignored either way.
   }
-  if (list) {
+  if (value !== undefined) {
     try {
       writeFileDurable(file, read.text, { backup: false }); // keep the good .bak where it is
     } catch {
@@ -131,41 +205,181 @@ function readList(file: string, key: "tasks" | "pending"): Raw[] {
   }
   telemetryBus.emitWarning(
     "scheduled_action.store_corrupt",
-    `[Agent Accelerator] ${path.basename(file)} is not valid; moved to ${path.basename(moved)} and ${list ? "restored from its backup" : "starting empty"}.`,
-    { file: moved, restored: !!list }
+    `[Agent Accelerator] ${path.relative(baseDir(path.dirname(path.dirname(file))), file)} is not valid; moved to ${path.basename(moved)} and ${value !== undefined ? "restored from its backup" : "ignored"}.`,
+    { file: moved, restored: value !== undefined }
   );
-  return list ?? [];
+  return value;
 }
 
-// Writes `{ version, <key>: [...] }` durably (with a .bak); in: updateTasks/updateDeliveries, out: the file.
-function writeList(file: string, key: "tasks" | "pending", list: Raw[]): void {
-  writeFileDurable(file, JSON.stringify({ version: 1, [key]: list }, null, 2) + "\n");
+// Names of the action folders of a home (every folder not starting with a dot), sorted; in: readTasks/readDeliveries, out: folder names.
+function actionFolders(home: string): string[] {
+  try {
+    return fs
+      .readdirSync(baseDir(home), { withFileTypes: true })
+      .filter((e) => e.isDirectory() && !e.name.startsWith("."))
+      .map((e) => e.name)
+      .sort();
+  } catch {
+    return [];
+  }
 }
 
-/** Every record as stored. Records may be invalid: check with {@link validateRecord} before acting on one. */
+/** Folder/id mismatches already reported, so a bad hand edit warns once per process. */
+const reportedMismatch = new Set<string>();
+// True when a record or delivery names the folder it sits in; otherwise warns once and says no; in: readTasks/readDeliveries, out: a boolean.
+function inOwnFolder(file: string, folder: string, id: unknown): boolean {
+  if (id === folder) return true;
+  const key = `${file}:${String(id)}`;
+  if (!reportedMismatch.has(key)) {
+    reportedMismatch.add(key);
+    telemetryBus.emitWarning(
+      "scheduled_action.invalid",
+      `[Agent Accelerator] ${folder}/${path.basename(file)} names the id ${JSON.stringify(id)} but sits in the folder "${folder}" and is skipped.`,
+      { id: String(id), problem: "id: does not match its folder", file: path.basename(file) }
+    );
+  }
+  return false;
+}
+
+// Orders records by creation time, then id, so listings are stable; in: readTasks, out: a comparison number.
+function byCreation(a: ScheduledActionRecord, b: ScheduledActionRecord): number {
+  return (a.createdAt ?? "").localeCompare(b.createdAt ?? "") || a.id.localeCompare(b.id);
+}
+
+/** One action as stored (`task.json`), or undefined when it does not exist or `id` is not an action id. May be invalid: check with {@link validateRecord}. */
+export function readTask(home: string, id: string): ScheduledActionRecord | undefined {
+  let dir: string;
+  try {
+    dir = taskDir(home, id);
+  } catch {
+    return undefined;
+  }
+  const raw = readShard(taskFile(dir), parseTask);
+  return raw && inOwnFolder(taskFile(dir), id, raw["id"]) ? (raw as unknown as ScheduledActionRecord) : undefined;
+}
+
+/** Every record as stored, oldest first. Records may be invalid: check with {@link validateRecord} before acting on one. */
 export function readTasks(home: string): ScheduledActionRecord[] {
-  return readList(tasksFile(home), "tasks") as unknown as ScheduledActionRecord[];
+  const out: ScheduledActionRecord[] = [];
+  for (const folder of actionFolders(home)) {
+    if (!TASK_ID_PATTERN.test(folder) || folder.length > MAX_TASK_ID_LENGTH) continue; // not an action folder
+    const rec = readTask(home, folder);
+    if (rec) out.push(rec);
+  }
+  return out.sort(byCreation);
+}
+
+/**
+ * Changes one action under its own short mutex: re-reads `task.json`, calls `fn` (which may mutate the record in place;
+ * it gets `undefined` when the action does not exist) and writes the record back if it changed. If `fn` throws nothing
+ * is written. Other actions are never locked, so processes working on different actions do not wait for each other.
+ */
+export function updateTask<T>(home: string, id: string, fn: (rec: ScheduledActionRecord | undefined) => T): T {
+  let dir: string;
+  try {
+    dir = taskDir(home, id);
+  } catch {
+    return fn(undefined); // not an action id: nothing to change
+  }
+  if (!fs.existsSync(dir)) return fn(undefined);
+  try {
+    return withFileMutex(mutexFile(dir), () => {
+      sweepShardTemps(dir);
+      const rec = readTask(home, id);
+      const before = rec ? JSON.stringify(rec) : "";
+      const result = fn(rec);
+      if (rec && JSON.stringify(rec) !== before) writeFileDurable(taskFile(dir), JSON.stringify({ version: 2, task: rec }, null, 2) + "\n");
+      return result;
+    });
+  } catch (err) {
+    if (!isMissingFolder(err)) throw err;
+    return fn(undefined); // another process deleted the action while we waited for its lock
+  }
 }
 
-/** Re-reads `tasks.json`, applies `fn` (mutating the array/records in place) and writes it back. */
-export function updateTasks<T>(home: string, fn: (tasks: ScheduledActionRecord[]) => T): T {
-  const tasks = readTasks(home);
-  const result = fn(tasks);
-  writeList(tasksFile(home), "tasks", tasks as unknown as Raw[]);
-  return result;
+/**
+ * Creates an action in a new folder. The folder is made with a create-only `mkdir`, so two processes can never take the
+ * same id; `nextId` is called again until a free one is found, then `build` makes the record for it.
+ */
+export function createTask(home: string, nextId: () => string, build: (id: string) => ScheduledActionRecord): ScheduledActionRecord {
+  fs.mkdirSync(baseDir(home), { recursive: true, mode: 0o700 });
+  for (let attempt = 0; attempt < 100; attempt++) {
+    const id = nextId();
+    const dir = taskDir(home, id);
+    try {
+      fs.mkdirSync(dir, { mode: 0o700 });
+    } catch (err) {
+      if ((err as { code?: string }).code === "EEXIST") continue;
+      throw err;
+    }
+    const rec = build(id);
+    withFileMutex(mutexFile(dir), () => {
+      sweepShardTemps(dir);
+      writeFileDurable(taskFile(dir), JSON.stringify({ version: 2, task: rec }, null, 2) + "\n");
+    });
+    return rec;
+  }
+  throw new ValidationError("Could not find a free scheduled action id.");
 }
 
-/** Every saved delivery as stored (entries may be invalid: check with validateDelivery); in: the scheduler, out: PendingDelivery[]. */
+/** Removes an action's record and saved deliveries (run files stay); true when there was something to remove. An emptied folder is removed too. */
+export function deleteTask(home: string, id: string): boolean {
+  const dir = taskDir(home, id);
+  if (!fs.existsSync(dir)) return false;
+  let removed: boolean;
+  try {
+    removed = withFileMutex(mutexFile(dir), () => {
+      const had = fs.existsSync(taskFile(dir)) || fs.existsSync(deliveryFile(dir));
+      for (const f of [taskFile(dir), deliveryFile(dir)]) fs.rmSync(f, { force: true }), fs.rmSync(`${f}.bak`, { force: true });
+      fs.rmSync(heartbeatFile(dir), { force: true });
+      return had;
+    });
+  } catch (err) {
+    if (isMissingFolder(err)) return false; // another process deleted it first
+    throw err;
+  }
+  try {
+    fs.rmdirSync(dir); // only succeeds when nothing is left in it
+  } catch {
+    // why: run files (or another process's new action) keep the folder.
+  }
+  return removed;
+}
+
+/** Every saved delivery of every action as stored, soonest first (entries may be invalid: check with validateDelivery). */
 export function readDeliveries(home: string): PendingDelivery[] {
-  return readList(deliveriesFile(home), "pending") as unknown as PendingDelivery[];
+  const out: PendingDelivery[] = [];
+  for (const folder of actionFolders(home)) {
+    if (!TASK_ID_PATTERN.test(folder) || folder.length > MAX_TASK_ID_LENGTH) continue;
+    const file = deliveryFile(taskDir(home, folder));
+    for (const entry of readShard(file, parsePending) ?? []) if (inOwnFolder(file, folder, entry["id"])) out.push(entry as unknown as PendingDelivery);
+  }
+  return out.sort((a, b) => String(a.deliverAt).localeCompare(String(b.deliverAt)));
 }
 
-/** Re-reads `deliveries.json`, applies `fn` (mutating in place) and writes it back. */
-export function updateDeliveries<T>(home: string, fn: (pending: PendingDelivery[]) => T): T {
-  const pending = readDeliveries(home);
-  const result = fn(pending);
-  writeList(deliveriesFile(home), "pending", pending as unknown as Raw[]);
-  return result;
+/** Changes the saved deliveries of ONE action under its short mutex (`fn` mutates the array in place); the file is removed when the list ends up empty. */
+export function updateDeliveries<T>(home: string, id: string, fn: (pending: PendingDelivery[]) => T): T {
+  const dir = taskDir(home, id);
+  for (let attempt = 1; ; attempt++) {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    try {
+      return withFileMutex(mutexFile(dir), () => {
+        sweepShardTemps(dir);
+        const file = deliveryFile(dir);
+        const pending = (readShard(file, parsePending) ?? []) as unknown as PendingDelivery[];
+        const result = fn(pending);
+        if (pending.length === 0) {
+          fs.rmSync(file, { force: true });
+          fs.rmSync(`${file}.bak`, { force: true });
+        } else {
+          writeFileDurable(file, JSON.stringify({ version: 2, pending }, null, 2) + "\n");
+        }
+        return result;
+      });
+    } catch (err) {
+      if (!isMissingFolder(err) || attempt >= 3) throw err; // the folder was removed between making it and locking it: make it again
+    }
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -224,7 +438,7 @@ const deliverySchema = z.object({
   late: z.boolean().optional(),
 });
 
-/** `undefined` when a `deliveries.json` entry is usable, else a one-line reason. Never throws. */
+/** `undefined` when a `delivery.json` entry is usable, else a one-line reason. Never throws. */
 export function validateDelivery(raw: unknown): string | undefined {
   const parsed = deliverySchema.safeParse(raw);
   return parsed.success ? undefined : parsed.error.issues.map((i) => `${i.path.join(".") || "entry"}: ${i.message}`).join("; ");
@@ -246,7 +460,7 @@ function renderRun(header: RunHeader, body: string): string {
 
 /**
  * Writes one run under its final name (`27-october-2026.md`, `-2`, `-3` on a
- * same-day clash) and returns its path relative to `scheduled_actions/`.
+ * same-day clash) and returns its path relative to `scheduled/`.
  */
 export function writeRunFile(home: string, id: string, deliverAt: Date, header: RunHeader, body: string): string {
   const dir = path.join(baseDir(home), id);
@@ -293,7 +507,7 @@ export function findRunFile(home: string, id: string, deliverAt: Date, startedAt
   return undefined;
 }
 
-/** Deletes an action's folder (`purge`). Only ever inside `scheduled_actions/`. */
+/** Deletes an action's folder (`purge`). Only ever inside `scheduled/`. */
 export function removeTaskFolder(home: string, id: string): void {
   const root = baseDir(home);
   const dir = path.resolve(root, id);

package/src/session/architecture.md

@@ -10,7 +10,7 @@ Saving a conversation, its spending and its tool logs.
 | `tool-log.ts` | `ToolLogs`: one fsynced NDJSON file per tool call under `<session>/tool-logs/`. |
 
 ## Invariants
-- Layout: `<home>/sessions/<id>/{session.json, journal.ndjson, media/, tool-logs/, workers/}`.
+- Layout: `<home>/sessions/<id>/{session.json, journal.ndjson, telemetry.ndjson, media/, tool-logs/, workers/}`. `telemetry.ndjson` is written by `telemetry-file.ts` (opt-in), not by the session code; a folder holding only that file is not a session.
 - A journal whose header epoch differs from the snapshot's is ignored on load.
 - Journal record types: `base`, `msg`, `meta`, `run`, `end`, `tool`, `pending`, `usage`. Replay ignores unknown types, drops a torn last line, and stops at earlier damage with `session.journal_corrupt`.
 - Media is content-addressed (`media/<kind>-h<hash>.<ext>`), written once, never deleted.

package/src/session/store.ts

@@ -166,7 +166,7 @@ function specFor(modelStr: string): ReturnType<typeof getModelFromCatalog> {
 }
 
 /** Context window for telemetry display. Falls back to 1M like the chat CLI.
- * @deprecated (Q-34) Kept for compat; new code should use
+ * @deprecated Kept for compat; new code should use
  * `getSessionContextWindowOrUndefined` and handle `undefined` explicitly.
  */
 export function getSessionContextWindow(modelStr: string): number {
@@ -575,7 +575,7 @@ function parseSession(raw: string, limits?: SessionLimits): PersistedAgentSessio
   const maxBytes = limits?.maxBytes ?? MAX_SESSION_JSON_BYTES;
   const text = (raw ?? "").trim();
   if (!text) return null;
-  // Q-10: oversized payloads are rejected, but flagged as over-limit (NOT corrupt).
+  // Oversized payloads are rejected, but flagged as over-limit (NOT corrupt).
   if (text.length > maxBytes) return OVER_LIMIT;
   try {
     // Legacy JSONL: lines shaped {type: session|mainModel|subagentModel|metrics|message|...}
@@ -626,7 +626,7 @@ function parseSession(raw: string, limits?: SessionLimits): PersistedAgentSessio
         }
       }
       if (!sessionId && messages.length === 0) return null;
-      // Q-10: oversize guard — flagged as over-limit, not corrupt.
+      // Oversize guard — flagged as over-limit, not corrupt.
       if (messages.length > maxMessages) return OVER_LIMIT;
       return {
         version: 1,
@@ -645,7 +645,7 @@ function parseSession(raw: string, limits?: SessionLimits): PersistedAgentSessio
     }
     const obj: any = JSON.parse(text);
     if (!obj || typeof obj !== "object") return null;
-    // Q-10: version check — reject unknown versions, accept legacy shapes
+    // Version check — reject unknown versions, accept legacy shapes
     // that predate versioning (no version field).
     if ("version" in obj && (obj as { version?: unknown }).version !== 1) return null;
     // Very old single-JSON shape without version: {sessionId, model, context:{messages}}
@@ -978,7 +978,7 @@ export function saveSessionDir(
   agent: SessionAgentLike,
   telemetry?: SessionTelemetry | SessionTotals | null
 ): string {
-  // Q-28-partial: sessionDirFor already enforces assertValidSessionId.
+  // sessionDirFor already enforces assertValidSessionId.
   const sessionDir = sessionDirFor(rootDir, agent.sessionId);
   try {
     fs.mkdirSync(sessionDir, { recursive: true });
@@ -1139,7 +1139,7 @@ export function findLatestSessionDir(rootDir: string): string | null {
 }
 
 // ---------------------------------------------------------------------------
-// Q-10: session validation (append-only; deserializeSession above only gained
+// Session validation (append-only; deserializeSession above only gained
 // size/version guards, no behavior change otherwise).
 // ---------------------------------------------------------------------------
 
@@ -1156,9 +1156,9 @@ function sessionLoadError(message: string): Error {
 }
 
 /**
- * Manual Zod-like validation for session snapshots (Q-10, no new deps).
+ * Manual Zod-like validation for session snapshots (no new deps).
  * Checks `version===1`, string `sessionId`, array `messages`, and oversize
- * (>5000 messages or >10MB JSON). Throws a `SessionLoadError`-named Error
+ * (more than `MAX_SESSION_MESSAGES` = 50,000 messages or `MAX_SESSION_JSON_BYTES` = 100 MB of JSON). Throws a `SessionLoadError`-named Error
  * on failure; returns the typed session on success.
  */
 export function validateSessionData(data: unknown): PersistedAgentSession {
@@ -1191,12 +1191,12 @@ export function validateSessionData(data: unknown): PersistedAgentSession {
 }
 
 // ---------------------------------------------------------------------------
-// Q-34: context-window lookup without the legacy 1M fallback.
+// Context-window lookup without the legacy 1M fallback.
 // ---------------------------------------------------------------------------
 
 /**
- * Returns the catalog context window for a model, or `undefined` when unknown
- * (Q-34). Prefer this over `getSessionContextWindow` for new code.
+ * Returns the catalog context window for a model, or `undefined` when unknown.
+ * Prefer this over `getSessionContextWindow` for new code.
  */
 export function getSessionContextWindowOrUndefined(modelStr: string): number | undefined {
   try {
@@ -1210,7 +1210,7 @@ export function getSessionContextWindowOrUndefined(modelStr: string): number | u
 }
 
 // ---------------------------------------------------------------------------
-// Q-41: telemetry bus lives in `../telemetry.ts` (dependency-free, so low-level
+// Telemetry bus lives in `../telemetry.ts` (dependency-free, so low-level
 // modules such as the catalog cache and event stream can emit without import
 // cycles). Re-exported here for backward compatibility.
 // ---------------------------------------------------------------------------
@@ -1218,7 +1218,7 @@ import { telemetryBus } from "../telemetry.ts";
 export { telemetryBus };
 export type { TelemetryEvent, TelemetryListener } from "../telemetry.ts";
 
-/** Reports a usage/cost anomaly via the global hook + telemetry bus (Q-35). Never logs. */
+/** Reports a usage/cost anomaly via the global hook + telemetry bus. Never logs. */
 export function reportUsageAnomaly(detail: { type: string; [k: string]: unknown }): void {
   try {
     (globalThis as unknown as { __agentAccelAnomaly?: (d: unknown) => void }).__agentAccelAnomaly?.(detail);
@@ -1233,10 +1233,10 @@ export function reportUsageAnomaly(detail: { type: string; [k: string]: unknown
 }
 
 // ---------------------------------------------------------------------------
-// Q-35: canonical usage invariants.
+// Canonical usage invariants.
 // ---------------------------------------------------------------------------
 /**
- * Canonical usage invariants (provider-agnostic, Q-35):
+ * Canonical usage invariants (provider-agnostic):
  * - all token counts are finite integers >= 0;
  * - `cachedTokens` / `cacheReadTokens` are a SUBSET of `inputTokens`
  *   (cache hits cannot exceed input; aggregates clamp — see `accumulateUsage`
@@ -1287,13 +1287,13 @@ export function assertUsageInvariants(usage: TokenUsage): void {
 }
 
 // ---------------------------------------------------------------------------
-// Q-36: one cost model — integer micro-USD accumulation.
+// One cost model — integer micro-USD accumulation.
 // ---------------------------------------------------------------------------
 
-/** Where a priced cost came from (Q-36). Unknown stays unknown, never 0. */
+/** Where a priced cost came from. Unknown stays unknown, never 0. */
 export type CostSource = "provider" | "catalog" | "unknown";
 
-/** Integer micro-USD breakdown behind a priced cost (Q-36). */
+/** Integer micro-USD breakdown behind a priced cost. */
 export interface CostBreakdown {
   inputMicroUSD: number;
   outputMicroUSD: number;
@@ -1315,7 +1315,7 @@ export type PricedCost = NonNullable<TokenUsage["cost"]> & {
 };
 
 /**
- * Service-tier price multipliers (Q-36). Aligned with pi
+ * Service-tier price multipliers. Aligned with pi
  * (`api/openai-responses.ts:387`): `flex` trades latency for ~0.5x price,
  * `priority`/`fast` reserve capacity at ~2x (`2.5x` for `gpt-5.5`).
  * Standard/default is 1.0. Estimates because vendors do not publish exact
@@ -1347,7 +1347,7 @@ function toDollars(microUSD: number): number {
 }
 
 /**
- * Resolves effective per-1M pricing for a usage snapshot (Q-36). When
+ * Resolves effective per-1M pricing for a usage snapshot. When
  * `usage.inputTokens > 200_000` and the catalog carries `cost.tiers` or
  * `cost.context_over_200k`, the over-200k tier prices apply; otherwise base
  * `pricing.*` (falling back to legacy `cost.*`) applies.
@@ -1404,7 +1404,7 @@ function resolveEffectivePricing(
 }
 
 /**
- * Prices one usage snapshot with integer micro-USD accumulation (Q-36).
+ * Prices one usage snapshot with integer micro-USD accumulation.
  *
  * - A provider-reported `usage.cost.totalCost` (a number, 0 included: free or cached) wins (source `provider`).
  * - Else catalog pricing via `resolveEffectivePricing` (source `catalog`).
@@ -1498,7 +1498,7 @@ export function priceUsage(
 }
 
 /**
- * Computes and attaches catalog pricing to a usage snapshot (Q-36).
+ * Computes and attaches catalog pricing to a usage snapshot.
  * Keeps provider-reported costs untouched; returns the cost (or undefined
  * when unknown). Never fabricates a 0 object for unknown pricing.
  */