cortico 0.1.0

package/src/core/markers.ts

@@ -0,0 +1,48 @@
+/**
+ * 模型上下文中的结构标记，用于缺失、截断、不可用或中断的内容。
+ * 标记使用英文，不受控制台语言设置影响；语义说明由 Persona 提供。
+ */
+
+/** 工具回执被折叠(见 truncate.ts 的 FOLD_THRESHOLD) */
+export const FOLD_PLACEHOLDER = '[result folded]';
+/** 调用入参被折叠 */
+export const FOLD_ARGS_PLACEHOLDER = '[arguments folded]';
+/** 单条越过整份预算,整条换成记号 */
+export const OVERSIZE_PLACEHOLDER = '[turn too long, omitted]';
+
+/** 配对修复:重建后调用还开着,补一条回执 */
+export const MISSING_RESULT = '[result missing]';
+/** 进程重启后，为未完成的调用补充缺失回执。 */
+export const MISSING_RESULT_RESTART = '[result missing (process restart)]';
+/** 主线程调用仍在执行时，fork 快照中的临时回执。 */
+export const PENDING_IN_MAIN_THREAD = '[result pending in the main thread]';
+
+/** 工具名不在本 session 的工具表里 */
+export const UNKNOWN_TOOL = '[unknown tool]';
+/** fork 调用了当前工具表中不存在的名称。 */
+export const forkUnknownTool = (name: string): string =>
+  `[unknown tool ${name}] This thread wires a subset of the tools. Use the ones listed above.`;
+
+/** 上游把这次调用标成未完成(流被截断),参数不可信,不执行 */
+export const NOT_EXECUTED_INCOMPLETE = '[not executed: function call incomplete]';
+/** 屏障工具(barrierAfter)之后同一条消息里的调用 */
+export const NOT_EXECUTED_BARRIER = '[not executed: review the preceding tool result first]';
+/** fork 已结束，同一条消息中后续的调用不执行。 */
+export const NOT_EXECUTED_THREAD_ENDED = '[not executed: this thread already ended]';
+/** 流在响应中途断了,提前派发的调用没跑完 */
+export const NOT_EXECUTED_STREAM_ABORTED = '[not executed: stream aborted mid-response]';
+/** 主循环已停 */
+export const NOT_EXECUTED_LOOP_STOPPED = '[not executed: main loop stopped]';
+/** 关机打断了这一轮,回执取不回来了 */
+export const SHUTDOWN_INTERRUPTED = '[tool result unavailable: shutdown interrupted the round]';
+
+/** 工具失败的模型可见标记；结构化失败状态使用 ToolOutcome.failed。 */
+export const toolFailed = (detail: string): string => `[tool failed] ${detail}`;
+/** 参数不是合法 JSON:不进 handler,就地失败 */
+export const TOOL_FAILED_BAD_ARGS = toolFailed('arguments are not valid JSON');
+
+/** 合成投递帧的表头(见 loop.ts 的 EXTERNAL_EVENT_FRAME) */
+export const eventFrameHeader = (count: number): string =>
+  `[${count} new event${count === 1 ? '' : 's'}]`;
+/** 读取投递帧正文时使用，需与写入的表头一致。 */
+export const EVENT_FRAME_HEADER_RE = /^\[\d+ new events?\]\n?/;

package/src/core/prefix.ts

@@ -0,0 +1,121 @@
+/**
+ * Assembles the main-session system prefix from Persona.systemSegments().
+ * World environment text is rendered from templates and supplied to that hook.
+ * Core joins the returned segments in order; their text remains opaque to Core.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { renderTemplate } from './template.ts';
+import type {
+  World,
+  WorldPrefixContext,
+  Persona,
+  PrefixSegment,
+  PromptDocDecl,
+} from './types.ts';
+
+export interface AssembleSystemDeps {
+  persona: Persona;
+  worlds: World[];
+  now: Date;
+  timezone: string;
+  /** 找环境提示词覆盖的两个目录。缺席(测试、预建实例)= 只用 World 自带的模板。 */
+  dirs?: EnvPromptDirs;
+}
+
+/**
+ * World 环境模板按以下顺序覆盖，同名文件整份替换：
+ * src/worlds/<id>/ENV_PROMPT.md → <代码包>/worlds/<id>/ENV_PROMPT.md
+ * → <部署>/worlds/<id>/ENV_PROMPT.md。
+ * 部署文件不进版本控制；控制台仅写入部署覆盖，删除后回退到代码包或 World 模板。
+ */
+export interface EnvPromptDirs {
+  /** bot 代码包目录。 */
+  packageDir?: string;
+  /** 部署目录。 */
+  deploymentDir?: string;
+}
+
+/** 某一层里这个 World 的覆盖文件路径:`<dir>/worlds/<Worldid>/ENV_PROMPT.md`。 */
+export function envPromptOverridePath(dir: string, worldId: string): string {
+  return join(dir, 'worlds', worldId, 'ENV_PROMPT.md');
+}
+
+/** World 环境提示词模板此刻读哪份文件。自后向前找第一份存在的。 */
+export function envPromptTemplateSource(
+  doc: PromptDocDecl,
+  worldId: string,
+  dirs: EnvPromptDirs | undefined,
+): { path: string; origin: EnvPromptOrigin } {
+  for (const [dir, origin] of [
+    [dirs?.deploymentDir, 'deployment'],
+    [dirs?.packageDir, 'package'],
+  ] as const) {
+    if (!dir) continue;
+    const override = envPromptOverridePath(dir, worldId);
+    if (existsSync(override)) return { path: override, origin };
+  }
+  return { path: doc.path, origin: 'module' };
+}
+
+export type EnvPromptOrigin = 'deployment' | 'package' | 'module';
+
+/** 按 role=envPrompt 查找模板声明；未声明时不提供环境前缀。 */
+export function envPromptDocOf(mod: World): PromptDocDecl | undefined {
+  let decl;
+  try {
+    decl = mod.console?.();
+  } catch {
+    return undefined; // 控制台声明异常时省略该 World 的模板。
+  }
+  return decl?.promptDocs?.find((doc) => doc.role === 'envPrompt');
+}
+
+/** 读取模板并代入 World 当前值；前缀组装与控制台预览共用。 */
+export async function renderWorldEnvPrompt(
+  mod: World,
+  dirs?: EnvPromptDirs,
+): Promise<{ text: string; sourceKey?: string }> {
+  // null 表示省略整段，不读取模板。
+  const vars = await mod.envPromptVars();
+  const doc = vars === null ? undefined : envPromptDocOf(mod);
+  if (!doc) return { text: '' };
+  const { path } = envPromptTemplateSource(doc, mod.id, dirs);
+  const text = renderTemplate(readFileSync(path, 'utf8'), vars ?? {}).trim();
+  // 空段不提供模板编辑来源。
+  return text ? { text, sourceKey: doc.key } : { text: '' };
+}
+
+/** 环境模板提供 World 的前缀文本；工具 description 随工具定义发送。 */
+export async function collectWorldContexts(
+  worlds: World[],
+  dirs?: EnvPromptDirs,
+): Promise<WorldPrefixContext[]> {
+  const sorted = [...worlds].sort((a, b) => a.id.localeCompare(b.id));
+  return Promise.all(
+    sorted.map(async (mod) => {
+      const { text, sourceKey } = await renderWorldEnvPrompt(mod, dirs);
+      return {
+        id: mod.id,
+        envPrompt: text,
+        ...(sourceKey ? { sourceKey } : {}),
+      };
+    }),
+  );
+}
+
+/** 供控制台观察:前缀的分段视图(与实际发出的前缀同一来源) */
+export async function assembleSystemSegments(deps: AssembleSystemDeps): Promise<PrefixSegment[]> {
+  const { persona, worlds, now, timezone, dirs } = deps;
+  return persona.systemSegments({
+    now,
+    timezone,
+    worlds: await collectWorldContexts(worlds, dirs),
+  });
+}
+
+/** 按顺序直接拼接各段，分隔符由 Persona 的段文本提供。 */
+export async function assembleSystem(deps: AssembleSystemDeps): Promise<string> {
+  const segments = await assembleSystemSegments(deps);
+  return segments.map((segment) => segment.text).join('');
+}

package/src/core/run.ts

@@ -0,0 +1,95 @@
+/**
+ * 一次进程运行对应一个 run，运行日志保存在 data/runs/<run>/。
+ * index.jsonl 在启动与正常关机时各追加一行；暂停沿用 run，重启创建新 run。
+ */
+import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { nowIso } from './util.ts';
+
+export interface RunInfo {
+  id: string;
+  dir: string;
+  runsDir: string;
+  startedAt: string;
+  previousRun: string | null;
+}
+
+export interface RunOpenMeta {
+  timezone: string;
+  bot: string;
+  repoRoot?: string;
+}
+
+export interface RunCloseSummary {
+  endedAt: string;
+  lastCursor: number;
+  /** 关机步骤是否全部完成。 */
+  complete: boolean | null;
+  reason: string;
+}
+
+const RUN_ID = /^r-\d{8}-\d{6}-[0-9a-f]{4}$/;
+
+export function runsDirOf(dataDir: string): string {
+  return join(dataDir, 'runs');
+}
+
+/** 已存在的 run id,按时间升序(id 自带时间戳,字典序即时间序)。 */
+export function listRuns(dataDir: string): string[] {
+  const dir = runsDirOf(dataDir);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir).filter((name) => RUN_ID.test(name)).sort();
+}
+
+function gitSha(repoRoot: string | undefined): string | null {
+  if (!repoRoot) return null;
+  try {
+    const head = readFileSync(join(repoRoot, '.git', 'HEAD'), 'utf8').trim();
+    if (!head.startsWith('ref:')) return head.slice(0, 12);
+    const ref = head.slice(4).trim();
+    const refFile = resolve(repoRoot, '.git', ref);
+    if (existsSync(refFile)) return readFileSync(refFile, 'utf8').trim().slice(0, 12);
+    const packed = join(repoRoot, '.git', 'packed-refs');
+    if (!existsSync(packed)) return null;
+    for (const line of readFileSync(packed, 'utf8').split('\n')) {
+      const [sha, name] = line.trim().split(' ');
+      if (name === ref) return sha.slice(0, 12);
+    }
+  } catch {
+    // 不在 git 仓库里就不记
+  }
+  return null;
+}
+
+/** 生成 run id、建目录、在 index.jsonl 记一行开机。 */
+export function openRun(dataDir: string, meta: RunOpenMeta): RunInfo {
+  const runsDir = runsDirOf(dataDir);
+  mkdirSync(runsDir, { recursive: true });
+  const previous = listRuns(dataDir);
+  const startedAt = nowIso(meta.timezone);
+  const stamp = startedAt.slice(0, 19).replace(/[-:T]/g, '');
+  const id = `r-${stamp.slice(0, 8)}-${stamp.slice(8, 14)}-${randomBytes(2).toString('hex')}`;
+  const dir = join(runsDir, id);
+  mkdirSync(dir, { recursive: true });
+  const previousRun = previous.length ? previous[previous.length - 1] : null;
+  appendFileSync(join(runsDir, 'index.jsonl'), JSON.stringify({
+    run: id,
+    startedAt,
+    bot: meta.bot,
+    pid: process.pid,
+    gitSha: gitSha(meta.repoRoot),
+    previousRun,
+  }) + '\n', 'utf8');
+  return { id, dir, runsDir, startedAt, previousRun };
+}
+
+/** 追加关机记录；进程异常结束时可能没有该行，查询方需从已有记录推算结束时间。 */
+export function closeRun(run: RunInfo, summary: RunCloseSummary): void {
+  appendFileSync(join(run.runsDir, 'index.jsonl'), JSON.stringify({ run: run.id, ...summary }) + '\n', 'utf8');
+}
+
+/** run.json 保存本次运行的 World 清单与配置指纹。 */
+export function writeRunJson(run: RunInfo, data: Record<string, unknown>): void {
+  writeFileSync(join(run.dir, 'run.json'), JSON.stringify({ run: run.id, startedAt: run.startedAt, previousRun: run.previousRun, ...data }, null, 2), 'utf8');
+}

package/src/core/secrets.ts

@@ -0,0 +1,18 @@
+/** 按名称同步读取密钥；可轮换凭据的生命周期由 provider 管理。 */
+import { existsSync } from 'node:fs';
+import { readTextFile } from './util.ts';
+
+/**
+ * 每次优先读取非空进程环境变量；否则使用首次读取后缓存的文件内容，缺失返回空串。
+ * 文件值读取到首个空白字符，不解析引号。
+ */
+export function secretReader(file: string): (name: string) => string {
+  let text: string | null = null;
+  return (name: string): string => {
+    const fromEnv = process.env[name];
+    if (fromEnv) return fromEnv;
+    if (text === null) text = existsSync(file) ? readTextFile(file) : '';
+    const m = new RegExp(`^\\s*${name}\\s*=\\s*(\\S+)`, 'm').exec(text);
+    return m ? m[1] : '';
+  };
+}

package/src/core/session.ts

@@ -0,0 +1,56 @@
+/** Session context is append-only between lifecycle resets. */
+import { join } from 'node:path';
+import type { ContextRecord } from '../protocol/open-responses/context.ts';
+import { ContextLog } from '../protocol/open-responses/context-log.ts';
+import { estimateMessagesTokens } from './util.ts';
+
+
+export class SessionLog {
+  private readonly context: ContextLog;
+  get records(): readonly ContextRecord[] { return this.context.records; }
+  private appendListeners: Array<(msg: ContextRecord, index: number) => void> = [];
+  private resetListeners: Array<(messages: ContextRecord[]) => void> = [];
+
+  /** stamp:入库时刻的来源(config 时区的 ISO);不给则消息不带 ts */
+  constructor(
+    dataDir: string,
+    fileName = 'session-main.jsonl',
+    stamp?: () => string,
+  ) {
+    this.context = new ContextLog(join(dataDir, fileName), stamp);
+  }
+
+  /** 每次 append 后通知 Web 调试监听器;监听器异常与会话写入隔离。 */
+  onAppend(cb: (msg: ContextRecord, index: number) => void): void {
+    this.appendListeners.push(cb);
+  }
+
+  /** 截断/重置后回调(整个数组被替换) */
+  onReset(cb: (messages: ContextRecord[]) => void): void {
+    this.resetListeners.push(cb);
+  }
+
+  append(msg: ContextRecord): void {
+    this.context.append(msg);
+    const stored = this.records[this.records.length - 1];
+    for (const cb of this.appendListeners) {
+      try { cb(stored, this.records.length - 1); } catch { /* 观察者异常不影响主流程 */ }
+    }
+  }
+
+  load(): void { this.context.load(); }
+
+  /** 整体替换：先写临时文件，再 rename 覆盖目标文件。 */
+  reset(messages: readonly ContextRecord[]): void {
+    this.context.reset(messages);
+    for (const cb of this.resetListeners) {
+      try { cb([...this.records]); } catch { /* 观察者异常不影响主流程 */ }
+    }
+  }
+
+  estTokens(): number {
+    return estimateMessagesTokens(this.records);
+  }
+
+
+}

package/src/core/sessions.ts

@@ -0,0 +1,261 @@
+import type { ContextRecord } from '../protocol/open-responses/context.ts';
+import type { ProviderAttempt } from './generation.ts';
+import { usageCounters } from '../protocol/open-responses/context-helpers.ts';
+/**
+ * 控制台使用的 session 统计与消息引用，注册表仅驻留内存。
+ * role 使用 Persona 声明的 session id；open 返回的实例 id 也传给模型调用。
+ * 消息通过保存的引用在读取时序列化；重启清空统计。
+ */
+import type { LLMUsage, UsageRecord } from './types.ts';
+import { nowIso } from './util.ts';
+
+export interface SessionStats {
+  id: string;
+  /** session声明id(Persona定义的不透明字符串) */
+  role: string;
+  label: string;
+  startedAt: string;
+  /** null=进行中 */
+  endedAt: string | null;
+  /** LLM调用次数 */
+  calls: number;
+  promptTokens: number;
+  completionTokens: number;
+  cacheHitTokens: number;
+  cacheMissTokens: number;
+  reasoningTokens: number;
+  /** 缓存命中率估算 = hit/(hit+miss);无输入数据为null */
+  cacheHitRate: number | null;
+  /** 当前消息条数(引用实时读) */
+  messageCount: number;
+}
+
+export interface SessionHandle {
+  recordAttempts(attempts: readonly ProviderAttempt[], messagesRef?: ContextRecord[], extra?: { prefixHash?: string; outcome?: 'discarded' }): void;
+  /** 本次 session 实例的 id；常驻 session 使用声明 id，临时 fork 使用运行期序号。 */
+  id: string;
+  /** 累计用量，可更新消息数组引用。model 用于持久化归因；extra 提供前缀指纹和费用记录。 */
+  record(
+    usage: LLMUsage,
+    messagesRef?: ContextRecord[],
+    model?: string,
+    extra?: { prefixHash?: string; charges?: import('./generation.ts').Charge[] },
+  ): void;
+  /** 关闭 session；重复调用无效。 */
+  close(): void;
+}
+
+interface Entry {
+  stats: Omit<SessionStats, 'cacheHitRate' | 'messageCount'>;
+  messagesRef: (() => readonly ContextRecord[]) | null;
+  /** 用固定id注册的常驻session:结束后也不从仪表里清掉 */
+  pinned: boolean;
+}
+
+/** 已结束session最多保留条数(临时session的近期历史,防内存膨胀) */
+const CLOSED_KEEP = 8;
+
+export class SessionTracker {
+  private readonly timezone: string;
+  private readonly onRecord?: (rec: UsageRecord) => void;
+  private readonly entries = new Map<string, Entry>();
+  private readonly listeners: Array<() => void> = [];
+  private seq = 0;
+
+  /** onRecord=每次record时把一条持久化流水交出去(UsageLog.append),可选 */
+  constructor(timezone: string, onRecord?: (rec: UsageRecord) => void) {
+    this.timezone = timezone;
+    this.onRecord = onRecord;
+  }
+
+  /** 变化通知(open/record/close都触发;web侧接这里做推送) */
+  onChange(cb: () => void): void {
+    this.listeners.push(cb);
+  }
+
+  /**
+   * 注册一个session。opts.id指定固定id(常驻session用它的声明id);
+   * opts.messagesRef=消息数组的惰性引用(查看消息流/条数用)。
+   */
+  open(
+    role: string,
+    label: string,
+    opts?: { id?: string; messagesRef?: () => readonly ContextRecord[] },
+  ): SessionHandle {
+    const id = opts?.id ?? `${role}-${++this.seq}`;
+    const entry: Entry = {
+      stats: {
+        id,
+        role,
+        label,
+        startedAt: nowIso(this.timezone),
+        endedAt: null,
+        calls: 0,
+        promptTokens: 0,
+        completionTokens: 0,
+        cacheHitTokens: 0,
+        cacheMissTokens: 0,
+        reasoningTokens: 0,
+      },
+      messagesRef: opts?.messagesRef ?? null,
+      pinned: opts?.id !== undefined,
+    };
+    this.entries.set(id, entry);
+    this.pruneClosed();
+    this.emit();
+
+    let closed = false;
+    return {
+      id,
+      recordAttempts: (attempts, messagesRef, extra) => {
+        if (messagesRef) entry.messagesRef = () => messagesRef;
+        for (const source of attempts) {
+          const attempt = structuredClone(source);
+          if (extra?.outcome === 'discarded' && (attempt.outcome === 'completed' || attempt.outcome === 'incomplete')) attempt.outcome = 'discarded';
+          const usage = usageCounters(attempt.meters);
+          const stats = entry.stats;
+          stats.calls++;
+          stats.promptTokens += usage.promptTokens;
+          stats.completionTokens += usage.completionTokens;
+          stats.cacheHitTokens += usage.cacheHitTokens;
+          stats.cacheMissTokens += usage.cacheMissTokens;
+          stats.reasoningTokens += usage.reasoningTokens ?? 0;
+          this.onRecord?.({ version: 2, attempt, ts: nowIso(this.timezone, new Date(attempt.startedAt)), sessionId: id,
+            role: stats.role, label: stats.label, model: attempt.origin.model, ...usage, reasoningTokens: usage.reasoningTokens ?? 0,
+            failedAfterMs: attempt.elapsedMs, ...(attempt.requestId ? { requestId: attempt.requestId } : {}),
+            ...(attempt.status !== null ? { status: attempt.status } : {}),
+            ...(attempt.outcome === 'completed' || attempt.outcome === 'incomplete' ? {} : { outcome: attempt.outcome === 'discarded' ? 'discarded' : 'failed' }),
+            ...(extra?.prefixHash ? { prefixHash: extra.prefixHash } : {}),
+          });
+        }
+        this.emit();
+      },
+      record: (
+        usage: LLMUsage,
+        messagesRef?: ContextRecord[],
+        model?: string,
+        extra?: { prefixHash?: string; charges?: import('./generation.ts').Charge[] },
+      ) => {
+        if (closed) return;
+        const s = entry.stats;
+        s.calls++;
+        s.promptTokens += usage.promptTokens;
+        s.completionTokens += usage.completionTokens;
+        s.cacheHitTokens += usage.cacheHitTokens;
+        s.cacheMissTokens += usage.cacheMissTokens;
+        s.reasoningTokens += usage.reasoningTokens ?? 0;
+        if (messagesRef) entry.messagesRef = () => messagesRef;
+        if (this.onRecord) {
+          try {
+            this.onRecord({
+              ts: nowIso(this.timezone),
+              sessionId: id,
+              role: s.role,
+              label: s.label,
+              model: model ?? '',
+              promptTokens: usage.promptTokens,
+              completionTokens: usage.completionTokens,
+              cacheHitTokens: usage.cacheHitTokens,
+              cacheMissTokens: usage.cacheMissTokens,
+              reasoningTokens: usage.reasoningTokens ?? 0,
+              ...(extra?.prefixHash ? { prefixHash: extra.prefixHash } : {}),
+              ...(extra?.charges ? { charges: structuredClone(extra.charges) } : {}),
+            });
+          } catch {
+            // 持久化观察失败不改变session本身的运行状态。
+          }
+        }
+        this.emit();
+      },
+      close: () => {
+        if (closed) return;
+        closed = true;
+        entry.stats.endedAt = nowIso(this.timezone);
+        this.pruneClosed();
+        this.emit();
+      },
+    };
+  }
+
+  /** 全部session统计(进行中在前,新的在前) */
+  list(): SessionStats[] {
+    const out: SessionStats[] = [];
+    for (const e of this.entries.values()) {
+      const s = e.stats;
+      const denom = s.cacheHitTokens + s.cacheMissTokens;
+      out.push({
+        ...s,
+        cacheHitRate: denom > 0 ? s.cacheHitTokens / denom : null,
+        messageCount: this.countMessages(e),
+      });
+    }
+    return out.sort((a, b) => {
+      const ra = a.endedAt === null ? 0 : 1;
+      const rb = b.endedAt === null ? 0 : 1;
+      if (ra !== rb) return ra - rb;
+      return b.startedAt.localeCompare(a.startedAt);
+    });
+  }
+
+  /**
+   * 统计清零(web运维动作):进行中的session保留条目但usage归零、
+   * 计时重置(句柄继续有效);已结束的条目移除。
+   */
+  reset(): void {
+    for (const [id, e] of [...this.entries]) {
+      if (e.stats.endedAt !== null) {
+        this.entries.delete(id);
+        continue;
+      }
+      e.stats.calls = 0;
+      e.stats.promptTokens = 0;
+      e.stats.completionTokens = 0;
+      e.stats.cacheHitTokens = 0;
+      e.stats.cacheMissTokens = 0;
+      e.stats.reasoningTokens = 0;
+      e.stats.startedAt = nowIso(this.timezone);
+    }
+    this.emit();
+  }
+
+  /** 某session当前消息流(引用实时序列化);未知id或无引用→null */
+  messages(id: string): readonly ContextRecord[] | null {
+    const e = this.entries.get(id);
+    if (!e?.messagesRef) return null;
+    try {
+      return e.messagesRef();
+    } catch {
+      return null;
+    }
+  }
+
+
+  private countMessages(e: Entry): number {
+    if (!e.messagesRef) return 0;
+    try {
+      return e.messagesRef().length;
+    } catch {
+      return 0;
+    }
+  }
+
+  /** 已结束session只留最近CLOSED_KEEP个(按结束时间;常驻条目永不清) */
+  private pruneClosed(): void {
+    const closed = [...this.entries.values()]
+      .filter((e) => e.stats.endedAt !== null && !e.pinned)
+      .sort((a, b) => (b.stats.endedAt ?? '').localeCompare(a.stats.endedAt ?? ''));
+    for (const e of closed.slice(CLOSED_KEEP)) {
+      this.entries.delete(e.stats.id);
+    }
+  }
+
+  private emit(): void {
+    for (const cb of this.listeners) {
+      try {
+        cb();
+      } catch {
+        /* 观察者异常不影响主流程 */
+      }
+    }
+  }
+}