cortico 0.1.1 → 0.1.3

package/README.md

@@ -23,9 +23,9 @@ checker and the test runner. 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cortico",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "type": "module",
   "description": "A TypeScript framework for event-driven, long-running persona bots",
   "license": "MIT",

package/src/boot.ts

@@ -4,6 +4,7 @@
  */
 import { existsSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import type { CoreConfig, LLMProviderEntry } from './core/types.ts';
 
 export const RESTART_FLAG_FILE = '.restart-request';
 
@@ -19,6 +20,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 +53,23 @@ 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}/`;
+}
+
+/** 空选择允许进入控制台完成配置；非空名称必须引用已有连接。 */
+export function providerAtBoot(config: Pick<CoreConfig, 'activeProvider' | 'providers'>): LLMProviderEntry | undefined {
+  if (!config.activeProvider) return undefined;
+  const entry = config.providers[config.activeProvider];
+  if (!entry) {
+    throw new Error(`activeProvider="${config.activeProvider}" 在 providers 段里不存在(现有: ${Object.keys(config.providers).join(' / ') || '无'})`);
+  }
+  return entry;
+}

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()),
+    },
   ];
 }
 
@@ -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

@@ -34,6 +34,9 @@ Core 管理 session、事件流与模型调用的生命周期，包括事件投
 `sessionDecls`;`spawnFork`、`resolveBlob` / `internBlobs`、`setWorldVisible`、`activeSpec` /
 `activeProviderEntry`、`mountWorld` / `unmountWorld`、`start` / `stop`。
 
+`WorldHost.modelFacts` 每次调用按当前端点读取。`activeProvider` 为空或端点没有模型时 `accepts`
+返回 false,`activeProvider` 指向不存在的端点时抛错。
+
 Persona 通过 `CoreApi` 访问：`injectInternal` / `injectDeferred` / `injectExternal`、
 `requestContextHandoff`、`spawnFork`、`sessionInfo`、`llm`、`timers`、`deliveryGate`、
 `personaState` / `savePersonaState`、`toolsTagged`、`blob`、`log`。
@@ -51,14 +54,19 @@ piggyback 只入队，随后续唤醒一起投递。
 更新后的值在下一次入队时参与计算。
 
 投递水位 `lastDeliveredCursor` 持久化，队列不持久化。重启时补投水位之后的外部事件；
-已被候选处理结果引用的原始归档不重复投递。内部事件仅在当次运行投递。
+已被候选处理结果引用的原始归档不重复投递。内部事件仅在当次运行投递。清空分片或跳过损坏行
+留下的游标空位没有可投递内容，不阻止水位推进。
 
 ## 主循环
 
 每次唤醒处理一批事件，可进行多轮模型调用。`SessionDecl.rounds()` 提供
 `{ soft, hard, softHint? }`：到 soft 轮时将 `softHint` 追加到最后一条工具回执；到 hard 轮时
 记录 warn 并结束本批。`endsTurn` 工具和自然结束共用结束处理；本批结束时尚未处理的事件
-退回总线，进入下一批。
+退回总线，进入下一批。控制台的前缀重载与清空 session 在批次边界执行：正在处理批次时等该批
+结束，空闲时立即；并发请求复用同一事务。
+
+一批正文归档后，Core 调用 `Persona.onDelivery` 并等待它返回的 Promise,不设期限。完成前
+`injectInternal` 的内容排在这批的内部行末尾、外部正文之前;完成后的注入进入总线。
 
 状态 0、429 或 5xx 的模型调用失败，可保留已记录的输出和工具回执，按 `ResubmitPolicy` 重试。
 默认允许连续重试 2 次、每批最多 4 次，退避为 2 秒、10 秒；上下文超限、抢占、关机或轮数
@@ -86,3 +94,5 @@ handler 异常转为失败回执。流式生成时 `EagerDispatch` 可提前执
 warn；`onHandoff` 异常记录 error 并使用默认交接策略。其他钩子的异常由调用方处理。
 读取 `console()` 失败时省略该 World 的环境段，继续构建前缀。主循环异常退出时记录 error
 并停止定时器。启动器处理未捕获的进程异常并执行关机流程。
+
+`instanceIsRunning(dataDir)` 只读检查实例锁对应进程是否存活，沿用锁接管时的陈旧记录判定，不获取或更改锁。

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,
     };
   }
 
@@ -464,8 +468,10 @@ export class Core<C extends CoreConfig = CoreConfig> {
     return {
       model: () => spec().model,
       accepts: (mime) => {
+        if (!this.loaded.config.activeProvider) return false;
         const {entry} = this.activeProviderEntry();
-        return providerModule(entry.kind).accepts?.(entry,spec(),mime) ?? (entry.multimodal === true && mime.startsWith('image/'));
+        if (!entry.spec) return false;
+        return providerModule(entry.kind).accepts?.(entry,entry.spec,mime) ?? (entry.multimodal === true && mime.startsWith('image/'));
       },
       contextWindow: () => this.contextWindowOf(spec()),
     };
@@ -587,7 +593,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/generation.ts

@@ -16,13 +16,26 @@ export interface TokenMeters {
 }
 export type Meter = Exclude<keyof TokenMeters, 'native' | 'details'> | `detail:${string}`;
 export interface PriceRule { meter: Meter; perMillion: number; unit?: string; }
-export interface PriceSnapshot {
+export interface PriceSchedule { rules: PriceRule[]; inputBands?: Array<{ from: number; rules: PriceRule[] }>; }
+export interface PriceTable extends PriceSchedule { serviceTiers?: Record<string, PriceSchedule>; }
+/**
+ * `from` and `to` are `HH:MM` on the clock of `timezone`, half-open; `to` at or before `from` spans midnight.
+ * A span belongs to the local date it starts on. `weekdays` (ISO, 1 = Monday to 7 = Sunday) limits the dates
+ * that open it; `exceptDates` (`YYYY-MM-DD`) removes single dates.
+ */
+export interface PriceWindow extends PriceTable {
+  from: string;
+  to: string;
+  timezone: string;
+  weekdays?: number[];
+  exceptDates?: string[];
+}
+export interface PriceSnapshot extends PriceTable {
   id: string;
   currency: string;
   basis: 'marginal' | 'equivalent';
-  rules: PriceRule[];
-  inputBands?: Array<{ from: number; rules: PriceRule[] }>;
-  serviceTiers?: Record<string, { rules: PriceRule[]; inputBands?: Array<{ from: number; rules: PriceRule[] }> }>;
+  /** The first window holding `capturedAt` replaces the table above it; outside every window that table applies. */
+  timeWindows?: PriceWindow[];
   source: string;
   capturedAt: string;
 }
@@ -30,7 +43,7 @@ export interface Charge {
   quote: PriceSnapshot;
   amount: number | null;
   knownAmount: number;
-  missing: Array<Meter | 'serviceTier'>;
+  missing: Array<Meter | 'serviceTier' | 'timeWindow'>;
   lines: Array<{ meter: Meter; unit: string; quantity: number | null; perMillion: number; amount: number | null }>;
 }
 export interface ProviderAttempt {
@@ -89,13 +102,57 @@ export function standardUsage(meters: TokenMeters): Usage | null {
   return { input_tokens: input, output_tokens: output, total_tokens: total,
     input_tokens_details: { cached_tokens: cachedInput }, output_tokens_details: { reasoning_tokens: reasoning } };
 }
+/** Minutes since midnight for an `HH:MM` bound, 24:00 included; null when the text is not one. */
+function clockMinutes(value: string): number | null {
+  const match = /^(\d{1,2}):(\d{2})$/.exec(value);
+  if (!match) return null;
+  const minutes = Number(match[1]) * 60 + Number(match[2]);
+  return Number(match[2]) > 59 || minutes > 24 * 60 ? null : minutes;
+}
+/** Whether the text is a real calendar date written `YYYY-MM-DD`. */
+function isCalendarDate(value: string): boolean {
+  const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value);
+  if (!match) return false;
+  const [year, month, day] = [Number(match[1]), Number(match[2]), Number(match[3])];
+  const date = new Date(Date.UTC(year, month - 1, day));
+  return date.getUTCFullYear() === year && date.getUTCMonth() === month - 1 && date.getUTCDate() === day;
+}
+/** Whether the instant falls in the window on the window's own clock and date; null when a field is unreadable. */
+function holdsTime(window: PriceWindow, at: string): boolean | null {
+  const instant = new Date(at);
+  const [from, to] = [clockMinutes(window.from), clockMinutes(window.to)];
+  if (from === null || to === null || Number.isNaN(instant.getTime())) return null;
+  if (window.weekdays?.some(day => !Number.isInteger(day) || day < 1 || day > 7)) return null;
+  if (window.exceptDates?.some(date => !isCalendarDate(date))) return null;
+  let year: number, month: number, day: number, local: number;
+  try {
+    // Intl throws on a zone name it does not know.
+    const parts = new Intl.DateTimeFormat('en-GB', { timeZone: window.timezone, year: 'numeric', month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit', hourCycle: 'h23' }).formatToParts(instant);
+    const read = (type: string): number => Number(parts.find(part => part.type === type)!.value);
+    [year, month, day] = [read('year'), read('month'), read('day')];
+    local = read('hour') * 60 + read('minute');
+  } catch { return null; }
+  const spansMidnight = to <= from;
+  if (spansMidnight ? local < from && local >= to : local < from || local >= to) return false;
+  // After midnight the span still belongs to the previous date, the one it started on.
+  const start = new Date(Date.UTC(year, month - 1, spansMidnight && local < to ? day - 1 : day));
+  if (window.weekdays && !window.weekdays.includes(start.getUTCDay() || 7)) return false;
+  return !window.exceptDates?.includes(start.toISOString().slice(0, 10));
+}
 export function priceUsage(meters: TokenMeters, quotes: readonly PriceSnapshot[], serviceTier: string | null = null): Charge[] {
   return quotes.map(quote => {
     const missing: Charge['missing'] = [];
-    let schedule: Pick<PriceSnapshot, 'rules' | 'inputBands'> = quote;
-    if (quote.serviceTiers) {
-      if (serviceTier === null || !quote.serviceTiers[serviceTier]) missing.push('serviceTier');
-      else schedule = quote.serviceTiers[serviceTier];
+    let table: PriceTable = quote;
+    for (const window of quote.timeWindows ?? []) {
+      const holds = holdsTime(window, quote.capturedAt);
+      // An unreadable window may be the one holding the request; a later table cannot stand in for it.
+      if (holds === null) { missing.push('timeWindow'); break; }
+      if (holds) { table = window; break; }
+    }
+    let schedule: PriceSchedule = table;
+    if (table.serviceTiers) {
+      if (serviceTier === null || !table.serviceTiers[serviceTier]) missing.push('serviceTier');
+      else schedule = table.serviceTiers[serviceTier];
     }
     let rules = schedule.rules;
     if (schedule.inputBands?.length) {

package/src/core/instance-lock.ts

@@ -72,6 +72,12 @@ function readPayload(file: string): LockPayload | null {
   }
 }
 
+/** 只读检查数据目录的锁是否仍对应存活进程。 */
+export function instanceIsRunning(dataDir: string): boolean {
+  const payload = readPayload(join(dataDir, INSTANCE_LOCK_FILE));
+  return payload !== null && ownerStillRunning(payload);
+}
+
 /** 排他创建；仅 EEXIST 返回 false，其他错误抛出。 */
 function createExclusive(file: string, payload: LockPayload): boolean {
   let fd: number;