Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

44.9 KB
Raw Blame
/**
 * MakerMemoryManager — Maker Memory 顶层单例 + 状态机 + per-workdir Store 实例池。
 *
 * 职责:
 *  - 维护全局 enabled 状态 (mode='maker' 时 true), 跟 native auto-memory 强制互斥
 *    (enable 时遍历 agents 调 setMemory(false))
 *  - per-workdir Store 实例池: 第一次 getStore(workdir) 时 lazy 创建 storage dir + open
 *    SQLite db, 同 workdir 复用同一 store + db 实例 (避免 db 多 open 句柄)
 *  - Manager.dispose() 时关闭所有 db, 跟 BaseAgent.dispose() 同生命周期
 *  - review 通过 host 注入的某个 agent.oneShot 跑 (默认 claude haiku, 最便宜)
 *
 * 跟 Maker 的关系:
 *  Maker 持有 makerMemory 字段 (可选), host 通过 MakerDeps.makerMemory 注入。
 *  agent 端 (claude-code/index.ts, codex/index.ts) 在 startSession 拼 prompt 时
 *  通过 deps.runtimeConfig.makerMemoryEnabled 判断是否注入 memory 段;
 *  通过 host 传入的 makerMemory.getStore(workdir).getIndex() 拿当前索引内容拼。
 *
 * 不管:
 *  - sqliteFactory / userDataPath 的具体值 (host 在 desktop 一侧处理 better-sqlite3 +
 *    app.getPath('userData'))
 *  - settings 持久化 (renderer localStorage 模式)
 *  - flush before compaction (那是 flush-controller 的职责, 后续阶段)
 */

import * as path from 'node:path';
import * as fsSync from 'node:fs';
import type Database from 'better-sqlite3';

import { MakerMemoryStore, memoryScopeDirName, parseFilename } from './store.js';
import { parseBotMemoryScopeKey } from './storage.js';
import {
  MemoryError,
  type MemoryConfig,
  type WriteOptions,
} from './types.js';
import type { BaseAgent } from '../agents/base-agent.js';
import { NotSupportedError } from '../types/capabilities.js';
import type { AgentKind } from '../types/common.js';
import type { Logger } from '../interfaces/logger.js';

/** 工厂函数: 给一个绝对文件路径, 返回 better-sqlite3 Database 实例。host 注入。 */
export type SqliteFactory = (filePath: string) => Database.Database;

/** review 一次性调用预算: 一段 ≤200 词的建议, 给足 60s(LLM 冷启 + 长 dump)。 */
const REVIEW_ONE_SHOT_OPTS = { maxTokens: 800, timeoutMs: 60_000 } as const;

export interface MakerMemoryManagerDeps {
  /** Maker memory 文件根目录, host 注入 (e.g. <electron userData>/maker-memory) */
  basePath: string;
  /**
   * 动态解析当前 owner 作用域的存储根(desktop: 按 getActiveAppSession().dataOwnerId 现取)。
   * 返回 null = owner 作用域不可用(signed-out / 认证未就绪 / 边界切换中),此时 manager
   * 必须 fail-closed(抛 memory:not-ready),绝不降级写临时目录。
   * 缺席 = 退化为静态 basePath(测试 / 无 owner 概念宿主)。
   *
   * 修复 #2341:构造时冻结 basePath 会让冷启动竞态把根锁死在
   * %TEMP%\cindy-no-session\<pid>\ 且不再重解析 —— 每次访问都重新解析根,
   * 配合 ownerScopeKey 在作用域变化时清池换根。
   */
  resolveBasePath?: () => string | null;
  /**
   * 当前 owner 作用域的不透明键(desktop: activeOwnerScopeKey 的脱敏形态,
   * 含 mode + 脱敏 owner + generation)。每次 commit(登录/登出/切账号,generation+1)
   * 都会变化:manager 检测到变化时先关闭全部旧 store db 再重建到新根,杜绝旧句柄
   * 与新 owner 数据混用。缺席 = 不做作用域追踪(静态 basePath 宿主)。
   */
  ownerScopeKey?: () => string;
  /**
   * owner 作用域变化(首次解析 / 换根)后重新读取 enabled 初值的回调
   * (desktop: 按新 owner 根读 memory-settings.json)。修复冷启动竞态里
   * initialEnabled 在 owner 未就绪时冻结为全局默认、owner 就绪后不重绑定的
   * 问题(#2388 review Codex 4th P1)。缺席 = 不重绑定(静态宿主)。
   */
  reloadEnabled?: () => boolean;
  /**
   * Optional host-owned physical storage resolver. Ordinary scopes keep the
   * historical `<owner>/maker-memory/<scope>` path; Desktop uses this only for
   * Bot scopes so their durable records live inside the Bot Home.
   */
  resolveStorageDir?: (scopeKey: string, ownerRoot: string) => string | null;
  /**
   * Scopes whose lifecycle is independent from the global Maker Memory toggle.
   * They remain available when Maker Memory is disabled and are excluded from
   * the global active-workdir projection/reset directory.
   */
  isIndependentScope?: (scopeKey: string) => boolean;
  /** SQLite open 工厂, host 注入 (better-sqlite3 是 native module, 不能在 maker-core require) */
  sqliteFactory: SqliteFactory;
  /** Agent 引用 — 强联动 setMemory(false) 关原生时用 */
  agents: Partial<Record<AgentKind, BaseAgent>>;
  /** 跑 memory_review 时用哪个 agent 的 oneShot. 默认 'claude-code' (haiku 最便宜) */
  reviewAgent?: AgentKind;
  /**
   * review 派发前的停用轴守卫(host 注入,desktop = isAgentOneShotRouteDisabled)。
   * memory_review 的 oneShot 是一次新的付费调用:该 agent 的默认 one-shot 路由被
   * 用户停用时不派发,抛错让 MCP 工具面把原因回给调用方(PR #744 review 第十六轮)。
   * 缺席 = 不裁决(未接入停用设置的宿主)。
   */
  isOneShotRouteDisabled?: (agent: AgentKind) => Promise<boolean>;
  /**
   * memory_review 的一次性文本调用(host 注入)。返回 null / 空串 = 链上没产出,
   * manager 不再回退 reviewAgent 的默认 oneShot 路由(那是本账号无权模型的死路),
   * 直接以可读原因 fail-closed。
   *
   * desktop 注入的实现走共享辅助模型链: review agent 的默认模型(claude-haiku-4-5)
   * 在部分供应商网关上不在账号可用清单内(403 user_model_access_denied), 硬编码
   * 默认路由会让 memory_review 对这些账号 100% 失败(2026-10-14 实测)。
   */
  reviewOneShot?: (
    prompt: string,
    opts: { maxTokens: number; timeoutMs: number },
  ) => Promise<string | null>;
  logger: Logger;
  /** 配置覆盖 */
  config?: Partial<MemoryConfig>;
  /**
   * 启动时初值. 来自 settings (host 透传 runtimeConfig.makerMemoryEnabled).
   * 默认 false — host 必须明确开启,避免未接入设置系统的宿主意外改变行为。
   */
  initialEnabled?: boolean;
}

export interface MakerMemoryState {
  enabled: boolean;
  /** 已 lazy create 的 workdir 列表 (调试 / UI 列表用) */
  activeWorkdirs: string[];
}

export interface SetEnabledResult {
  /** 'next-session': 已经在跑的 session 不会被影响; 改完下次 startSession 才生效 */
  effective: 'next-session';
  /** enabled=true 时, 联动调过的 agent kind 列表 (各自 setMemory(false) 的结果) */
  affectedAgents?: Array<{ kind: AgentKind; effective: 'immediate' | 'next-session' | 'unsupported' }>;
}

interface PooledEntry {
  store: MakerMemoryStore;
  db: Database.Database;
  independent: boolean;
  /** 入池时的池世代 — resetAll 后 +1, getStore 命中旧世代时惰性关闭重建 */
  generation: number;
}

const MEMORY_SUBDIR = 'maker-memory';
const FTS_DB_FILENAME = 'fts.db';
const STORAGE_MIGRATION_RECEIPT = '.cindy-memory-migration-v1.json';
// This shape is only a candidate: sanitized project paths can match it too.
const LEGACY_BOT_MEMORY_DIR = /^bot-.{0,24}-[a-f0-9]{16}$/;

async function isLegacyBotMemoryDir(dir: string): Promise<boolean> {
  const name = path.basename(dir);
  if (!LEGACY_BOT_MEMORY_DIR.test(name)) return false;
  try {
    const meta: unknown = JSON.parse(await fsSync.promises.readFile(path.join(dir, 'meta.json'), 'utf8'));
    const scope = meta && typeof meta === 'object' && 'absPath' in meta ? meta.absPath : undefined;
    // Validate both identity and its mapping to this directory. A matching
    // project scope must be cleared even if its directory looks like a Bot's.
    if (typeof scope === 'string' && scope && memoryScopeDirName(scope) === name) {
      return parseBotMemoryScopeKey(scope) !== null;
    }
  } catch {
    // Missing/damaged metadata cannot prove either ownership. Preserve the
    // ambiguous data, but never report a successful global clear.
  }
  throw new MemoryError('not-ready', `cannot determine memory scope for ${name}; reset incomplete, data preserved`);
}

function copyLegacyMemoryShardsSync(sourceDir: string, targetDir: string): void {
  fsSync.mkdirSync(targetDir, { recursive: true });
  for (const entry of fsSync.readdirSync(sourceDir, { withFileTypes: true })) {
    // Only curated memory shard files are durable source data. MEMORY.md,
    // meta.json, fts.db and migration receipts are derived/host state and must
    // be rebuilt in the destination. Never follow a legacy symlink.
    if (!entry.isFile() || !parseFilename(entry.name)) continue;
    const source = path.join(sourceDir, entry.name);
    if (fsSync.lstatSync(source).isSymbolicLink()) continue;
    const target = path.join(targetDir, entry.name);
    if (!fsSync.existsSync(target)) fsSync.copyFileSync(source, target);
  }
}

export class MakerMemoryManager {
  private enabled: boolean;
  private readonly stores = new Map<string, PooledEntry>();
  private readonly logger: Logger;
  /**
   * 最近一次校验通过的 owner 作用域 key(deps.ownerScopeKey 的快照)。
   * 变化时清池换根;null = 尚未校验过。仅用于相等性比较,日志已由 host
   * 注入的 ownerScopeKey 保证脱敏(不落明文 owner id)。
   */
  private activeScopeKey: string | null = null;
  /**
   * 池世代 (review #2388 Greptile 16th): resetAll 清空全部 workdir 后 +1,
   * 池内所有旧世代 store 惰性失效 — getStore 命中旧世代时 close + 重建。
   * 不立即关闭任何 store: 已返回给调用方的实例 (可能正在使用) 不被误伤。
   */
  private poolGeneration = 0;
  /**
   * resetAll 进行中**计数** (review #2388 Greptile 17th: 布尔标志在多并发
   * resetAll 下会提前解除屏障): >0 期间并发 getStore 与 store 操作一律
   * 拒绝 (not-ready)。用途:
   *  - 删除目录时池中 db 若仍打开 (better-sqlite3 占用 fts.db) 会 EBUSY —
   *    resetAll 开头 closeAllStores 清池, 期间拒绝新入池, 删除无占用;
   *  - 在途 store 操作在下一复核点 (assertStoreOperable) 抛 not-ready 中止,
   *    不再访问已被 closeAllStores 关闭的 db 句柄。
   */
  private resetInFlight = 0;
  /**
   * init 进行中的 db (review #2388 Codex 26th P1): db 打开后、store.init 完成
   * 入池前不在 this.stores 里 — resetAll 只关池内 store, Windows 上 fs.rm 会
   * 碰到这个未跟踪的 open fts.db → 跳过该 workdir 且报成功。closeAllStores
   * 同时关闭该集合, 保证 reset 扫描前无任何 open 句柄。
   */
  private readonly openingStores = new Map<Database.Database, boolean>();

  constructor(private readonly deps: MakerMemoryManagerDeps) {
    this.enabled = deps.initialEnabled ?? false;
    this.logger = deps.logger;
    this.logger.info('MakerMemoryManager initialized', {
      enabled: this.enabled,
      basePath: deps.basePath,
      reviewAgent: deps.reviewAgent ?? 'claude-code',
    });
  }

  /**
   * 当前生效的存储根: 优先动态 resolveBasePath (可为 null = owner 未就绪),
   * 缺席时退化为静态 basePath。
   *
   * 注意不能用 `deps.resolveBasePath?.() ?? deps.basePath` —— resolveBasePath
   * 返回 null 是「owner 不可用」的显式信号, `??` 会把 null 误当成未提供而
   * 回退到静态 basePath, 让 fail-closed 守卫失效 (#2341)。
   */
  private get resolvedBasePath(): string | null {
    return this.deps.resolveBasePath ? this.deps.resolveBasePath() : this.deps.basePath;
  }

  /**
   * owner 作用域守卫 (每次 getStore / resetDigests / resetAll 前调用):
   *  1. ownerScopeKey 变化 → 关闭旧 store 池全部 db, 重解析根 (修复 #2341 的
   *     「启动期根冻结后不再重解析」);
   *  2. resolveBasePath 返回 null → 抛 memory:not-ready, 绝不创建/写入临时目录
   *     (修复「write 返回成功但数据落 %TEMP% 一次性目录」的静默丢失)。
   *
   * 抛出的 MemoryError 会被 MCP 层 classifyMemoryError 翻译成
   * MAKER_MEMORY_NOT_READY, 与「空库返回 ok+[]」可区分。
   */
  /**
   * 纯 scope 同步 (不抛): 首次锚定 / ownerScopeKey 变化时关闭旧 store 池、
   * 换根并重绑定 enabled。供 ensureOwnerScope (fail-closed 前) 与 isEnabled()
   * (纯查询, 不能抛) 共用 — review #2388 Codex 11th P1: rebindEnabled 此前
   * 只在 ensureOwnerScope 里跑, 先读 isEnabled() 的路径 (withStore 短路、
   * session/remote option backfills) 会停留在旧 owner 的 flag 上。
   */
  private syncOwnerScope(): void {
    if (!this.deps.ownerScopeKey) return;
    const key = this.deps.ownerScopeKey();
    if (this.activeScopeKey === null) {
      // 首次解析 — 构造期 owner 可能尚未就绪 (initialEnabled 是全局默认),
      // 这里锚定 scope 的同时按当前 owner 重绑定 enabled。
      this.activeScopeKey = key;
      this.rebindEnabled();
    } else if (key !== this.activeScopeKey) {
      this.logger.warn('maker memory owner scope changed — closing stores and rebinding root', {
        fromScope: this.activeScopeKey,
        toScope: key,
      });
      this.closeAllStores();
      this.activeScopeKey = key;
      this.rebindEnabled();
    }
  }

  private ensureOwnerScope(): void {
    // scope 同步 + fail-closed: 缺 owner 直接拒绝 (不建临时库), scope 变化则换根。
    this.syncOwnerScope();
    // 注意 disabled 检查**不**放在这里: resetAll/resetDigests 等清理路径也走
    // ensureOwnerScope, 用户关闭 memory 后仍需能清空已有记忆 — 重置入口按
    // 「不论 makerEnabled 值都能清」语义工作 (review #2388 Codex 10th P2)。
    if (this.resolvedBasePath === null) {
      this.logger.warn('maker memory owner scope unavailable — refusing ephemeral fallback', {
        scopeKey: this.activeScopeKey,
      });
      throw new MemoryError(
        'not-ready',
        'owner scope unavailable (signed-out or auth not settled); refusing to fall back to ephemeral storage',
      );
    }
  }

  /**
   * 当前 owner 作用域键的公开只读快照 — 供 MCP 工具层 (withStore) 在拿到
   * store 后、对 store 发起 await 操作前捕获 / 操作后复核 (review #2388
   * Codex 4th P1: getStore 返回的裸 store 在 manager 守卫之外被调用方使用)。
   * 返回 null = 未注入 ownerScopeKey (静态宿主)。
   */
  currentOwnerScopeKey(): string | null {
    return this.deps.ownerScopeKey?.() ?? null;
  }

  /** owner 作用域变化时按新 owner 设置重绑定 enabled (host 注入 reloadEnabled)。 */
  private rebindEnabled(): void {
    if (!this.deps.reloadEnabled) return;
    const next = this.deps.reloadEnabled();
    if (next !== this.enabled) {
      this.logger.info('maker memory enabled rebound after owner scope change', { enabled: next });
      this.enabled = next;
    }
  }

  /**
   * store 操作复核点 (注入 store 的 scopeCheck, 每次公开操作/写盘前调用):
   * 1. resetAll 进行中 → 抛 not-ready (review #2388 Greptile 17th): 在途操作
   *    在下一复核点中止, 不再访问已被 closeAllStores 关闭的 db 句柄;
   * 2. store 创建后 resetAll 已完整执行 → 其 db 已被 closeAllStores 关闭
   *    (review #2388 Greptile 20th P1): 调用方持有的旧世代 store 任何操作
   *    都不得访问已关句柄, fail-closed 抛 not-ready 而非裸 database is closed;
   * 3. owner scope 变化 → 抛 not-ready (assertScopeUnchanged)。
   */
  private assertStoreOperable(
    scopeAtEntry: string | null,
    generationAtCreation: number,
    independent: boolean,
  ): void {
    if (!independent && this.resetInFlight > 0) {
      throw new MemoryError(
        'not-ready',
        'memory reset in progress; store operation aborted',
      );
    }
    if (!independent && this.poolGeneration !== generationAtCreation) {
      throw new MemoryError(
        'not-ready',
        'memory was reset after this store was created; retry with a fresh store',
      );
    }
    this.assertScopeUnchanged(scopeAtEntry);
  }

  /** 关闭池内全部 db (作用域切换 / dispose / resetAll 共用)。幂等。 */
  private closeAllStores(): void {
    for (const [workdir, { db }] of this.stores) {
      try {
        db.close();
      } catch (e) {
        this.logger.warn('close store db failed', { workdir, error: String(e) });
      }
    }
    this.stores.clear();
    // 关闭 init 进行中的 db (review #2388 Codex 26th P1): 未入池的 open 句柄
    // 在 Windows 上会阻塞 resetAll 的 fs.rm — reset 扫描前必须全部关掉。
    for (const db of this.openingStores.keys()) {
      try {
        db.close();
      } catch (e) {
        this.logger.warn('close opening db failed', { error: String(e) });
      }
    }
    this.openingStores.clear();
  }

  /** Global Maker Memory reset must not close or invalidate Bot-owned stores. */
  private closeResettableStores(): void {
    for (const [scopeKey, entry] of this.stores) {
      if (entry.independent) continue;
      try {
        entry.db.close();
      } catch (e) {
        this.logger.warn('close resettable store db failed', { scopeKey, error: String(e) });
      }
      this.stores.delete(scopeKey);
    }
    for (const [db, independent] of this.openingStores) {
      if (independent) continue;
      try {
        db.close();
      } catch (e) {
        this.logger.warn('close opening resettable db failed', { error: String(e) });
      }
      this.openingStores.delete(db);
    }
  }

  /**
   * 跨 await 作用域复核 — owner 竞态守卫的第二道闸 (review #2388 P1):
   * 异步操作 (getStore 的 store.init、resetAll/resetDigests 的 fs 操作) 期间
   * owner 可能已提交/切换。用 ownerScopeKey() 的**实时值**与入口捕获的
   * scopeAtEntry 比较 (不能依赖 activeScopeKey —— 它只在 ensureOwnerScope
   * 被再次调用时才刷新), 不一致立即中止 fail-closed, 绝不把旧 owner 的结果
   * 提交到新 owner 的池/文件系统。
   */
  private assertScopeUnchanged(scopeAtEntry: string | null): void {
    if (!this.deps.ownerScopeKey) return;
    if (this.deps.ownerScopeKey() !== scopeAtEntry) {
      throw new MemoryError(
        'not-ready',
        'owner scope changed during async memory operation; aborting (retry against current scope)',
      );
    }
  }

  /**
   * Bootstrap-time agents 注入 — 解决"manager 需要 agents, agents 需要 manager"
   * 的鸡生蛋时序: manager 先建 (agents 传 {}) → agents 创建时拿 manager 引用 →
   * setAgents() 把 agents 挂回 manager。后续 enable() 才能遍历到。
   *
   * 仅在 host 装配阶段调一次, 不应该在运行期改。
   */
  setAgents(agents: Partial<Record<AgentKind, BaseAgent>>): void {
    this.deps.agents = agents;
  }

  // ── 状态查询 / 切换 ─────────────────────────────────────────────────────

  getState(): MakerMemoryState {
    return {
      enabled: this.enabled,
      activeWorkdirs: Array.from(this.stores.keys()).filter(
        (scopeKey) => !this.deps.isIndependentScope?.(scopeKey),
      ),
    };
  }

  /** No scope queries the global switch; host-owned independent scopes opt out. */
  isEnabled(scopeKey?: string): boolean {
    // 读取前同步 scope (review #2388 Codex 11th P1): rebindEnabled 只在
    // ensureOwnerScope/syncOwnerScope 里跑, 先读 isEnabled() 的路径 (withStore
    // 短路、session/remote option backfills) 会停留在旧 owner 的 flag —
    // owner A false→B true 时不得继续短路, B false→A true 时不得漏暴露。
    // 纯查询语义, 不抛 (owner 缺失由 getStore fail-closed)。
    this.syncOwnerScope();
    return this.enabled || (scopeKey !== undefined && this.deps.isIndependentScope?.(scopeKey) === true);
  }

  /**
   * 启用 maker memory:
   *  1. 标记 enabled = true
   *  2. 遍历所有 agent 调 setMemory(false) 强制关原生 (capabilities 不支持的跳过, 不抛)
   *  3. 后续 startSession 自动注入 memory MCP + system prompt
   *
   * 已经在跑的 session 不会 hot-reload, 改完下次 startSession 生效。
   */
  async enable(opts?: { skipAgentSync?: boolean }): Promise<SetEnabledResult> {
    this.enabled = true;
    if (opts?.skipAgentSync) {
      // 状态先行、原生联动延迟:host 的「延迟生效」路径(Codex 会话在 turn 内)
      // 需要 enabled 立刻翻转(新 session 的 memory 注入按新值走),但 native
      // setMemory 的 live-host RPC 热更新不能打进正在跑的 turn —— 由 host 在
      // 会话空闲后自行调 syncNativeAgentsOff() 补齐。
      this.logger.info('maker memory enabled (agent sync deferred by caller)');
      return { effective: 'next-session' };
    }
    const affected = await this.syncNativeAgentsOff();
    this.logger.info('maker memory enabled', { affectedAgents: affected });
    return { effective: 'next-session', affectedAgents: affected };
  }

  /**
   * enable 的原生联动步骤:把各 agent 的原生 memory 关掉(setMemory(false),
   * maker memory 接管)。CodexAgent.setMemory 会立即 RPC 热更新所有 live host,
   * 因此单独暴露 —— enable({skipAgentSync:true}) 的调用方在会话空闲后再补这一步。
   * kinds 可选:只同步指定 agent(Claude 的 setMemory 是纯内存覆盖、不碰
   * shared host,调用方可以立即同步 Claude、只把 Codex 延迟到空闲后)。
   */
  async syncNativeAgentsOff(
    kinds?: AgentKind[],
  ): Promise<NonNullable<SetEnabledResult['affectedAgents']>> {
    const affected: NonNullable<SetEnabledResult['affectedAgents']> = [];
    for (const [kind, agent] of Object.entries(this.deps.agents) as Array<[AgentKind, BaseAgent]>) {
      if (kinds && !kinds.includes(kind)) continue;
      try {
        const r = await agent.setMemory(false);
        affected.push({ kind, effective: r.effective });
      } catch (e) {
        if (e instanceof NotSupportedError) {
          affected.push({ kind, effective: 'unsupported' });
        } else {
          this.logger.warn('enable: agent.setMemory(false) failed', { kind, error: String(e) });
        }
      }
    }
    return affected;
  }

  /**
   * 关闭 maker memory:
   *  1. 标记 enabled = false
   *  2. 不主动恢复各 agent 的原生 memory (用户独立控制) — 避免覆盖用户后续手动 toggle
   *  3. 已 open 的 store / db 不立即 close (留给 dispose), 因为可能 mode 短期内又切回来
   *
   * 后续 startSession 不会注入 memory MCP, 但 active session 仍带着 memory MCP
   * 直到自然结束。
   */
  async disable(): Promise<SetEnabledResult> {
    this.enabled = false;
    this.logger.info('maker memory disabled (native memory unchanged)');
    return { effective: 'next-session' };
  }

  // ── Store 实例池 ─────────────────────────────────────────────────────────

  /**
   * 拿到某 workdir 的 Store. 第一次访问时 lazy 创建:
   *  - mkdir <basePath>/<sanitized-workdir>/
   *  - open SQLite db: <basePath>/<sanitized-workdir>/fts.db
   *  - 调 store.init() (创建 FTS 表 + sanity check)
   *
   * 同 workdir 复用同一 store + db 实例。失败 (db open 失败 / mkdir 失败) 抛错。
   *
   * key 语义: 本地会话传 workdir 绝对路径; SSH remote 会话传
   * buildMemoryScopeKey 产出的 `ssh:<hostId>:<path>` 复合键 (调用方负责,
   * manager 不自己判远端) — 见 storage.ts buildMemoryScopeKey。
   *
   * opts.skipDisabledCheck: 清理路径 (resetWorkdir) 用 — 用户关闭 maker memory
   * 后仍需能清空已有记忆, 重置入口按「不论 makerEnabled 值都能清」语义工作
   * (review #2388 Codex 10th P2)。
   */
  async getStore(
    absWorkdir: string,
    opts?: { skipDisabledCheck?: boolean },
  ): Promise<MakerMemoryStore> {
    if (!absWorkdir || absWorkdir.length === 0) {
      throw new Error('MakerMemoryManager.getStore: absWorkdir required');
    }
    // owner 作用域守卫: 缺 owner 直接拒绝 (不建临时库), scope 变化则换根。
    this.ensureOwnerScope();
    // 打开 store 路径的 disabled 检查 (review #2388 Codex 5th P1): 调用方
    // 可能已持过期 isEnabled()=true 快照 (withStore / session opts) 通过检查,
    // 换根后 enabled=false 不得继续打开新 owner store; 仅 host 提供
    // reloadEnabled 时判定 (静态宿主无 rebind 语义, disabled 由 isEnabled 拦)。
    const independentScope = this.deps.isIndependentScope?.(absWorkdir) === true;
    if (
      !opts?.skipDisabledCheck
      && this.deps.reloadEnabled
      && !this.enabled
      && !independentScope
    ) {
      throw new MemoryError(
        'not-ready',
        'maker memory disabled for current owner scope; refusing to open store',
      );
    }
    // resetAll 进行中 (review #2388 Greptile 16th/17th): 删除期间入池会导致目录
    // 被删后残留失效条目 / EBUSY — 并发 getStore 一律拒绝, 调用方重试。
    if (!independentScope && this.resetInFlight > 0) {
      throw new MemoryError('not-ready', 'memory reset in progress; retry shortly');
    }
    const cached = this.stores.get(absWorkdir);
    if (cached) {
      // 旧世代 (resetAll 后) 的缓存条目惰性失效: close + 移除, 走重建;
      // 不立即关闭已返回给调用方的实例 (review #2388 Greptile 16th)。
      if (cached.independent || cached.generation === this.poolGeneration) return cached.store;
      try {
        cached.db.close();
      } catch {
        /* swallow */
      }
      this.stores.delete(absWorkdir);
    }

    // 异步初始化期间的竞态锚点 (review #2388 P1): 整个流程用入口捕获的 scope +
    // root, 不再跨 await re-read 动态根; 完成后复核 scope 未变才提交入池。
    const scopeAtEntry = this.deps.ownerScopeKey?.() ?? null;
    // 池世代锚点 (review #2388 Codex 20th P1): init 等待期间并发 resetAll 可能
    // 开始**并完成** (resetInFlight 已回 0) — 用 generation 对比识别「重置前
    // 打开、closeAllStores 从未见过的 stale store」。
    const generationAtEntry = this.poolGeneration;
    const rootAtEntry = this.resolvedBasePath!;

    // 目录名派生见 memoryScopeDirName:本地键 = sanitizeWorkdir 原规则 (不迁移),
    // 远端 ssh: 键 = 碰撞安全的 hash 形态 (review R4 P2)。
    const sanitized = memoryScopeDirName(absWorkdir);
    const legacyStorageDir = path.join(rootAtEntry, MEMORY_SUBDIR, sanitized);
    const resolvedStorageDir = this.deps.resolveStorageDir?.(absWorkdir, rootAtEntry);
    const storageDir = resolvedStorageDir?.trim() || legacyStorageDir;
    const dbPath = path.join(storageDir, FTS_DB_FILENAME);

    // mkdir 在 storage.init() 里也会做, 但 db open 时父目录必须存在 — 提前 mkdir
    const fs = await import('node:fs');
    // await import 窗口后、mkdir/SQLite 打开前复核 (review #2388 Codex 22nd P2):
    // rootAtEntry 捕获后边界可能发生 — 不得用旧 root 创建目录/打开 fts.db。
    // 同时复核 reset 屏障 (review #2388 Codex 24th P1): resetAll 可能在本调用
    // 挂起于 import 时开始 — resetInFlight 在先前检查之后变正, scope-only 检查
    // 会放行 mkdir/open, Windows 上阻塞并发 fs.rm / POSIX 返回被删目录的 store。
    this.assertScopeUnchanged(scopeAtEntry);
    if (!independentScope && this.resetInFlight > 0) {
      throw new MemoryError('not-ready', 'memory reset started; retry shortly');
    }
    if (!independentScope && this.poolGeneration !== generationAtEntry) {
      throw new MemoryError('not-ready', 'memory reset completed; retry against current state');
    }
    /*
     * Custom stores (currently Bot Home memory) migrate only durable shard
     * files and retain the old directory for rollback. Derived indexes/SQLite
     * state are rebuilt by store.init(), and existing Home files always win.
     */
    if (
      storageDir !== legacyStorageDir
      && fs.existsSync(legacyStorageDir)
      && !fs.existsSync(path.join(storageDir, STORAGE_MIGRATION_RECEIPT))
    ) {
      try {
        fs.mkdirSync(storageDir, { recursive: true });
        this.assertScopeUnchanged(scopeAtEntry);
        copyLegacyMemoryShardsSync(legacyStorageDir, storageDir);
        const receipt = path.join(storageDir, STORAGE_MIGRATION_RECEIPT);
        const receiptTmp = `${receipt}.tmp-${process.pid}`;
        fs.writeFileSync(
          receiptTmp,
          `${JSON.stringify({ schemaVersion: 1, migratedAt: new Date().toISOString() })}\n`,
          'utf8',
        );
        fs.renameSync(receiptTmp, receipt);
      } catch (error) {
        if (!fs.existsSync(path.join(storageDir, STORAGE_MIGRATION_RECEIPT))) throw error;
      }
    }
    fs.mkdirSync(storageDir, { recursive: true });

    const db = this.deps.sqliteFactory(dbPath);
    // 注册 in-flight 打开的 db (review #2388 Codex 26th P1): init 完成前不在
    // this.stores, resetAll 需能关闭它避免 Windows fs.rm EBUSY 跳过该 workdir。
    this.openingStores.set(db, independentScope);
    const store = new MakerMemoryStore({
      storageDir,
      absWorkdir,
      db,
      logger: this.logger.child(`memory:${sanitized}`),
      ...(this.deps.config ? { config: this.deps.config } : {}),
      // store 级 mutation 前置守卫 (review #2388 Codex 5th P1): 裸 store 在
      // manager 守卫之外被调用方使用 (withStore fn / agent prompt 注入路径),
      // 后置复核无法撤销已发生的写操作 —— 锚定 store 创建时 scope, 每次
      // write/delete/consolidate 前复核, scope 已变即抛 not-ready。
      ...(this.deps.ownerScopeKey
        ? { scopeCheck: () => this.assertStoreOperable(scopeAtEntry, generationAtEntry, independentScope) }
        : {}),
    });
    try {
      await store.init();
    } catch (e) {
      // init 内 (storage.init 写 meta.json 前守卫 / fts 初始化) 可能已因 scope
      // 变化抛 not-ready — 关闭刚开的 db 防止句柄泄漏, 再重新抛出。
      try {
        db.close();
      } catch {
        /* swallow */
      }
      this.openingStores.delete(db);
      throw e;
    }
    this.openingStores.delete(db);
    // 跨 await 复核: 期间 owner 已切换 → 丢弃刚建的旧 owner store, fail-closed,
    // 绝不入池。用实时 ownerScopeKey() 比较 (不依赖 activeScopeKey 被刷新)。
    if (this.deps.ownerScopeKey && this.deps.ownerScopeKey() !== scopeAtEntry) {
      try {
        db.close();
      } catch {
        /* swallow */
      }
      this.logger.warn('getStore aborted: owner scope changed during async init', {
        scopeAtEntry,
        activeScope: this.activeScopeKey,
      });
      throw new MemoryError(
        'not-ready',
        'owner scope changed during store init; retry against current scope',
      );
    }
    // 跨 await 复核: init 等待期间并发 resetAll 已开始 (review #2388 Greptile
    // 18th P1) — 目标目录将被删除, 不得把指向它的 store 入池 (Windows 上 open
    // 的 fts.db 还会阻塞目录删除 / 返回指向已删目录的实例)。
    if (!independentScope && this.resetInFlight > 0) {
      try {
        db.close();
      } catch {
        /* swallow */
      }
      throw new MemoryError(
        'not-ready',
        'memory reset started during store init; retry against current state',
      );
    }
    // 跨 await 复核: init 等待期间 resetAll 已**完成** (review #2388 Codex 20th
    // P1) — resetInFlight 已回 0, 用 generation 对比识别: 本 store 是重置前
    // 打开的旧世代 (closeAllStores 从未关闭其 db, Windows 上阻塞目录删除 /
    // POSIX 返回指向已删目录的实例), 不得入池。
    if (!independentScope && this.poolGeneration !== generationAtEntry) {
      try {
        db.close();
      } catch {
        /* swallow */
      }
      throw new MemoryError(
        'not-ready',
        'memory reset completed during store init; retry against current state',
      );
    }
    // 并发去重: 同 workdir 的并发 getStore 可能已把 store 提交入池, 复用池内实例。
    // 仅复用同世代的 (resetAll 后旧世代条目先关闭, 由本调用重建覆盖)。
    const existing = this.stores.get(absWorkdir);
    if (existing) {
      if (existing.independent || existing.generation === this.poolGeneration) {
        try {
          db.close();
        } catch {
          /* swallow */
        }
        return existing.store;
      }
      try {
        existing.db.close();
      } catch {
        /* swallow */
      }
    }
    this.stores.set(absWorkdir, {
      store,
      db,
      independent: independentScope,
      generation: this.poolGeneration,
    });
    this.logger.debug('memory store opened', { workdir: absWorkdir, sanitized });
    return store;
  }

  /** 当前是否已 open 过某 workdir 的 store (manager.getState 也能看, 这里给热路径用) */
  hasStore(absWorkdir: string): boolean {
    return this.stores.has(absWorkdir);
  }

  // ── 重置 ─────────────────────────────────────────────────────────────────

  /** 清空某 workdir 全部 memory (UI 调) — 清理路径, 绕过 disabled 检查 */
  async resetWorkdir(absWorkdir: string): Promise<{ removedCount: number }> {
    const store = await this.getStore(absWorkdir, { skipDisabledCheck: true });
    return store.resetAll();
  }

  /**
   * 仅清空 Pi 压缩产生的 digest,绝不触碰用户维护的四类 curated memory。
   *
   * 已打开的 store 经 facade 删除以同步 FTS;未打开目录直接删 digest 文件,遗留的
   * FTS 行会在下次打开时被 sanityCheck 的计数差异触发重建。digest 本来就不进入
   * MEMORY.md,因此无需改写用户索引。
   */
  async resetDigests(): Promise<{ removedCount: number }> {
    this.ensureOwnerScope();
    // 竞态锚点 (review #2388 P1): 捕获 scope + root, 跨 await 不再 re-read 动态根;
    // 每次 fs 写操作前复核, owner 已切换则中止, 绝不扫/删新 owner 的目录。
    const scopeAtEntry = this.deps.ownerScopeKey?.() ?? null;
    const memoryRoot = path.join(this.resolvedBasePath!, MEMORY_SUBDIR);
    let total = 0;
    const activeDirs = new Set<string>();
    // 入口快照池 — owner 切换时 closeAllStores 会 clear Map, for-of 直遍历会提前
    // 结束; 用快照保证循环体仍按原 owner 的 store 逐项复核+处理 (review #2388)。
    const storeSnapshot = [...this.stores.entries()];
    for (const [workdir, { store }] of storeSnapshot) {
      if (this.deps.isIndependentScope?.(workdir)) continue;
      // 迭代前复核 (review #2388 第三轮 P1): resetType 自身 await (list/delete),
      // 期间 owner 切换会使本循环持有的 store 被 closeAllStores 关闭 —— 必须先
      // 复核再操作, 不得在切换后继续用已失效的 store。
      this.assertScopeUnchanged(scopeAtEntry);
      activeDirs.add(memoryScopeDirName(workdir));
      total += (await store.resetType('digest')).removedCount;
    }

    const fs = await import('node:fs/promises');
    this.assertScopeUnchanged(scopeAtEntry);
    let entries: string[];
    try {
      entries = await fs.readdir(memoryRoot);
    } catch {
      // 异常早退路径也复核 (review #2388 Greptile 24th P1): readdir await 期间
      // owner 切换 → 不得把部分完成的跨边界重置报为成功, 抛 not-ready 让调用方重试。
      this.assertScopeUnchanged(scopeAtEntry);
      return { removedCount: total };
    }
    for (const entry of entries) {
      if (activeDirs.has(entry)) continue;
      const dir = path.join(memoryRoot, entry);
      let filenames: string[];
      try {
        if (!(await fs.stat(dir)).isDirectory()) continue;
        this.assertScopeUnchanged(scopeAtEntry);
        filenames = await fs.readdir(dir);
      } catch {
        continue;
      }
      const botOwned = await isLegacyBotMemoryDir(dir);
      this.assertScopeUnchanged(scopeAtEntry);
      if (botOwned) continue;
      for (const filename of filenames) {
        if (parseFilename(filename)?.type !== 'digest') continue;
        try {
          this.assertScopeUnchanged(scopeAtEntry);
          await fs.unlink(path.join(dir, filename));
          total += 1;
        } catch (error) {
          if (error instanceof MemoryError && error.code === 'not-ready') throw error;
          this.logger.warn('resetDigests: failed to remove digest', {
            filename,
            error: String(error),
          });
        }
      }
    }
    // 删除后复核 (review #2388 Greptile 5th): 目标 root 在入口已固定为操作开始时
    // owner (不会误删新 owner), 但删除期间 owner 若已切换, 结果不可信 ——
    // fail-closed 抛 not-ready, 调用方不得按「成功清空」对待。
    if (this.deps.ownerScopeKey && this.deps.ownerScopeKey() !== scopeAtEntry) {
      this.logger.warn('resetDigests crossed owner boundary; aborting as not-ready', {
        scopeAtEntry,
      });
      throw new MemoryError(
        'not-ready',
        'owner scope changed during resetDigests; result is partial and must not be trusted',
      );
    }
    return { removedCount: total };
  }

  /** 清空所有 workdir 全部 memory. 慎用. */
  async resetAll(): Promise<{ removedCount: number }> {
    this.ensureOwnerScope();
    // 竞态锚点 (review #2388 P1): 捕获 scope + root, 跨 await 不再 re-read 动态根;
    // 每次目录删除前复核, owner 已切换则中止, 绝不递归删新 owner 的 maker-memory。
    const scopeAtEntry = this.deps.ownerScopeKey?.() ?? null;
    // 置位并发拒绝计数 (review #2388 Greptile 17th): 并发 resetAll 各自 +1,
    // 较早结束的 -1 后仍 >0, 不会提前解除屏障。
    this.resetInFlight += 1;
    try {
      // 只关闭全局 Maker Memory store。Bot-owned independent stores live in
      // Bot Home and are outside this reset's product boundary.
      this.closeResettableStores();
      const memoryRoot = path.join(this.resolvedBasePath!, MEMORY_SUBDIR);
      let total = 0;
      // 还没 open 的 workdir 文件也要清: 扫 basePath/maker-memory 下所有目录
      const fs = await import('node:fs/promises');
      this.assertScopeUnchanged(scopeAtEntry);
      let entries: string[] = [];
      try {
        entries = await fs.readdir(memoryRoot);
      } catch {
        // 空根/ENOENT 分支 (review #2388 Codex 21st P1): 也视为一次完成的 reset
        // 尝试 — 必须 bump generation, 否则 init 中暂停的 getStore 恢复后通过
        // generation 检查, 在用户可见的 reset 完成后写入新 memory。
        // 先复核 scope (review #2388 Greptile 23rd P1): readdir await 期间边界
        // 可能发生 — 不得把跨边界的 reset 误判为成功。
        this.assertScopeUnchanged(scopeAtEntry);
        return { removedCount: 0 };
      }
      for (const entry of entries) {
        const dir = path.join(memoryRoot, entry);
        try {
          const stat = await fs.stat(dir);
          if (!stat.isDirectory()) continue;
          const botOwned = await isLegacyBotMemoryDir(dir);
          this.assertScopeUnchanged(scopeAtEntry);
          if (botOwned) continue;
          await fs.rm(dir, { recursive: true, force: true });
          total += 1;
        } catch (e) {
          if (e instanceof MemoryError && e.code === 'not-ready') throw e;
          this.logger.warn('resetAll: failed to remove workdir memory dir', {
            dir,
            error: String(e),
          });
        }
      }
      // 删除后复核 (review #2388 Greptile 5th): 目标 root 在入口已固定为操作开始时
      // owner (不会误删新 owner), 但删除期间 owner 若已切换, 结果不可信 ——
      // fail-closed 抛 not-ready, 调用方不得按「成功清空」对待。
      if (this.deps.ownerScopeKey && this.deps.ownerScopeKey() !== scopeAtEntry) {
        this.logger.warn('resetAll crossed owner boundary; aborting as not-ready', {
          scopeAtEntry,
        });
        throw new MemoryError(
          'not-ready',
          'owner scope changed during resetAll; result is partial and must not be trusted',
        );
      }
      return { removedCount: total };
    } finally {
      // closeResettableStores invalidates its handles even if ambiguous
      // ownership aborts the reset. Retained callers must reopen their store.
      this.poolGeneration += 1;
      this.resetInFlight -= 1;
    }
  }

  // ── Review (LLM 自审) ────────────────────────────────────────────────────

  /**
   * 让 LLM 审查当前 workdir 的所有 memory, 找出矛盾/过期/可合并条目。
   * 返回 LLM 的建议文本 (LLM 自己决定是否 follow up consolidate/delete tool 调用)。
   *
   * 不在 manager 内自动执行 delete/consolidate — 让 LLM 在 turn 内决定 + 走标准
   * write/delete tool, 保留可观测性。manager 只是 "起一次审查 LLM 调用" 的入口。
   */
  async runReview(absWorkdir: string): Promise<{ suggestions: string }> {
    // 竞态锚点 (review #2388 Codex 9th P1): 读记录与发 oneShot 之间有 await
    // (isOneShotRouteDisabled / agent 派发), 边界窗口内不得把旧 owner 的
    // memory dump 发给 review LLM — 构造/发送 prompt 前复核 scope。
    const scopeAtEntry = this.deps.ownerScopeKey?.() ?? null;
    const store = await this.getStore(absWorkdir);
    const records = await store.list();
    if (records.length === 0) {
      return { suggestions: 'No memories in this workdir yet.' };
    }
    const reviewAgentKind = this.deps.reviewAgent ?? 'claude-code';
    if (await this.deps.isOneShotRouteDisabled?.(reviewAgentKind)) {
      throw new Error(
        `runReview: one-shot route for '${reviewAgentKind}' is disabled in settings`,
      );
    }
    // 发送前复核: 边界已切换则丢弃旧 owner 的 records, fail-closed。
    this.assertScopeUnchanged(scopeAtEntry);

    const summary = records
      .map((r) => `### ${r.filename}\n- title: ${r.frontmatter.title}\n- description: ${r.frontmatter.description}\n- updatedAt: ${r.frontmatter.updatedAt}\n\n${r.body}`)
      .join('\n\n---\n\n');
    const prompt = [
      'You are reviewing a memory store for consistency.',
      'For each potential issue, classify as: contradiction / outdated / duplicate / fine.',
      'Output a concise plan (<= 200 words) listing which files to delete or merge and why.',
      '',
      `Memory dump (${records.length} entries):`,
      '',
      summary,
    ].join('\n');

    // host 注入的自定义一次性调用优先(共享辅助模型链); agent 查找推迟到这里: 注入链
    // 缺席时未注册 review agent 才该把 review 硬拦死。
    const injectedChain = this.deps.reviewOneShot !== undefined;
    const custom = injectedChain
      ? await this.deps.reviewOneShot!(prompt, REVIEW_ONE_SHOT_OPTS)
      : null;
    // 辅助链的 await 可能横跨账号边界(链因此中止并返回 null)。此时旧 owner 的
    // dump 一条都不能再发: 回落默认路由会读新账号凭据, 而末尾复核只能挡住返回,
    // 撤不回已发出的 prompt。任一分支出发前必须重新复核, fail-closed 抛出。
    this.assertScopeUnchanged(scopeAtEntry);
    if (custom && custom.trim().length > 0) {
      return { suggestions: custom };
    }
    // 宿主注入了链 = 用户显式指定了本次审查的路由。链上没产出时再回退 review agent
    // 默认路由, 只会落到硬编码的 claude-haiku-4-5, 对没有 Anthropic 权限的账号必然
    // 403, 用户看到的是与真实原因无关的死路(2026-10-14 实测)。改成一句可读原因。
    if (injectedChain) {
      throw new Error(
        'runReview: auxiliary model chain produced no text; configure an available auxiliary model in Settings',
      );
    }
    const agent = this.deps.agents[reviewAgentKind];
    if (!agent) {
      throw new Error(`runReview: review agent '${reviewAgentKind}' not registered`);
    }
    const suggestions = await agent.oneShot(prompt, REVIEW_ONE_SHOT_OPTS);
    // oneShot await 后、返回前复核 (review #2388 Codex 21st P1): 边界在 LLM
    // 调用期间发生则建议文本基于旧 owner 数据 — 不得向当前 session 报 ok。
    this.assertScopeUnchanged(scopeAtEntry);
    return { suggestions };
  }

  /** 直接给 store 一个 write 入口. mcp-server 层会拿这个 (而不是先 getStore 再 write) */
  async write(absWorkdir: string, opts: WriteOptions) {
    const store = await this.getStore(absWorkdir);
    return store.write(opts);
  }

  // ── 生命周期 ────────────────────────────────────────────────────────────

  /** Maker.shutdown 调 (跟 agent.dispose 同时机). 关闭所有 db, 清池. 幂等. */
  dispose(): void {
    this.closeAllStores();
    this.logger.info('MakerMemoryManager disposed');
  }
}