cortico 0.1.0 → 0.1.2

package/README.md

@@ -15,8 +15,7 @@ import type { EventEnvelope, WorldHost } from 'cortico/core/types.ts';
 
 Inside a running instance those specifiers are resolved by the host's module hook to the
 framework that instance runs. This package supplies the same files to the editor, the type
-checker and the test runner before the extension is installed anywhere, which is the whole of
-what it does: it has no entry point and starts nothing.
+checker and the test runner. It has no entry point and starts nothing.
 
 ## Install
 
@@ -24,9 +23,9 @@ what it does: it has no entry point and starts nothing.
 pnpm add -D cortico
 ```
 
-The extension contract is API version 4; a package declares it as `"cortico": { "kind": ..., "api": 4 }`
-in its own `package.json`. This package's minor version tracks the framework, so pin the range
-your extension was written against.
+Each extension kind has its own contract version — world 5, provider 5, bot 5 — and a package
+declares its own as `"cortico": { "kind": "world", "api": 5 }` in its `package.json`. This
+package's minor version tracks the framework, so pin the range your extension was written against.
 
 `templates/extension/` in the repository holds a ready package for each kind, and
 [docs/extensions.md](https://github.com/Pal-AI-Lab/Cortico/blob/main/docs/extensions.md) states
@@ -34,14 +33,8 @@ the packaging rules.
 
 ## Running a bot
 
-Running Cortico itself means cloning the repository; deployments, bot packages and the web
-console live in the checkout.
-
-```bash
-git clone https://github.com/Pal-AI-Lab/Cortico.git
-cd Cortico
-corepack pnpm install
-pnpm start
-```
+Deployments, bot packages and the web console live in a checkout of the repository, which is
+where a bot runs from:
+[Quick Start](https://github.com/Pal-AI-Lab/Cortico#quick-start).
 
 MIT licensed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cortico",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "description": "A TypeScript framework for event-driven, long-running persona bots",
   "license": "MIT",
@@ -36,8 +36,6 @@
     "@types/express": "^4.17.21",
     "@types/ws": "^8.5.13",
     "express": "^4.21.2",
-    "fflate": "0.8.3",
-    "tar-stream": "3.2.1",
     "ws": "^8.18.0"
   }
 }

package/src/boot.ts

@@ -19,6 +19,14 @@ export function isSupervised(env: NodeJS.ProcessEnv = process.env): boolean {
   return env[SUPERVISED_ENV] === '1' || env[SUPERVISED_ENV] === 'true';
 }
 
+/**
+ * 启动时是否暂停事件投递。每一轮受监管的启动拿到同一份环境和同一串参数，
+ * 所以这个值也是重启后的状态。
+ */
+export function startsPaused(env: NodeJS.ProcessEnv = process.env, argv: readonly string[] = process.argv): boolean {
+  return env.CORTICO_START_PAUSED === '1' || env.CORTICO_START_PAUSED === 'true' || argv.includes('--paused');
+}
+
 function notifyLauncher(message: { type: string; dataDir?: string }, env = process.env): void {
   if (!isSupervised(env)) return;
   process.send?.(message);
@@ -44,3 +52,13 @@ export function consumeBootFlags(dataDir: string): void {
     }
   }
 }
+
+export function listensOnEveryInterface(bound: string | null): boolean {
+  return bound === '0.0.0.0' || bound === '::';
+}
+
+/** 本机打得开的控制台地址:监听所有网卡时给回环地址,IPv6 加方括号。 */
+export function consoleUrlOf(bound: string | null, port: number): string {
+  const host = bound === null || listensOnEveryInterface(bound) ? '127.0.0.1' : bound.includes(':') ? `[${bound}]` : bound;
+  return `http://${host}:${port}/`;
+}

package/src/bot.ts

@@ -19,7 +19,7 @@ import { coreConfigGroup } from './core/config.ts';
 import { pick, resolveLanguage, type Language } from './core/language.ts';
 import { updateJsonObject } from './config-file.ts';
 import { ONBOARDING_FLAG_FILE } from './deploy.ts';
-import { isSupervised, requestRestart } from './boot.ts';
+import { isSupervised, requestRestart, startsPaused } from './boot.ts';
 import { ExtensionManager, type ExtensionSet } from './extensions.ts';
 import { WorldAssembly, type WorldDefinition, type WorldDeclaration, type WorldSection } from './world.ts';
 import { Core, type WorldStopFailure } from './core/core.ts';
@@ -30,6 +30,7 @@ import { assembleSystemSegments, envPromptOverridePath, envPromptTemplateSource,
 import { aggregateUsage } from './core/cost.ts';
 import { nowIso, withDeadline } from './core/util.ts';
 import { closeRun } from './core/run.ts';
+import { ProviderHub } from './providers/console/hub.ts';
 import { ProviderSettings } from './providers/console/settings.ts';
 import { providerModules } from './providers/registry.ts';
 import { readGroupValues, setByPath as setConfigPath } from './core/config-schema.ts';
@@ -51,6 +52,9 @@ import {
   type ConsolePageContribution,
 } from './web/shared/console-protocol.ts';
 
+/** 控制台访问密码的密钥名;进程环境或部署 .env 里非空时优先于 web.password。 */
+export const WEB_PASSWORD_SECRET = 'CORTICO_WEB_PASSWORD';
+
 /** 启动器使用的 bot 包装配契约。 */
 export interface BotDefinition<C extends CoreConfig = CoreConfig> {
   /** 控制台页 id `persona:<id>` 与产物键取它;仓内包的 id 与目录同名。 */
@@ -166,7 +170,7 @@ const BOT_TEXT = {
       },
       session: {
         label: '主session(当前对话上下文)',
-        note: '清除对话上下文并重新开场，保留 Memory 和事件库。建议在空闲时操作',
+        note: '清除对话上下文并重新开场，保留 Memory 和事件库。正在处理批次时等该批结束后执行',
         stat: (records: number, ktok: number, size: string) => `${records}条 / ~${ktok}k tok / ${size}`,
         cleared: 'session已清空重开(system前缀+开场消息)',
       },
@@ -212,6 +216,12 @@ const BOT_TEXT = {
         stat: (n: number) => `${n}条待投递`,
         cleared: (n: number) => `已丢弃${n}条待投递事件`,
       },
+      media: {
+        label: '附件库(事件与工具回执里的图片、音频)',
+        note: '删除全部附件文件，保留引用它们的事件与 session 记录；删掉的附件在上下文里只剩文字说明',
+        stat: (n: number, size: string) => `${n}份 / ${size}`,
+        cleared: (n: number) => `已删除${n}份附件`,
+      },
     },
     config: {
       unknownGroup: (id: string) => `没有这一组配置: ${id}`,
@@ -260,7 +270,7 @@ const BOT_TEXT = {
       },
       session: {
         label: 'Main session (current conversation context)',
-        note: 'Clears the conversation and reopens the session, keeping Memory and the event store. Prefer clearing while idle',
+        note: 'Clears the conversation and reopens the session, keeping Memory and the event store. While a batch is in progress, runs after it finishes',
         stat: (records: number, ktok: number, size: string) => `${records} records / ~${ktok}k tok / ${size}`,
         cleared: 'Session cleared and reopened (system prefix + opening message)',
       },
@@ -306,6 +316,12 @@ const BOT_TEXT = {
         stat: (n: number) => `${n} pending`,
         cleared: (n: number) => `Discarded ${n} pending events`,
       },
+      media: {
+        label: 'Attachment store (images and audio from events and tool results)',
+        note: 'Deletes every attachment file and keeps the events and session records that reference them; a deleted attachment leaves only its text description in context',
+        stat: (n: number, size: string) => `${n} files / ${size}`,
+        cleared: (n: number) => `Deleted ${n} attachments`,
+      },
     },
     config: {
       unknownGroup: (id: string) => `No such config group: ${id}`,
@@ -466,6 +482,19 @@ function deriveStorage<C extends CoreConfig>(core: Core<C>, dataDir: string, lan
       // 保留延迟渲染项，其回调还负责复位 World 的排队状态。
       clear: () => s.pending.cleared(core.discardPendingEvents()),
     },
+    {
+      key: 'media',
+      label: s.media.label,
+      kind: 'disk',
+      location: 'data/media/',
+      danger: true,
+      note: s.media.note,
+      stat: () => {
+        const { count, bytes } = core.logBlobs.stat();
+        return s.media.stat(count, `${(bytes / 1024).toFixed(1)}KB`);
+      },
+      clear: () => s.media.cleared(core.logBlobs.clear()),
+    },
   ];
 }
 
@@ -867,7 +896,7 @@ export function deriveConsolePageSources(
   parts: { assembly: WorldAssembly; persona?: Persona },
   /**
    * bot 标识、展示名、Memory 名与配置组;配置组归入 Persona 页面。
-   * 展示名由部署配置提供；Persona 页标题取 Persona 的类名。
+   * 展示名是这一台 bot 的名字(底栏头像旁边那个),Persona 页的标题另取 Persona 的类名。
    */
   bot?: { id: string; label: string; memoryName?: string; configGroups?: readonly ConfigGroup[] },
 
@@ -990,6 +1019,7 @@ export function createBot<C extends CoreConfig>(
 
   // 共享端点配置位于部署根的 providers/；activeProvider 属于当前部署。
   const providerSettings = new ProviderSettings(cfg,core.providers,join(loaded.rootDir,'config.json'),loaded.providersDir ?? join(loaded.rootDir,'providers'));
+  const providerHub = new ProviderHub(cfg, core.providers, providerSettings, join(loaded.rootDir, 'config.json'), loaded.providersDir ?? join(loaded.rootDir, 'providers'));
   const allConfigGroups = (language: Language) => [...configGroups(language),...providerSettings.groups(language)];
   const llmManagers = new Map<string,{stop():Promise<unknown>}>([['providers',{stop:()=>core.providers.stopAll()}]]);
 
@@ -1058,6 +1088,9 @@ export function createBot<C extends CoreConfig>(
       dataDir: loaded.dataDir,
       botDir: loaded.rootDir,
       language,
+      ...(cfg.web.host ? { host: cfg.web.host } : {}),
+      allowedHosts: cfg.web.allowedHosts ?? [],
+      password: loaded.secret(WEB_PASSWORD_SECRET) || (cfg.web.password ?? ''),
       defaultScheme: cfg.web.theme,
       sessions: core.sessions,
       storage: consoleStorage,
@@ -1099,7 +1132,7 @@ export function createBot<C extends CoreConfig>(
           ? (language) => contribution.consolePages!({ storage: consoleStorage(language), language })
           : undefined,
       )(),...providerSettings.sources()],
-      providersLamp: (language) => providerSettings.providersLamp(language),
+      providers: providerHub,
       worldVisibility: {
         state: () => core.worldVisibility(),
         set: (id, visible, language) => {
@@ -1127,6 +1160,7 @@ export function createBot<C extends CoreConfig>(
           return beginShutdown('控制台重启键', { closeWeb: false, exit: true, language });
         },
         supervised: isSupervised(),
+        startsPaused: startsPaused(),
       },
       onboarding: {
         dismiss: () => { try { unlinkSync(join(loaded.rootDir, ONBOARDING_FLAG_FILE)); } catch { /* 已经删过 */ } },
@@ -1166,6 +1200,7 @@ export function createBot<C extends CoreConfig>(
       },
       getStatus: () => ({
         displayName: cfg.displayName,
+        modelConnection: providerHub.current(language),
         startedAt,
         loop: core.loop.getStatus(),
         eventCount: core.store.latestCursor(),
@@ -1199,7 +1234,7 @@ export function createBot<C extends CoreConfig>(
 
       const orphans = Object.entries(cfg.providers).filter(([, entry]) => !providerModules.some((m) => m.id === entry.kind)).map(([name, entry]) => `${name}(kind=${entry.kind})`);
       if (orphans.length) core.runlog.logger('provider').warn('端点条目没有对应的 Provider 模块,不可用', { orphans });
-      void core.providers.start(cfg.activeProvider).catch(error=>core.runlog.logger('provider').error('Provider 启动失败',{error:String(error)}));
+      if (cfg.activeProvider && cfg.providers[cfg.activeProvider]) void core.providers.start(cfg.activeProvider).catch(error=>core.runlog.logger('provider').error('Provider 启动失败',{error:String(error)}));
       await parts.onStart?.({ core, loaded, port });
       await core.start();
       return { port };

package/src/core/README.md

@@ -51,14 +51,16 @@ piggyback 只入队，随后续唤醒一起投递。
 更新后的值在下一次入队时参与计算。
 
 投递水位 `lastDeliveredCursor` 持久化，队列不持久化。重启时补投水位之后的外部事件；
-已被候选处理结果引用的原始归档不重复投递。内部事件仅在当次运行投递。
+已被候选处理结果引用的原始归档不重复投递。内部事件仅在当次运行投递。清空分片或跳过损坏行
+留下的游标空位没有可投递内容，不阻止水位推进。
 
 ## 主循环
 
 每次唤醒处理一批事件，可进行多轮模型调用。`SessionDecl.rounds()` 提供
 `{ soft, hard, softHint? }`：到 soft 轮时将 `softHint` 追加到最后一条工具回执；到 hard 轮时
 记录 warn 并结束本批。`endsTurn` 工具和自然结束共用结束处理；本批结束时尚未处理的事件
-退回总线，进入下一批。
+退回总线，进入下一批。控制台的前缀重载与清空 session 在批次边界执行：正在处理批次时等该批
+结束，空闲时立即；并发请求复用同一事务。
 
 状态 0、429 或 5xx 的模型调用失败，可保留已记录的输出和工具回执，按 `ResubmitPolicy` 重试。
 默认允许连续重试 2 次、每批最多 4 次，退避为 2 秒、10 秒；上下文超限、抢占、关机或轮数
@@ -77,12 +79,8 @@ handler 异常转为失败回执。流式生成时 `EagerDispatch` 可提前执
 `Persona.onHandoff(snapshot, { hardTokens })` 返回 `{ tail, trim? }`。Core 重建 system 前缀，
 按 `hardTokens − estimate(prefix)` 限制保留上下文，其中 prefix 包括 system 前缀和 Persona 的合成
 开头(`sessionHead()`)。Core 校验工具调用配对，并重置 session。
-合成开头每次请求现取，不写入持久 session；Core 不据此判定远端缓存是否命中。
 阶段预算与保留比例由 Persona 决定，模型配置来自当前 provider。
 
-存储清单使用 `StorageOwner` 标识 Core、Persona、Memory 与 World 的归属。
-页面组织和 Memory 展示名称由装配层处理。
-
 ## 错误隔离
 
 装配层将 World 构造失败限制在该 World。`start()` 抛错时不挂载；`stop()` 失败或超时会记录

package/src/core/blobs.ts

@@ -4,7 +4,7 @@
  * `mem:<后端标识>` 由 Persona 的 BlobStore 解析，后端决定标识格式。
  */
 import { createHash } from 'node:crypto';
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import type { BlobRef } from './types.ts';
 
@@ -58,7 +58,7 @@ export function withBlobLines(text: string, refs: readonly BlobRef[] | undefined
 }
 
 /**
- * 字节按内容哈希存入 data/media/，重复写入不增加副本；删除由运维处理。
+ * 字节按内容哈希存入 data/media/，重复写入不增加副本。
  * 读取接受完整句柄或唯一的十六进制前缀（至少 8 位）。
  */
 export class LogBlobStore {
@@ -81,6 +81,27 @@ export class LogBlobStore {
     return `${LOG_SCHEME}${name}`;
   }
 
+  /** 现存份数与占用字节;目录还没建时都是 0。 */
+  stat(): { count: number; bytes: number } {
+    if (!existsSync(this.dir)) return { count: 0, bytes: 0 };
+    const names = readdirSync(this.dir);
+    return { count: names.length, bytes: names.reduce((sum, name) => sum + statSync(join(this.dir, name)).size, 0) };
+  }
+
+  /**
+   * 删掉目录里的全部附件,返回删掉的份数。附件那一行正文在落库时已写定
+   * (句柄、mime 与 fallbackText),此后 read() 返回 null,投递时不再附字节。
+   */
+  clear(): number {
+    if (!existsSync(this.dir)) return 0;
+    let removed = 0;
+    for (const name of readdirSync(this.dir)) {
+      rmSync(join(this.dir, name), { force: true });
+      removed += 1;
+    }
+    return removed;
+  }
+
   /** 按句柄取回;句柄不合形状、前缀不唯一或文件不在了返回 null。 */
   read(handle: string): { bytes: Buffer; mime: string } | null {
     const name = this.resolveName(handle);

package/src/core/config-schema.ts

@@ -12,7 +12,7 @@ import type { CoreConfig } from './types.ts';
 import { pick, type Language } from './language.ts';
 
 export interface ConfigProperty {
-  type: 'integer' | 'number' | 'boolean' | 'string' | 'array';
+  type: 'integer' | 'number' | 'boolean' | 'string' | 'array' | 'object';
   title: string;
   description?: string;
   minimum?: number;

package/src/core/config.ts

@@ -1,6 +1,5 @@
 /** Core 默认配置与深合并工具。Persona 和 World 参数由各自声明，部署合并顺序见 src/deploy.ts。 */
 import type { CoreConfig } from './types.ts';
-import type { PriceDefinition } from '../providers/pricebook.ts';
 import type { ConfigGroup } from './config-schema.ts';
 import { pick, type Language } from './language.ts';
 
@@ -186,21 +185,8 @@ export const CORE_DEFAULTS = {
   /** 用于控制台标题和终端消息的发送方名称。 */
   displayName: 'Cortico Bot',
   timezone: 'Asia/Shanghai',
-  /** 默认端点；部署根 providers/ 中的同名端点配置覆盖此项。 */
-  providers: {
-    deepseek: {
-      kind: 'openai-responses-compat' as const,
-      baseUrl: 'https://api.deepseek.com',
-      secret: 'DEEPSEEK_API_KEY',
-      spec: { model: 'deepseek-flash', thinking: false },
-      // 默认价目为零；操作者可在控制台填写实际价格。
-      pricing: [{
-        models: ['*'], currency: 'USD', basis: 'marginal', source: 'console',
-        rules: [{ meter: 'cachedInput', perMillion: 0 }, { meter: 'uncachedInput', perMillion: 0 }, { meter: 'output', perMillion: 0 }],
-      }] as PriceDefinition[],
-    },
-  },
-  activeProvider: 'deepseek',
+  providers: {} as Record<string, import('./types.ts').LLMProviderEntry>,
+  activeProvider: '',
   web: { port: 7777, theme: 'mint' },
   paths: { memory: 'memory', data: 'data' },
   batching: { quietGapMs: 2500, minBatchAgeMs: 0, maxBatchAgeMs: 15000, maxBatchSize: 100 },

package/src/core/core.ts

@@ -32,7 +32,7 @@ import { SessionLog } from './session.ts';
 import { CoreState } from './state.ts';
 import { ProviderRegistry } from '../providers/registry.ts';
 import { runForkLoop } from './fork.ts';
-import { providerModule } from '../providers/registry.ts';
+import { providerModule, providerModules } from '../providers/registry.ts';
 import { LogBlobStore, blobScheme, mimeOfHandle, withBlobLines } from './blobs.ts';
 import { TimerStore } from './timers.ts';
 import { SessionTracker, type SessionHandle } from './sessions.ts';
@@ -289,15 +289,19 @@ export class Core<C extends CoreConfig = CoreConfig> {
 
   /** 按当前活跃端点读取模型上下文事实。 */
   private contextFacts(): ContextFacts {
-    const module = () => providerModule(this.activeProviderEntry().entry.kind);
+    const module = () => {
+      const entry = this.config.providers[this.config.activeProvider];
+      return entry ? providerModules.find(module => module.id === entry.kind) : undefined;
+    };
     return {
       hardTokens: () => {
+        if (!module() || !this.config.providers[this.config.activeProvider]?.spec) return null;
         const spec = this.activeSpec();
         const window = this.contextWindowOf(spec);
         return window === undefined ? null : Math.max(0, window - (spec.maxTokens ?? 0));
       },
-      estimateTokens: (records) => module().estimateTokens?.(records, this.activeSpec()) ?? estimateMessagesTokens(records),
-      contextOverflow: (error) => module().contextOverflow?.(error) ?? false,
+      estimateTokens: (records) => module()?.estimateTokens?.(records, this.activeSpec()) ?? estimateMessagesTokens(records),
+      contextOverflow: (error) => module()?.contextOverflow?.(error) ?? false,
     };
   }
 
@@ -587,7 +591,13 @@ export class Core<C extends CoreConfig = CoreConfig> {
     const dataDir = this.loaded.dataDir;
     if (!existsSync(dataDir)) mkdirSync(dataDir, { recursive: true });
     // 构造期已加载状态；此处再次 load 会覆盖装配后、启动前的修改。
-    this.session.load();
+    const repair = this.session.load();
+    if (repair) {
+      this.log.warn(
+        repair.kind === 'torn-tail' ? 'session 末行未写完,已截掉' : 'session 末行缺换行,已补上',
+        { ...repair, file: 'session-main.jsonl' },
+      );
+    }
     for (const mod of this.worlds) {
       try {
         await mod.start(this.makeHost(mod));

package/src/core/loop.ts

@@ -245,8 +245,9 @@ export class MainLoop {
   /** 截断与前缀重载共用的维护串行链，避免两个 session.reset 互相覆盖。 */
   private maintenanceChain: Promise<void> = Promise.resolve();
   private prefixReloadPromise: Promise<void> | null = null;
-  /** 在一轮处理中请求重载时，等自然回合边界再释放。 */
-  private releasePrefixReload: (() => void) | null = null;
+  private clearSessionPromise: Promise<void> | null = null;
+  /** 在一轮处理中请求的前缀重载与清空，等自然回合边界再释放。 */
+  private releaseAtBoundary: Array<() => void> = [];
   /** 当前正在处理一个事件批；手动交接必须等到该批自然结束，不能重置半轮session。 */
   private processingBatch = false;
   private handoffRequested = false;
@@ -722,13 +723,15 @@ export class MainLoop {
     const latest = store.latestCursor();
     for (let c = top + 1; c <= latest; c++) {
       const next = store.get(c);
-      if (!next) break;
-      // 未处理的 archive-only 项必须保留在水位之后，重启才会补投。
-      // 已处理项由 settledArchives 标识。
-      const skippable = next.origin === 'internal'
-        || (next.contextDelivery === 'archive-only' && this.settledArchives.has(c));
-      // 集合记录存储位置；装载期重排保证 next.cursor === c。
-      if (!skippable && !this.deliveredCursors.has(c)) break;
+      // 清空分片或跳过损坏行留下的空位没有可投递内容，不阻止水位推进。
+      if (next) {
+        // 未处理的 archive-only 项必须保留在水位之后，重启才会补投。
+        // 已处理项由 settledArchives 标识。
+        const skippable = next.origin === 'internal'
+          || (next.contextDelivery === 'archive-only' && this.settledArchives.has(c));
+        // 集合记录存储位置；装载期重排保证 next.cursor === c。
+        if (!skippable && !this.deliveredCursors.has(c)) break;
+      }
       this.deliveredCursors.delete(c);
       this.settledArchives.delete(c);
       top = c;
@@ -904,8 +907,8 @@ export class MainLoop {
         } finally {
           this.processingBatch = false;
         }
-        // 异常退出由 stop 释放排队请求；只有正常批次边界执行重载。
-        await this.flushRequestedPrefixReload(generation);
+        // 异常退出由 stop 释放排队请求；只有正常批次边界执行重载与清空。
+        await this.flushBoundaryMaintenance();
       }
     } finally {
       this.stop();
@@ -933,7 +936,11 @@ export class MainLoop {
     for (let round = 1; ; round++) {
       if (!this.active(generation)) return;
       this.roundsLastBatch = round;
-      const spec = this.d.spec();
+      let spec: ModelSpec;
+      try { spec = this.d.spec(); } catch (error) {
+        log.warn('模型配置不可用', { error: String(error) });
+        return;
+      }
       // 后续轮输入超限时结束本批，由批末检查执行交接。
       // 首轮仍处理本批新投递的事件；上一批的容量检查已在批末执行。
       if (round > 1) {
@@ -1425,9 +1432,25 @@ export class MainLoop {
     return rebuildTail(paired, budget, estimate);
   }
 
-  /** 清空主 session，重建 system 前缀并调用 Persona 开场钩子；事件库保留。 */
-  async clearSession(): Promise<void> {
+  /**
+   * 清空主 session，重建 system 前缀并调用 Persona 开场钩子；事件库保留。
+   * 正在处理批次时等到该批自然结束，不重置半轮 session；并发请求复用同一 Promise。
+   */
+  clearSession(): Promise<void> {
     const generation = this.generation;
+    if (!this.active(generation)) return Promise.resolve();
+    if (this.clearSessionPromise) return this.clearSessionPromise;
+    let tracked: Promise<void>;
+    tracked = this.safeBoundary()
+      .then(() => this.enqueueMaintenance(() => this.performClearSession(generation), generation))
+      .finally(() => {
+        if (this.clearSessionPromise === tracked) this.clearSessionPromise = null;
+      });
+    this.clearSessionPromise = tracked;
+    return tracked;
+  }
+
+  private async performClearSession(generation: number): Promise<void> {
     if (!this.active(generation)) return;
     const { session, log } = this.d;
     const sysMsg = await this.buildSystem();
@@ -1447,11 +1470,8 @@ export class MainLoop {
     const generation = this.generation;
     if (!this.active(generation)) return Promise.resolve();
     if (this.prefixReloadPromise) return this.prefixReloadPromise;
-    const safeBoundary = this.processingBatch
-      ? new Promise<void>((resolve) => { this.releasePrefixReload = resolve; })
-      : Promise.resolve();
     let tracked: Promise<void>;
-    tracked = safeBoundary
+    tracked = this.safeBoundary()
       .then(() => this.enqueueMaintenance(() => this.performSystemPrefixReload(generation), generation))
       .finally(() => {
         if (this.prefixReloadPromise === tracked) this.prefixReloadPromise = null;
@@ -1460,12 +1480,22 @@ export class MainLoop {
     return tracked;
   }
 
-  private async flushRequestedPrefixReload(_generation: number): Promise<boolean> {
-    const release = this.releasePrefixReload;
-    if (!release) return false;
-    this.releasePrefixReload = null;
-    release();
-    await this.prefixReloadPromise;
+  /** 空闲时立即；正在处理批次时等 run() 在批末释放，或 stop() 释放。 */
+  private safeBoundary(): Promise<void> {
+    if (!this.processingBatch) return Promise.resolve();
+    return new Promise<void>((resolve) => { this.releaseAtBoundary.push(resolve); });
+  }
+
+  private releaseBoundary(): void {
+    const waiting = this.releaseAtBoundary;
+    this.releaseAtBoundary = [];
+    for (const release of waiting) release();
+  }
+
+  private async flushBoundaryMaintenance(): Promise<boolean> {
+    if (this.releaseAtBoundary.length === 0) return false;
+    this.releaseBoundary();
+    await Promise.all([this.prefixReloadPromise, this.clearSessionPromise]);
     return true;
   }
 
@@ -1721,9 +1751,7 @@ export class MainLoop {
     this.backoffWake?.();
     if (!this.shutdown.signal.aborted) this.shutdown.abort(new Error('core 正在关机'));
     this.handoffRequested = false;
-    const releasePrefixReload = this.releasePrefixReload;
-    this.releasePrefixReload = null;
-    releasePrefixReload?.();
+    this.releaseBoundary();
     this.stopFn?.();
     const round = this.currentRound;
     if (round && !round.controller.signal.aborted) {

package/src/core/session.ts

@@ -1,7 +1,7 @@
 /** 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 { ContextLog, type ContextLoadRepair } from '../protocol/open-responses/context-log.ts';
 import { estimateMessagesTokens } from './util.ts';
 
 
@@ -38,7 +38,8 @@ export class SessionLog {
     }
   }
 
-  load(): void { this.context.load(); }
+  /** 返回对未写完末行的修复；其他损坏行抛错。 */
+  load(): ContextLoadRepair | null { return this.context.load(); }
 
   /** 整体替换：先写临时文件，再 rename 覆盖目标文件。 */
   reset(messages: readonly ContextRecord[]): void {

package/src/core/timers.ts

@@ -2,7 +2,7 @@
  * 通用持久定时器:到点回调持有方、跨重启恢复。载荷不透明——
  * 闹钟的备注、阻断、关键词这些语义归持有它的Persona。
  */
-import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import type { Logger, TimerEntry, TimersApi } from './types.ts';
 import { nullLogger, shortId } from './util.ts';
@@ -47,7 +47,8 @@ export class TimerStore implements TimersApi {
     const entry: TimerEntry = { id: shortId('wake_'), atIso, payload };
     this.entries.push(entry);
     this.save();
-    if (this.started) this.arm(entry);
+    // 已到期的也等 set 返回后再回调,持有方先拿到 id。
+    if (this.started) this.arm(entry, 'next-tick');
     return { ok: true, id: entry.id };
   }
 
@@ -76,9 +77,10 @@ export class TimerStore implements TimersApi {
     return n;
   }
 
-  private arm(entry: TimerEntry): void {
+  /** 已到期的条目按 whenDue 立即回调或下一个宏任务回调;start() 用前者。 */
+  private arm(entry: TimerEntry, whenDue: 'now' | 'next-tick' = 'now'): void {
     const delay = Date.parse(entry.atIso) - Date.now();
-    if (delay <= 0) {
+    if (delay <= 0 && whenDue === 'now') {
       this.fire(entry.id);
       return;
     }
@@ -88,7 +90,7 @@ export class TimerStore implements TimersApi {
       // 超长延迟按 MAX_TIMEOUT 分段重新 arm。
       this.timers.set(entry.id, setTimeout(() => this.arm(entry), MAX_TIMEOUT));
     } else {
-      this.timers.set(entry.id, setTimeout(() => this.fire(entry.id), delay));
+      this.timers.set(entry.id, setTimeout(() => this.fire(entry.id), Math.max(0, delay)));
     }
   }
 
@@ -123,7 +125,7 @@ export class TimerStore implements TimersApi {
     if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
     const tmp = this.file + '.tmp';
     writeFileSync(tmp, JSON.stringify(this.entries, null, 2), 'utf8');
-    if (existsSync(this.file)) rmSync(this.file);
+    // 通过 rename 原子覆盖，不先删除，避免崩溃后定时器全部丢失。
     renameSync(tmp, this.file);
   }
 }