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。

81.1 KB
Raw Blame
/**
 * Maker — Session 注册中心 + Agent 路由。
 *
 * 当前职责(一阶段):
 * - 持有按 AgentKind 注册的 BaseAgent 实例
 * - 按 (agentKind, workDir) 创建 Session
 * - 维护 Session 列表
 *
 * 未来扩展(MetaAgent 升级):
 * - 自带 LLM 决策循环 → 当前类做成 extends-friendly(关键方法 protected)
 * - workdir-scoped 记忆 / constraints → 预留 deps 字段
 *
 * 不做:
 * - UI 状态、权限弹窗(host 注入 PermissionListener)
 * - 业务 token 管理、飞书业务态
 */

import { DEFAULT_DRAFT_SESSION_TITLE } from '@cindy/maker-shared/session-title';
import fs from 'node:fs';
import path from 'node:path';
import { clearTimeout as clearNodeTimeout, setTimeout as setNodeTimeout } from 'node:timers';

import type { AgentKind } from './types/common.js';
import type { Capabilities } from './types/capabilities.js';
import {
  isTerminalAgentErrorEvent,
  type AgentEvent,
  type ForkSdkSessionOptions,
  type ForkSdkSessionResult,
} from './types/events.js';
import type {
  ScanAtResourcesOptions,
  ScanAtResourcesResult,
  AgentBuiltinCommand,
  ListAgentSkillsOptions,
  ListAgentSkillsResult,
  ListRuntimeSkillsOptions,
} from './types/palette.js';
import type {
  ListCustomizationsOptions,
  ListCustomizationsResult,
} from './types/customizations.js';
import type { PiRuntimeCapabilityManifest } from './types/pi-runtime-capabilities.js';
import { piExplicitSkillRuntimePath } from './agents/pi/skill-runtime-provenance.js';
import { fingerprintPiProjectSkillEntrypoint } from './agents/pi/project-resource-assembly.js';
import { Session, generateSessionId, type SessionStartupPreferences } from './session.js';
import { withFastModePolicy } from './agents/shared/fast-mode-policy.js';
import { NotSupportedError } from './types/capabilities.js';
import {
  AgentNotAuthenticatedError,
  AgentStartupCleanupPendingError,
  AgentStartupStoppedError,
  LOCAL_AGENT_CLIENT,
} from './agents/base-agent.js';
import type {
  AgentSessionHandle,
  AgentSessionTeardownOptions,
  AgentSessionTeardownReason,
  BaseAgent,
  StartSessionOptions,
  OneShotOptions,
  RefreshLocalModelsOptions,
} from './agents/base-agent.js';
import type { MemoryStatus, MemorySetResult, MemoryResetResult } from './types/memory.js';
import type { ConsumeAccountRateLimitResetCreditParams } from './types/account-rate-limits.js';
import type { SessionStorage, SessionMeta } from './interfaces/session-storage.js';
import type { Logger } from './interfaces/logger.js';
import type { AuthLoginOptions } from './interfaces/auth-adapter.js';
import type { MakerMemoryManager } from './memory/manager.js';

/**
 * Session 生命周期钩子 —— host 层声明 session 启动 / 成功发布 / 关闭时的副作用。
 * Maker 不知道 hook 内部干什么 (持久化上下文 / worktree / temp 文件 / metric / ...)。
 *
 * 设计动机: 把 desktop-specific 的 cleanup (worktree / OS temp 文件) 集中在 host
 * 一处声明,避免散落在各个 IPC handler 的 post-hook 里; maker-core 抽象保持干净
 * (零 Electron / 零 file system 概念)。
 */
export interface SessionBeforeStartContext {
  agentKind: AgentKind;
  workingDir: string;
  remoteHostId?: string;
}

export interface SessionStartFailureContext {
  sessionId: string;
  options: CreateSessionOptions;
  stage: 'prepare' | 'agent-start' | 'storage';
  error: unknown;
  /** Startup entered the adapter without confirmed exit; host runtime guards must remain protective. */
  runtimeMayBeAlive?: boolean;
}

export interface SessionLifecycleHooks {
  /**
   * Agent 启动前补齐 start options。该步骤属于正确启动的前置条件,失败会阻断创建。
   * 允许直接修改 options;Maker 会把同一个对象传给 agent 和成功钩子。
   */
  prepareStartOptions?: (sessionId: string, options: CreateSessionOptions) => void | Promise<void>;
  /** Agent 启动前的 host 准备动作。失败只记日志,不阻断 session 创建。 */
  onBeforeStart?: (context: SessionBeforeStartContext) => void | Promise<void>;
  /** Agent 和 Session 均创建成功后、对外发布前调用。失败只记日志,不阻断创建。 */
  onStartSucceeded?: (sessionId: string, options: CreateSessionOptions) => void | Promise<void>;
  /**
   * Session 尚未发布前的启动失败。Host 可据此收口 prepare 阶段创建的审计记录;
   * hook 自身失败只记日志,绝不覆盖原始启动错误。
   */
  onStartFailed?: (context: SessionStartFailureContext) => void | Promise<void>;
  /** Failed startup's handle was finally closed after deferred cleanup; no task ownership change. */
  onStartCleanupSucceeded?: (sessionId: string, options: CreateSessionOptions) => void | Promise<void>;
  /** session 关闭时调用;options 始终属于该次启动,不从当前同 id 的 runtime 取值。 */
  onClose?: (sessionId: string, options: CreateSessionOptions) => void | Promise<void>;
  /**
   * Codex-only: resume 前读取该业务 session 对应 thread history 是否已可靠包含
   * 产品 prompt。读取失败由 Maker 视为 unknown,让 Codex fail toward restore。
   */
  getCodexHistoryHasProductPrompt?: (sessionId: string) => boolean | undefined | Promise<boolean | undefined>;
  /**
   * Codex-only: start/resume 成功后写入真实投递事实。只在 handle 有有效 threadId
   * 且 agent 明确报告 delivery 时调用;失败只记日志,不阻塞 session 创建。
   */
  onCodexProductPromptDelivery?: (args: {
    sessionId: string;
    threadId: string;
    historyHasProductPrompt: boolean;
  }) => void | Promise<void>;
}

export interface MakerDeps {
  agents: Partial<Record<AgentKind, BaseAgent>>;
  /**
   * 可选:在同账号另一台电脑上启动 Agent(CreateSessionOptions.agentDeviceId)。返回的句柄由
   * host 实现(对方运行 Agent、本机执行文件与命令)。缺省时这类会话无法创建。
   */
  startDeviceAgentSession?: (input: {
    agentKind: AgentKind;
    deviceId: string;
    options: StartSessionOptions;
  }) => Promise<AgentSessionHandle>;
  storage: SessionStorage;
  logger: Logger;
  /** 可选: session 生命周期副作用钩子 (host 层注入)。详见 SessionLifecycleHooks。 */
  lifecycleHooks?: SessionLifecycleHooks;
  /**
   * 可选: Maker Memory 顶层单例 (host 注入)。host 在创建 Maker 前先实例化
   * MakerMemoryManager (传 sqliteFactory + userDataPath + agents), 再传给 Maker。
   * 缺省时 Maker.makerMemory 为 undefined, agent 端 startSession 不注入 memory 段
   * (即跟改造前行为一致, native auto-memory 走自家)。
   */
  makerMemory?: MakerMemoryManager;
  /**
   * 可选: 视觉桥钩子(层 B)的全局默认。host 创建 Maker 时注入一次,所有
   * createSession 自动带上;单个 createSession 的 visionBridge 优先。缺省不注入 =
   * 零干扰(见 docs/vision-bridge-design.md 层 B)。
   */
  visionBridge?: import('./types/vision-bridge.js').VisionBridgeHook;
  /**
   * 可选: Pi / Codex 工具循环疑似命中时的辅助模型复核入口。Claude Code 在 agent 内
   * 检测,由 AgentDeps.toolLoopReviewer 注入同一实现。缺省放行疑似,保留最终上限。
   */
  toolLoopReviewer?: import('./agents/shared/tool-loop-review.js').ToolLoopReviewer;
}

/** A previous attempt still owns native resources; retry without changing route/history. */
export class SessionCreationCleanupPendingError extends Error {
  constructor(options?: ErrorOptions) {
    super('Previous session startup cleanup is still pending; retry the task.', options);
    this.name = 'SessionCreationCleanupPendingError';
  }
}

export interface CreateSessionOptions extends StartSessionOptions {
  /** Host caller preferences before generated context; retained only by the live Session. */
  hostStartupPreferences?: SessionStartupPreferences;
  agentKind: AgentKind;
  /** 可选:UI 显示用 */
  title?: string;
  /**
   * 可选:视觉桥钩子(层 B)。host 注入后,session.send 在把用户贴图交给 agent 前
   * 用视觉模型转成文字描述(见 docs/vision-bridge-design.md 层 B)。缺省不注入 = 零干扰。
   */
  visionBridge?: import('./types/vision-bridge.js').VisionBridgeHook;
  /** 可选:父会话 id,用于 fork / orchestration 等会话关系。 */
  parentSessionId?: string;
  /**
   * 可选:Agent 在同账号的另一台电脑上运行(那台电脑的设备 id)。任务、项目文件与命令留在本机,
   * Agent 用那台电脑的程序、登录、供应商与网络。由 MakerDeps.startDeviceAgentSession 启动;
   * 持久化到 SessionMeta.agentDeviceId,恢复时据此找回那台电脑。与 remoteHostId 互斥。
   */
  agentDeviceId?: string;
  /**
   * 可选:调用方提供的 sessionId(通常来自外部 DB row)。提供后:
   *   - storage 已有同 id 的 row → 跳过 create, 直接复用
   *   - storage 没有 → 用此 id 创建新 row
   * 不提供则 maker 自己生成 uuid。chat 切换场景必传(本端 sessions 表的 id 来自
   * local-db:sessions:create, maker 必须复用而不是再生成一个)。
   */
  id?: string;
}

export type MakerSessionCloseReason =
  | 'requested'
  | 'agent-switch'
  | 'runtime-refresh'
  | 'unexpected';

export type MakerEvent =
  | { type: 'session:created'; session: Session }
  | {
      type: 'session:closed';
      sessionId: string;
      session: Session;
      reason: MakerSessionCloseReason;
    };

export type MakerEventListener = (event: MakerEvent) => void;

/** Codex thread 归属键:SSH 主机或运行 Agent 的另一台电脑(两者的 thread 都不在本机)。 */
function codexThreadOwnerKey(opts: { remoteHostId?: string; agentDeviceId?: string }): string | undefined {
  return opts.remoteHostId ?? (opts.agentDeviceId ? `device:${opts.agentDeviceId}` : undefined);
}

function capabilitiesForSession(
  agentKind: AgentKind,
  base: Capabilities,
  remoteHostId?: string | null,
  agentDeviceId?: string | null,
  handle?: AgentSessionHandle,
): Capabilities {
  if (agentDeviceId) {
    // Agent 在另一台电脑上:对话在那台截断(handle 转发 commitRewindFiles),文件由本机按保存点
    // 回退。那台的 Cindy 不支持转发时不提供。
    if (base.rewind.supported && typeof handle?.commitRewindFiles === 'function') return base;
    return {
      ...base,
      rewind: {
        supported: false,
        reason: 'platform-limited',
        message: 'Update Cindy on the computer running the agent to rewind this task',
      },
    };
  }
  if (agentKind !== 'codex' || !remoteHostId) return base;
  return {
    ...base,
    rewind: {
      supported: false,
      reason: 'platform-limited',
      message: '远端 Codex 会话暂不支持对话 rewind',
    },
  };
}

/** External applications use only this small Session surface. Remote handles
 * enforce the peer's actual capabilities; no local binary is required. */
function applicationHandleCapabilities(handle: AgentSessionHandle): Capabilities {
  const no = { supported: false, reason: 'not-implemented' } as const;
  const yes = { supported: true } as const;
  return {
    switchModel: no, availableModels: [], hasFastMode: false,
    effort: handle.setEffort ? yes : no, effortLevels: [], reasoningDisplay: [],
    permissionModes: [], setPermissionModeMidSession: no,
    multimodal: { text: yes, image: yes, file: no },
    fork: no, rewind: no, abort: yes, sameTurnSteer: yes,
    memory: { supported: no }, extraDirs: no,
  };
}

function canonicalPiRuntimePath(value: string): string {
  try {
    return fs.realpathSync(value);
  } catch {
    return path.resolve(value);
  }
}

// Windows realpath/stat calls can legitimately take longer than 250 ms under
// concurrent CI or endpoint scanning even for a tiny skill tree. Keep the
// entry budget as the complexity bound, but give the fail-closed fingerprint
// enough wall-clock time to preserve an unchanged launch snapshot's loaded
// status across supported platforms.
const PI_PROJECT_SKILL_PALETTE_FINGERPRINT_TIMEOUT_MS = 1_000;
const PI_PROJECT_SKILL_PALETTE_FINGERPRINT_ENTRY_BUDGET = 2_048;

async function fingerprintPiProjectSkillForPalette(
  sourcePath: string,
  canonicalRepoRoot: string,
  budget: { remainingEntries: number; deadlineAtMs: number },
): ReturnType<typeof fingerprintPiProjectSkillEntrypoint> {
  const remainingMs = budget.deadlineAtMs - Date.now();
  if (remainingMs <= 0) return null;
  let timeout: number | NodeJS.Timeout | undefined;
  try {
    return await Promise.race([
      fingerprintPiProjectSkillEntrypoint(sourcePath, canonicalRepoRoot, { budget }),
      new Promise<null>((resolve) => {
        timeout = setNodeTimeout(() => resolve(null), remainingMs);
      }),
    ]);
  } finally {
    if (timeout) clearNodeTimeout(timeout);
  }
}

async function mergePiRuntimeSkillStatuses(
  result: ListAgentSkillsResult,
  manifest: PiRuntimeCapabilityManifest | undefined,
): Promise<ListAgentSkillsResult> {
  // The global managed-package store can change while a task is running. An
  // active Pi task must expose only its launch-time roster, never a fresh scan
  // that makes a newly installed or renamed skill look executable mid-session.
  const currentManagedSkills = result.skills.filter((skill) => skill.runtimeStatus === 'approved');
  const nonManagedSkills = result.skills.filter((skill) => skill.runtimeStatus !== 'approved');
  const managedSnapshot = manifest?.managedPackageSkills;
  const managedSkills = managedSnapshot
    ? managedSnapshot.map((skill) => ({
        kind: 'agent-skill' as const,
        name: skill.name,
        ...(skill.description ? { description: skill.description } : {}),
        source: 'skill' as const,
        path: skill.sourcePath,
        origin: 'package' as const,
        scope: 'user' as const,
        enabled: true,
        runtimeStatus: skill.runtimeCommandName ? 'loaded' as const : 'unknown' as const,
        ...(skill.runtimeCommandName ? { runtimeCommandName: skill.runtimeCommandName } : {}),
      }))
    : currentManagedSkills.map((skill) => ({
        ...skill,
        runtimeStatus: 'unknown' as const,
        runtimeCommandName: undefined,
      }));
  const sessionResult: ListAgentSkillsResult = {
    ...result,
    skills: [...nonManagedSkills, ...managedSkills],
  };
  if (manifest?.status !== 'loaded') return sessionResult;
  const loadedExplicitSkills = new Map<string, string>();
  const loadedLegacyProjectSkills = new Map<string, string>();
  const changedProjectSkills = new Map<string, string>();
  const fingerprintBudget = {
    remainingEntries: PI_PROJECT_SKILL_PALETTE_FINGERPRINT_ENTRY_BUDGET,
    deadlineAtMs: Date.now() + PI_PROJECT_SKILL_PALETTE_FINGERPRINT_TIMEOUT_MS,
  };
  for (const skill of manifest.projectResources?.loadedSkills ?? []) {
    const canonicalSourcePath = canonicalPiRuntimePath(skill.sourcePath);
    if (!skill.snapshotDigest || !skill.sourceFingerprint || !skill.canonicalRepoRoot) {
      changedProjectSkills.set(canonicalSourcePath, skill.sourcePath);
      continue;
    }
    const currentFingerprint = await fingerprintPiProjectSkillForPalette(
      skill.sourcePath,
      skill.canonicalRepoRoot,
      fingerprintBudget,
    );
    if (
      currentFingerprint?.contentDigest !== skill.snapshotDigest
      || currentFingerprint.sourceStateDigest !== skill.sourceFingerprint
    ) {
      changedProjectSkills.set(canonicalSourcePath, skill.sourcePath);
      continue;
    }
    loadedExplicitSkills.set(canonicalSourcePath, skill.commandName);
  }
  for (const command of manifest.commands) {
    const baseDir = command.sourceInfo.baseDir;
    if (command.source !== 'skill' || !command.name.startsWith('skill:')) continue;
    const skillName = command.name.slice('skill:'.length);
    // Explicit --skill is `project` on Windows and `temporary` on macOS.
    // Match that provenance by path first so frontmatter aliases still load.
    const explicitPath = piExplicitSkillRuntimePath(command);
    if (explicitPath) {
      loadedExplicitSkills.set(canonicalPiRuntimePath(explicitPath), command.name);
      if (typeof command.sourceInfo.path === 'string') {
        loadedExplicitSkills.set(canonicalPiRuntimePath(command.sourceInfo.path), command.name);
      }
      continue;
    }
    if (command.sourceInfo.scope === 'project' && typeof baseDir === 'string') {
      loadedLegacyProjectSkills.set(
        [skillName, canonicalPiRuntimePath(baseDir)].join('\0'),
        command.name,
      );
    }
  }
  if (
    loadedExplicitSkills.size === 0
    && loadedLegacyProjectSkills.size === 0
    && changedProjectSkills.size === 0
  ) return sessionResult;
  const changedSkillErrors = [...changedProjectSkills.values()].map((skillPath) => ({
    path: skillPath,
    message: 'Project skill changed after this Pi session started; restart the session to load the current version.',
  }));
  return {
    ...sessionResult,
    skills: sessionResult.skills.map((skill) => {
      let runtimeCommandName: string | undefined;
      if (skill.scope === 'repo' && skill.path) {
        const canonicalSkillPath = canonicalPiRuntimePath(skill.path);
        if (!changedProjectSkills.has(canonicalSkillPath)) {
          runtimeCommandName = loadedExplicitSkills.get(canonicalSkillPath)
            ?? loadedExplicitSkills.get(canonicalPiRuntimePath(path.dirname(skill.path)))
            ?? [skill.path, path.dirname(skill.path), path.dirname(path.dirname(skill.path))]
              .map(canonicalPiRuntimePath)
              .map((skillPath) => loadedLegacyProjectSkills.get([skill.name, skillPath].join('\0')))
              .find((commandName) => commandName !== undefined);
        }
      }
      return runtimeCommandName
        ? { ...skill, runtimeStatus: 'loaded' as const, runtimeCommandName }
        : skill;
    }),
    ...(changedSkillErrors.length > 0
      ? { errors: [...(sessionResult.errors ?? []), ...changedSkillErrors] }
      : {}),
  };
}

function isClaimableCodexThreadId(id: string | undefined): id is string {
  return (
    typeof id === 'string' &&
    id.length > 0 &&
    !id.startsWith('<') &&
    /^[0-9a-fA-F-]+$/.test(id)
  );
}

function codexThreadClaimKey(remoteHostId: string | undefined, threadId: string): string {
  return JSON.stringify([remoteHostId ?? null, threadId]);
}

interface CodexThreadClaimOwner {
  token: symbol;
  sessionId: string;
  sessionInstanceId: string;
}

interface CodexThreadClaimLease {
  moveTo(threadId: string): void;
  release(): void;
}

/**
 * What `Maker.shutdown` could not tear down.
 *
 * Additive and, until now, unobservable: shutdown collected per-session detach
 * failures, logged them, and resolved anyway. A caller that hands the runtime to
 * a different owner afterwards needs to know, because a PI session whose detach
 * threw may still have a live process — and that process owns durable Subagent
 * children holding BYOM credentials the outgoing account cannot revoke.
 */
export interface MakerShutdownReport {
  sessionFailures: Array<{ sessionId: string; agentKind: AgentKind; error: unknown }>;
}

interface FailedHandleCleanup {
  handle: AgentSessionHandle;
  promise: Promise<void> | null;
  onCleaned?: () => void;
}

/**
 * 在另一台电脑上运行的 Claude Code 会话,其新 vendor id(fork / 重建出的 id)要等这一轮
 * 成功结束才写成持久编号。`pending` 只在同一 session 的持久化队列里读写,保证与事件同序。
 */
interface DeferredSdkSessionCommit {
  pending?: string;
}

/**
 * 这一轮没有正常落地:与对方电脑失联,或对方的 Claude 流中途崩溃 / resume 失败。
 * 这类回合里新 fork 出的编号可能还没有对话记录,不能写成持久编号。
 * 用户主动 Stop 等其它收尾不在此列:Claude 已经收下输入并写了记录,下一轮应接着它走。
 */
const UNFINISHED_TURN_REASONS = new Set([
  'remote_agent_closed',
  'remote_agent_lost',
  'sdk_stream_crashed',
  'bridge_sdk_stream_crashed',
  'resume_session_not_found',
  'resume_session_recovery_failed',
]);

function isUnfinishedRemoteTurnEvent(evt: AgentEvent): boolean {
  const data = evt.data;
  if (!data || typeof data !== 'object' || Array.isArray(data)) return false;
  const { reason, message } = data as { reason?: unknown; message?: unknown };
  if (typeof reason === 'string' && UNFINISHED_TURN_REASONS.has(reason)) return true;
  return typeof message === 'string'
    && /\[REMOTE_AGENT_(EXPIRED|DEVICE_UNREACHABLE|NOT_FOUND|UNAVAILABLE)\]/.test(message);
}

export class Maker {
  protected readonly agents: Partial<Record<AgentKind, BaseAgent>>;
  protected readonly storage: SessionStorage;
  protected readonly logger: Logger;
  protected readonly lifecycleHooks: SessionLifecycleHooks;
  protected readonly activeSessions = new Map<string, Session>();
  protected readonly listeners = new Set<MakerEventListener>();
  /**
   * 同一 business session 的启动必须 singleflight。activeSessions 只在所有异步
   * startup / storage 步骤完成后写入;没有这层占位时,并发恢复会各自 spawn SDK
   * handle,Codex 同 thread 的后一个 subscriber 会覆盖前一个并让前一个 send 永久悬挂。
   */
  private readonly inFlightSessionCreations = new Map<
    string,
    { promise: Promise<Session>; signal?: AbortSignal }
  >();
  /** All create paths, including anonymous ids, that may still publish or quarantine a handle. */
  private readonly pendingSessionCreations = new Set<Promise<Session>>();
  /** Application-owned transcripts use the normal in-memory lifecycle without private storage. */
  private readonly localAgentSessions = new Set<Session>();
  /** Once shutdown starts, no new handle may race past its creation barrier. */
  private shutdownStarted = false;
  /**
   * Fences local ordinary Pi startups against managed-package mutations. A
   * startup captures this before its first await and may publish only if the
   * value is unchanged after every startup hook has settled.
   */
  private localPiPackageRuntimeGeneration = 0;
  /**
   * startSession 已返回、但 Session 尚未发布时 cleanup 失败的 handle。后续同 id
   * create 必须先把它确认关闭,不能丢失所有权后再 spawn 一个并存进程。
   */
  private readonly failedHandleCleanups = new Map<string, FailedHandleCleanup>();
  /**
   * Codex 0.145 会忽略已加载 thread 的 thread/resume.config。不同 Cindy task
   * 若同时复用同一 native thread,后启动者会继续使用前一 Session 的 MCP URL,
   * 使实例绑定失配并破坏通知路由。按 target(local / remote host)+thread 独占;
   * claim 由启动前持有到 Session 真正 close,禁止覆盖或抢占。
   */
  private readonly activeCodexThreadClaims = new Map<string, CodexThreadClaimOwner>();
  /**
   * 同一 business session 的 vendor id 写入必须串行。invalid-resume CAS 只有排在
   * 已在途的 session_id update 之后执行,才能保证旧写入不会在清空后反向覆盖。
   */
  private readonly sdkSessionPersistenceTails = new Map<string, Promise<void>>();
  /** 已确认失效的 vendor id;用于丢弃 CAS 之后才到达的旧 query session_id 事件。 */
  private readonly invalidSdkSessionIds = new Map<string, Set<string>>();
  /** Explicit close cause keyed by the exact Session instance that will emit closed. */
  private readonly closeReasons = new WeakMap<Session, MakerSessionCloseReason>();
  /** Host cleanup hooks must settle before Maker.shutdown() releases its process barrier. */
  private readonly pendingLifecycleCloses = new Set<Promise<void>>();
  /** Maker Memory 顶层单例 (可选). undefined 时 maker memory 功能整体禁用. */
  public readonly makerMemory: MakerMemoryManager | undefined;
  /** 视觉桥钩子(层 B)全局默认(可选)。见 MakerDeps.visionBridge。 */
  protected readonly visionBridge: import('./types/vision-bridge.js').VisionBridgeHook | undefined;
  private readonly toolLoopReviewer: import('./agents/shared/tool-loop-review.js').ToolLoopReviewer | undefined;
  private readonly startDeviceAgentSession: MakerDeps['startDeviceAgentSession'];

  constructor(deps: MakerDeps) {
    this.agents = deps.agents;
    this.storage = deps.storage;
    this.startDeviceAgentSession = deps.startDeviceAgentSession;
    this.visionBridge = deps.visionBridge;
    this.toolLoopReviewer = deps.toolLoopReviewer;
    // 不 child 自己名字 — host 传进来的 logger 通常已经命名(如 'maker'),
    // 再 child 'maker' 会变成 'maker/maker'。host 自己决定 root scope 名字。
    this.logger = deps.logger;
    this.lifecycleHooks = deps.lifecycleHooks ?? {};
    this.makerMemory = deps.makerMemory;
    this.logger.info('Maker initialized', {
      agents: Object.keys(this.agents),
      hasOnBeforeStartHook: !!this.lifecycleHooks.onBeforeStart,
      hasOnCloseHook: !!this.lifecycleHooks.onClose,
      makerMemory: !!this.makerMemory,
    });
  }

  private claimCodexThread(params: {
    sessionId: string;
    sessionInstanceId: string;
    remoteHostId?: string;
    threadId: string;
  }): CodexThreadClaimLease {
    const owner: CodexThreadClaimOwner = {
      token: Symbol('codex-thread-claim'),
      sessionId: params.sessionId,
      sessionInstanceId: params.sessionInstanceId,
    };
    let currentKey: string | null = null;
    let released = false;

    const moveTo = (threadId: string): void => {
      if (released) throw new Error('Codex thread claim was already released');
      const nextKey = codexThreadClaimKey(params.remoteHostId, threadId);
      if (nextKey === currentKey) return;
      const existing = this.activeCodexThreadClaims.get(nextKey);
      if (existing && existing.token !== owner.token) {
        throw new Error(
          `Codex thread ${threadId} is already active in another Cindy task. Close that task and try again.`,
        );
      }
      this.activeCodexThreadClaims.set(nextKey, owner);
      const previousKey = currentKey;
      currentKey = nextKey;
      if (
        previousKey &&
        previousKey !== nextKey &&
        this.activeCodexThreadClaims.get(previousKey)?.token === owner.token
      ) {
        this.activeCodexThreadClaims.delete(previousKey);
      }
    };

    moveTo(params.threadId);
    return {
      moveTo,
      release: () => {
        if (released) return;
        released = true;
        if (
          currentKey &&
          this.activeCodexThreadClaims.get(currentKey)?.token === owner.token
        ) {
          this.activeCodexThreadClaims.delete(currentKey);
        }
        currentKey = null;
      },
    };
  }

  private async retryFailedHandleCleanup(
    sessionId: string,
    expectedEntry?: FailedHandleCleanup,
  ): Promise<void> {
    const entry = this.failedHandleCleanups.get(sessionId);
    if (!entry || (expectedEntry && entry !== expectedEntry)) return;
    // Startup-failure rollback, not an ownership change.
    const cleanup = entry.promise ?? entry.handle.close({ reason: 'navigation' });
    entry.promise = cleanup;
    try {
      await cleanup;
    } catch (error) {
      if (this.failedHandleCleanups.get(sessionId) === entry && entry.promise === cleanup) {
        entry.promise = null;
      }
      throw error;
    }
    if (this.failedHandleCleanups.get(sessionId) === entry) {
      this.failedHandleCleanups.delete(sessionId);
      entry.onCleaned?.();
    }
  }

  /**
   * 创建一个新会话。
   *
   * 幂等性: 若 opts.id 已在 storage 命中, 跳过 storage.create 改用现有 meta;
   * 同 id 已有 active Session 或正在创建时直接复用 —— 适配"用户切回老 session
   * 继续聊"以及多个后台入口同时恢复同一会话的场景。
   */
  async createSession(opts: CreateSessionOptions, signal?: AbortSignal): Promise<Session> {
    signal?.throwIfAborted();
    if (this.shutdownStarted) {
      throw new Error('Maker is shutting down; refusing to create a new session');
    }
    const creation = this.createSessionWhileRunning(opts, signal);
    this.pendingSessionCreations.add(creation);
    try {
      return await creation;
    } finally {
      this.pendingSessionCreations.delete(creation);
    }
  }

  /** Keep replacement startup bounded without abandoning native cleanup ownership. */
  private waitForSessionCleanup(cleanup: Promise<unknown>, signal?: AbortSignal): Promise<void> {
    return new Promise<void>((resolve, reject) => {
      let done = false;
      const finish = (failed: boolean, error?: unknown) => {
        if (done) return;
        done = true;
        clearTimeout(timeout);
        signal?.removeEventListener('abort', abort);
        if (failed) reject(error); else resolve();
      };
      const timeout = setTimeout(() => finish(true, new SessionCreationCleanupPendingError()), 1000);
      const abort = () => finish(true, signal?.reason);
      signal?.addEventListener('abort', abort, { once: true });
      if (signal?.aborted) abort();
      // Cleanup rejection still means native ownership is unresolved. Keep it
      // distinct from the caller's abort reason so hosts cannot enter fallback.
      void cleanup.then(() => finish(false), error => finish(true,
        new SessionCreationCleanupPendingError({ cause: error })));
    });
  }

  private async createSessionWhileRunning(opts: CreateSessionOptions, signal?: AbortSignal): Promise<Session> {
    signal?.throwIfAborted();
    if (!opts.id) {
      return this.createSessionOnce(opts, signal);
    }

    // Any handle that failed cleanup before publication still owns this
    // business id. Confirm its shutdown before checking/starting live state.
    if (this.failedHandleCleanups.has(opts.id)) {
      await this.waitForSessionCleanup(this.retryFailedHandleCleanup(opts.id), signal);
      signal?.throwIfAborted();
    }

    // A cancelled creation still owns its native startup until cleanup settles.
    // Never hand that promise to a replacement. Bound this wait so a hung
    // adapter cannot indefinitely hold a new caller; retries retain the barrier.
    const cancelled = this.inFlightSessionCreations.get(opts.id);
    if (cancelled?.signal?.aborted) {
      await this.waitForSessionCleanup(cancelled.promise.then(() => undefined, () => undefined), signal);
      return this.createSessionWhileRunning(opts, signal);
    }

    // 进程内已经活着或正在启动的 session, 直接复用 (避免 spawn 第二个 SDK)。
    // close() 失败的 Session 不能继续收消息,但也不能立刻从 activeSessions
    // 摘掉并与可能仍存活的底层 transport 并存。先重试同一个 close;只有真实
    // 关闭成功、status listener 将其移除后,才允许创建新的 handle。
    const existing = this.activeSessions.get(opts.id);
    if (existing?.hasStartedClosing()) {
      await this.waitForSessionCleanup(existing.close(), signal);
      return this.createSessionWhileRunning(opts, signal);
    }
    if (existing?.getStatus() === 'error') {
      await existing.close();
      signal?.throwIfAborted();
    }
    const reusable = this.activeSessions.get(opts.id);
    if (reusable) return reusable;

    const inFlight = this.inFlightSessionCreations.get(opts.id);
    if (inFlight) return inFlight.promise;

    const creation = { promise: this.createSessionOnce(opts, signal), signal };
    this.inFlightSessionCreations.set(opts.id, creation);
    try {
      return await creation.promise;
    } finally {
      // entry 身份比较防御未来替换 / 重试逻辑误删更新的占位。
      if (this.inFlightSessionCreations.get(opts.id) === creation) {
        this.inFlightSessionCreations.delete(opts.id);
      }
    }
  }

  /** 执行一次真实 session startup;带 id 的并发去重由 createSession 统一负责。 */
  private async createSessionOnce(opts: CreateSessionOptions, signal?: AbortSignal): Promise<Session> {
    signal?.throwIfAborted();
    // Visible application tasks use the ordinary persistence path, but their
    // remote engine need not be installed on this controller either.
    const agent = opts[LOCAL_AGENT_CLIENT] && opts.agentDeviceId
      ? this.agents[opts.agentKind] : this.requireAgent(opts.agentKind);
    const id = opts.id ?? generateSessionId();
    const localPiPackageGeneration = (
      opts.agentKind === 'pi' && !opts.remoteHostId && !opts.agentDeviceId && !opts.reviewMode
    ) ? this.localPiPackageRuntimeGeneration : null;

    this.logger.debug('createSession ↓', {
      localSessionId: id,
      providedId: !!opts.id,
      agentKind: opts.agentKind,
      workingDir: opts.workingDir,
      model: opts.model,
      title: opts.title,
      effort: opts.effort,
      fastMode: opts.fastMode ?? 'default',
      permissionMode: opts.permissionMode,
      displayReasoning: opts.displayReasoning,
      resumeSessionId: opts.resumeSessionId,
      vendorOptionKeys: opts.vendorOptions ? Object.keys(opts.vendorOptions) : undefined,
    });

    const startedAt = Date.now();
    const startOpts: CreateSessionOptions = { ...opts };
    const notifyStartFailed = async (
      stage: SessionStartFailureContext['stage'],
      error: unknown,
      runtimeMayBeAlive = false,
    ): Promise<void> => {
      if (!this.lifecycleHooks.onStartFailed) return;
      try {
        await this.lifecycleHooks.onStartFailed({
          sessionId: id,
          options: startOpts,
          stage,
          error,
          runtimeMayBeAlive,
        });
      } catch (hookError) {
        this.logger.warn('lifecycleHooks.onStartFailed threw; preserving original startup error', {
          sessionId: id,
          stage,
          error: String(hookError),
        });
      }
    };
    const notifyStartCleanupSucceeded = (): void => {
      const cleanup = Promise.resolve()
        .then(() => this.lifecycleHooks.onStartCleanupSucceeded?.(id, startOpts))
        .catch((error) => this.logger.warn('lifecycleHooks.onStartCleanupSucceeded threw', {
          sessionId: id, error: String(error),
        }));
      this.pendingLifecycleCloses.add(cleanup);
      void cleanup.then(() => {
        this.pendingLifecycleCloses.delete(cleanup);
      });
    };
    if (this.lifecycleHooks.prepareStartOptions) {
      try {
        await this.lifecycleHooks.prepareStartOptions(id, startOpts);
        signal?.throwIfAborted();
      } catch (error) {
        await notifyStartFailed('prepare', error);
        throw error;
      }
    }
    if (this.lifecycleHooks.onBeforeStart) {
      try {
        await this.lifecycleHooks.onBeforeStart({
          agentKind: opts.agentKind,
          workingDir: opts.workingDir,
          ...(opts.remoteHostId ? { remoteHostId: opts.remoteHostId } : {}),
        });
      } catch (err) {
        this.logger.warn('lifecycleHooks.onBeforeStart threw; continuing session startup', {
          sessionId: id,
          workingDir: opts.workingDir,
          error: String(err),
        });
      }
    }
    if (
      opts.agentKind === 'codex' &&
      opts.resumeSessionId &&
      startOpts.codexHistoryHasProductPrompt === undefined &&
      this.lifecycleHooks.getCodexHistoryHasProductPrompt
    ) {
      try {
        startOpts.codexHistoryHasProductPrompt =
          await this.lifecycleHooks.getCodexHistoryHasProductPrompt(id);
      } catch (err) {
        this.logger.warn('failed to read codex prompt history state; resume will fail toward restore', {
          sessionId: id,
          error: String(err),
        });
        startOpts.codexHistoryHasProductPrompt = undefined;
      }
    }
    // 把 business sessionId 透传给 agent.startSession, 让 agent 在构造 MCP
    // provider ctx 时塞到 ctx.sessionId 上 (claude-code/index.ts buildMcpServers)。
    // MCP server 工厂据此闭包绑定 "我属于哪个 session", 控制类工具 (如
    // start_team / create_worker) 需要它把回调路由到对应 session 的业务函数。
    // business id 在 close/rebuild 后会复用;另铸一个只活在本次内存实例里的
    // 代号,让迟到的旧 MCP 请求不能借用新 Session 的权限状态。
    const sessionInstanceId = generateSessionId();
    let codexThreadClaim: CodexThreadClaimLease | null = null;
    let handle: AgentSessionHandle;
    let agentStartAttempted = false;
    // Local apps own their native history and require an explicit failed resume,
    // including failures discovered on first send. Visible tasks still use this
    // createSession path; never authorize a fresh conversation/replay for them.
    const onInvalidResumeSession: StartSessionOptions['onInvalidResumeSession'] =
      startOpts[LOCAL_AGENT_CLIENT]
        ? async () => false
        : opts.agentKind === 'claude-code' || opts.agentKind === 'pi'
          ? (expectedSdkSessionId) => this.invalidateAndClearSdkSessionId(id, expectedSdkSessionId)
          : undefined;
    try {
      signal?.throwIfAborted();
      if (opts.agentKind === 'codex' && isClaimableCodexThreadId(startOpts.resumeSessionId)) {
        codexThreadClaim = this.claimCodexThread({
          sessionId: id,
          sessionInstanceId,
          remoteHostId: codexThreadOwnerKey(startOpts),
          threadId: startOpts.resumeSessionId,
        });
      }
      agentStartAttempted = true;
      if (startOpts.fastModePolicy && !(startOpts.fastModePolicy.isRequestAllowed?.() ?? startOpts.fastModePolicy.isAllowed())) startOpts.fastMode = false;
      if (startOpts.agentDeviceId) {
        if (startOpts.remoteHostId) {
          throw new Error('A session cannot run its agent on another computer and on an SSH host at the same time');
        }
        if (!this.startDeviceAgentSession) {
          throw new NotSupportedError('remoteSession', {
            supported: false,
            reason: 'not-implemented',
            message: 'Running the agent on another computer is not available in this host',
          });
        }
        handle = await this.startDeviceAgentSession({
          agentKind: opts.agentKind,
          deviceId: startOpts.agentDeviceId,
          options: {
            ...startOpts,
            sessionId: id,
            sessionInstanceId,
            onInvalidResumeSession,
          },
        });
      } else handle = await (agent ?? this.requireAgent(opts.agentKind)).startSession({
        ...startOpts,
        sessionId: id,
        sessionInstanceId,
        // 强制由 Maker 注入持久化 CAS,不能信任外部 CreateSessionOptions 自带回调。
        // Claude adapter 只在精确识别 invalid-resume 时调用;Codex 不消费该字段。
        // 对所有 claude-code 会话装配(不止 resume):全新会话也可能在首个 turn 崩溃前
        // 就把 SDK 回填、已落库的 sdk_session_id 变成幽灵 id(见 claude-code/index.ts
        // 的 fresh-session self-reference 恢复),需要同一把 CAS 才能把它清掉,否则下一次
        // send 会 resume 同一个不存在的会话反复失败。
        onInvalidResumeSession,
      });
      handle = withFastModePolicy(handle, startOpts.fastModePolicy);
    } catch (error) {
      codexThreadClaim?.release();
      // A generic adapter error does not prove its process stopped. Preserve
      // host guards; only pre-adapter failure or explicit exit evidence releases them.
      const runtimeStopped = error instanceof AgentStartupStoppedError;
      const authenticationFailed = error instanceof AgentNotAuthenticatedError;
      const startupError = runtimeStopped ? error.cause : error;
      await notifyStartFailed(
        'agent-start',
        startupError,
        agentStartAttempted && !runtimeStopped && !authenticationFailed,
      );
      if (error instanceof AgentStartupCleanupPendingError) {
        // The adapter still owns this unpublished process. Its eventual close
        // must release only this startup's resources, even after a rebuild.
        void error.whenStopped.then(notifyStartCleanupSucceeded).catch((cleanupError) => {
          this.logger.warn('adapter startup cleanup remains unconfirmed', {
            sessionId: id, error: String(cleanupError),
          });
        });
      }
      throw startupError;
    }
    const rejectCancelledStartup = async (): Promise<never> => {
      let cleanupFailed = false;
      try {
        await handle.close({ reason: 'navigation' });
      } catch (closeError) {
        cleanupFailed = true;
        this.failedHandleCleanups.set(id, {
          handle, promise: null,
          onCleaned: () => { codexThreadClaim?.release(); notifyStartCleanupSucceeded(); },
        });
        this.logger.warn('failed to close cancelled startup', { sessionId: id, error: String(closeError) });
      }
      if (!cleanupFailed) codexThreadClaim?.release();
      // Keep already-assigned native history. This unpublished handle must not
      // run ordinary Session.onClose or release durable task/worktree ownership.
      const error = signal?.reason ?? new Error('Session startup cancelled');
      await notifyStartFailed('agent-start', error, cleanupFailed);
      throw error;
    };
    if (signal?.aborted) return rejectCancelledStartup();
    if (opts.agentKind === 'codex' && isClaimableCodexThreadId(handle.id)) {
      try {
        if (codexThreadClaim) {
          codexThreadClaim.moveTo(handle.id);
        } else {
          codexThreadClaim = this.claimCodexThread({
            sessionId: id,
            sessionInstanceId,
            remoteHostId: codexThreadOwnerKey(startOpts),
            threadId: handle.id,
          });
        }
      } catch (error) {
        let cleanupFailed = false;
        try {
          await handle.close({ reason: 'navigation' });
        } catch (closeError) {
          cleanupFailed = true;
          this.failedHandleCleanups.set(id, {
            handle, promise: null, onCleaned: notifyStartCleanupSucceeded,
          });
          this.logger.warn('failed to close Codex handle after thread claim conflict', {
            sessionId: id,
            error: String(closeError),
          });
        }
        codexThreadClaim?.release();
        await notifyStartFailed('agent-start', error, cleanupFailed);
        throw error;
      }
    }
    this.logger.debug('createSession ↑ agent.startSession returned', {
      localSessionId: id,
      sdkSessionId: handle.id,
      elapsedMs: Date.now() - startedAt,
    });

    // Reject a stale local Pi handle before creating or updating durable task
    // metadata. A startup invalidated by a package mutation was never published
    // and must not leave a ghost task or overwrite an existing sdkSessionId.
    if (
      localPiPackageGeneration !== null
      && localPiPackageGeneration !== this.localPiPackageRuntimeGeneration
    ) {
      let cleanupFailed = false;
      try {
        await handle.close({ reason: 'navigation' });
      } catch (closeError) {
        cleanupFailed = true;
        this.failedHandleCleanups.set(id, {
          handle,
          promise: null,
          onCleaned: notifyStartCleanupSucceeded,
        });
        this.logger.warn('failed to close stale local Pi handle after package mutation', {
          sessionId: id,
          error: String(closeError),
        });
      }
      const error = new Error('Local Pi runtime startup was invalidated by a package change; retry the task.');
      await notifyStartFailed('agent-start', error, cleanupFailed);
      throw error;
    }

    // 落地元数据 —— storage 已有同 id 的 row 时跳过 insert, 走 update 把 sdkSessionId 写回
    let meta: SessionMeta;
    let existingRowBeforePersistence: SessionMeta | null = null;
    let createdMetadata = false;
    let updatedSdkSessionId = false;
    try {
      existingRowBeforePersistence = opts.id ? await this.storage.get(opts.id) : null;
      signal?.throwIfAborted();
      if (existingRowBeforePersistence) {
        updatedSdkSessionId = handle.id !== '<pending>'
          && existingRowBeforePersistence.sdkSessionId !== handle.id;
        meta = updatedSdkSessionId
          ? await this.storage.update(id, { sdkSessionId: handle.id })
          : existingRowBeforePersistence;
      } else {
        meta = await this.storage.create({
          id,
          agentKind: opts.agentKind,
          workDir: opts.workingDir,
          title: opts.title ?? DEFAULT_DRAFT_SESSION_TITLE,
          model: opts.model,
          workspaceKind: opts.workspaceKind,
          effort: opts.effort,
          permissionMode: opts.permissionMode,
          fastMode: opts.fastMode,
          ...(typeof opts.planMode === 'boolean' ? { planMode: opts.planMode } : {}),
          reviewMode: opts.reviewMode,
          parentSessionId: opts.parentSessionId,
          // remoteHostId: 远端 session 把目标机器持久化, 之后 resume / list 都能识别。
          // 本地 session 留 undefined (sqlite 落空), 跟历史行为兼容。
          remoteHostId: opts.remoteHostId,
          ...(opts.agentDeviceId ? { agentDeviceId: opts.agentDeviceId } : {}),
          sdkSessionId: handle.id !== '<pending>' ? handle.id : undefined,
        });
        createdMetadata = true;
      }
    } catch (error) {
      // 轮 40-w4-t5 CRITICAL:agent-agnostic 回滚 —— startSession 成功后 storage
      // 写失败时, 已启动的 agent handle(PI 远端 daemon session / CC / Codex)必须
      // close, 否则 PI 无 codexThreadClaim 时 handle 不关, 远端 pi-manager session/
      // MCP bridge 残留成「用户看不到、Maker 管不到」的半创建状态。
      let cleanupFailed = false;
      try {
        await handle.close({ reason: 'navigation' });
      } catch (closeError) {
        cleanupFailed = true;
        this.failedHandleCleanups.set(id, {
          handle,
          promise: null,
          onCleaned: () => {
            codexThreadClaim?.release();
            notifyStartCleanupSucceeded();
          },
        });
        this.logger.warn('failed to close agent handle after session storage failure', {
          sessionId: id,
          error: String(closeError),
        });
      }
      if (!cleanupFailed && codexThreadClaim) {
        codexThreadClaim.release();
      }
      await notifyStartFailed('storage', error, cleanupFailed);
      throw error;
    }

    if (signal?.aborted) return rejectCancelledStartup();

    const rollbackStaleLocalPiMetadata = async (): Promise<void> => {
      const current = await this.storage.get(id);
      if (createdMetadata) {
        if (current?.createdAt === meta.createdAt && current.sdkSessionId === meta.sdkSessionId) {
          await this.storage.delete(id);
        }
        return;
      }
      if (!updatedSdkSessionId || current?.sdkSessionId !== handle.id) return;
      if (existingRowBeforePersistence?.sdkSessionId) {
        await this.storage.update(id, {
          sdkSessionId: existingRowBeforePersistence.sdkSessionId,
        });
      } else {
        await this.storage.compareAndClearSdkSessionId(id, handle.id);
      }
    };
    const rejectStaleLocalPiAfterPersistence = async (): Promise<never> => {
      try {
        await rollbackStaleLocalPiMetadata();
      } catch (error) {
        this.logger.error('failed to roll back stale local Pi task metadata', {
          sessionId: id,
          error: String(error),
        });
      }
      let cleanupFailed = false;
      try {
        await handle.close({ reason: 'navigation' });
      } catch (closeError) {
        cleanupFailed = true;
        this.failedHandleCleanups.set(id, {
          handle,
          promise: null,
          onCleaned: notifyStartCleanupSucceeded,
        });
        this.logger.warn('failed to close stale local Pi handle after package mutation', {
          sessionId: id,
          error: String(closeError),
        });
      }
      // This handle was never published. Ordinary onClose may release a task's
      // worktree and other durable ownership, so it belongs only to published
      // session closure—not startup rollback.
      const error = new Error('Local Pi runtime startup was invalidated by a package change; retry the task.');
      await notifyStartFailed('storage', error, cleanupFailed);
      throw error;
    };
    if (
      localPiPackageGeneration !== null
      && localPiPackageGeneration !== this.localPiPackageRuntimeGeneration
    ) {
      return rejectStaleLocalPiAfterPersistence();
    }

    const delivery = handle.codexProductPromptDelivery;
    if (
      opts.agentKind === 'codex' &&
      delivery &&
      handle.id !== '<pending>' &&
      handle.id !== '<failed>' &&
      this.lifecycleHooks.onCodexProductPromptDelivery
    ) {
      try {
        await this.lifecycleHooks.onCodexProductPromptDelivery({
          sessionId: id,
          threadId: delivery.threadId,
          historyHasProductPrompt: delivery.historyHasProductPrompt,
        });
      } catch (err) {
        this.logger.warn('failed to persist codex prompt delivery state', {
          sessionId: id,
          threadId: delivery.threadId,
          error: String(err),
        });
      }
    }

    if (signal?.aborted) return rejectCancelledStartup();
    if (this.lifecycleHooks.onStartSucceeded) {
      try {
        await this.lifecycleHooks.onStartSucceeded(id, startOpts);
      } catch (err) {
        this.logger.warn('lifecycleHooks.onStartSucceeded threw; continuing session publish', {
          sessionId: id,
          error: String(err),
        });
      }
    }

    if (
      localPiPackageGeneration !== null
      && localPiPackageGeneration !== this.localPiPackageRuntimeGeneration
    ) {
      return rejectStaleLocalPiAfterPersistence();
    }

    if (signal?.aborted) return rejectCancelledStartup();
    const session = new Session({
      id: meta.id,
      sessionInstanceId,
      agentKind: meta.agentKind,
      workDir: startOpts.workingDir,
      handle,
      hostStartupPreferences: opts.hostStartupPreferences,
      capabilities: capabilitiesForSession(
        meta.agentKind,
        agent?.capabilities ?? applicationHandleCapabilities(handle),
        meta.remoteHostId,
        meta.agentDeviceId ?? startOpts.agentDeviceId,
        handle,
      ),
      logger: this.logger,
      permissionMode: startOpts.permissionMode,
      // 透传 remoteHostId 让 host 层在 hot path 上能 O(1) 判 local/remote
      // (不用每次 send 回 DB 读 SessionMeta — register.ts checkWorkDirExists 走这条)。
      remoteHostId: meta.remoteHostId ?? null,
      // 取实际决定启动分支的 startOpts:任务记录事后读回的旧值不能把本机启动的会话标成远端。
      agentDeviceId: startOpts.agentDeviceId || null,
      // 层 B:视觉桥钩子(per-session 优先,否则全局默认;缺省不传 = 零干扰)。
      visionBridge: startOpts.visionBridge ?? this.visionBridge,
      toolLoopReviewer: this.toolLoopReviewer,
    });

    // 另一台电脑上的 Claude Code:新编号等这一轮成功结束才落库。失联的回合里,对方可能还没写出
    // 这个编号的对话记录,提前落库会让下次发送 resume 到一个空会话,丢掉全部历史。
    const deferredSdkSessionCommit: DeferredSdkSessionCommit | undefined =
      opts.agentKind === 'claude-code' && startOpts.agentDeviceId ? {} : undefined;

    // 当 SDK 回填 sdkSessionId 时持久化
    session.onEvent((evt) => {
      if (evt.type === 'session_id' && typeof evt.data === 'string' && evt.data) {
        if (opts.agentKind === 'codex' && isClaimableCodexThreadId(evt.data)) {
          try {
            if (codexThreadClaim) {
              codexThreadClaim.moveTo(evt.data);
            } else {
              codexThreadClaim = this.claimCodexThread({
                sessionId: id,
                sessionInstanceId,
                remoteHostId: codexThreadOwnerKey(startOpts),
                threadId: evt.data,
              });
            }
          } catch (error) {
            this.logger.error('Codex thread claim move failed; closing conflicting session', {
              sessionId: id,
              sdkSessionId: evt.data,
              error: String(error),
            });
            void session.close();
            return;
          }
        }
        void this.persistSdkSessionId(meta.id, evt.data, deferredSdkSessionCommit).catch((e) => {
          this.logger.warn('failed to persist sdkSessionId', { error: String(e) });
        });
        return;
      }
      if (!deferredSdkSessionCommit) return;
      if (evt.type === 'done' && !isUnfinishedRemoteTurnEvent(evt)) {
        void this.commitDeferredSdkSessionId(meta.id, deferredSdkSessionCommit).catch((e) => {
          this.logger.warn('failed to commit deferred sdkSessionId', { error: String(e) });
        });
      } else if (evt.type === 'done' || (isTerminalAgentErrorEvent(evt) && isUnfinishedRemoteTurnEvent(evt))) {
        void this.discardDeferredSdkSessionId(meta.id, deferredSdkSessionCommit);
      }
    });

    session.onStatusChange((status) => {
      if (status === 'closed') {
        if (deferredSdkSessionCommit) void this.discardDeferredSdkSessionId(meta.id, deferredSdkSessionCommit);
        codexThreadClaim?.release();
        // 不再持久化运行态: 'closed' 是 SDK 子进程的瞬态, 重启即灭, 无意义存盘。
        this.activeSessions.delete(meta.id);
        this.emit({
          type: 'session:closed',
          sessionId: meta.id,
          session,
          reason: this.closeReasons.get(session) ?? 'unexpected',
        });
        // 注入的副作用钩子 (worktree / temp 文件 / image cache 清理等)。
        // fire-and-forget, 异常只记日志, 不影响其他清理。在 storage update / activeSessions
        // delete / emit 之后调 —— 钩子里的逻辑可能对外发 IPC 或读 maker state, 让 Maker
        // 自己的 invariant 先一致。
        if (this.lifecycleHooks.onClose) {
          const cleanup = Promise.resolve()
            .then(() => this.lifecycleHooks.onClose!(meta.id, startOpts))
            .catch((err) => {
              this.logger.warn('lifecycleHooks.onClose threw', { sessionId: meta.id, error: String(err) });
            });
          this.pendingLifecycleCloses.add(cleanup);
          void cleanup.then(() => {
            this.pendingLifecycleCloses.delete(cleanup);
          });
        }
      }
    });

    this.activeSessions.set(meta.id, session);
    this.emit({ type: 'session:created', session });
    return session;
  }

  /**
   * 将同一 session 的 vendor id 持久化操作排成单通道;单次失败不阻断后续操作。
   */
  private enqueueSdkSessionPersistence<T>(sessionId: string, operation: () => Promise<T>): Promise<T> {
    const previous = this.sdkSessionPersistenceTails.get(sessionId) ?? Promise.resolve();
    const result = previous.then(operation);
    const tail = result.then(
      () => undefined,
      () => undefined,
    );
    this.sdkSessionPersistenceTails.set(sessionId, tail);
    void tail.finally(() => {
      if (this.sdkSessionPersistenceTails.get(sessionId) === tail) {
        this.sdkSessionPersistenceTails.delete(sessionId);
      }
    });
    return result;
  }

  /** 标记旧 vendor id 失效,并在所有已在途回填完成后执行 compare-and-clear。 */
  private invalidateAndClearSdkSessionId(sessionId: string, expectedSdkSessionId: string): Promise<boolean> {
    let invalidIds = this.invalidSdkSessionIds.get(sessionId);
    if (!invalidIds) {
      invalidIds = new Set<string>();
      this.invalidSdkSessionIds.set(sessionId, invalidIds);
    }
    // 先标记再排 CAS:CAS 等待期间新到达的同 id 事件也必须在执行时被丢弃。
    invalidIds.add(expectedSdkSessionId);
    return this.enqueueSdkSessionPersistence(sessionId, () =>
      this.storage.compareAndClearSdkSessionId(sessionId, expectedSdkSessionId),
    );
  }

  /**
   * 串行持久化有效 vendor id,并屏蔽已判失效 query 的晚到事件。
   * 传入 `deferred` 时:库里已有另一个编号,就先只记在 `deferred.pending`,等这一轮成功再提交;
   * 库里还没有编号(首轮)时没有可回退的对象,仍立即落库。
   */
  private persistSdkSessionId(
    sessionId: string,
    sdkSessionId: string,
    deferred?: DeferredSdkSessionCommit,
  ): Promise<void> {
    return this.enqueueSdkSessionPersistence(sessionId, async () => {
      if (this.invalidSdkSessionIds.get(sessionId)?.has(sdkSessionId)) {
        this.logger.debug('ignored stale sdkSessionId event after invalid-resume recovery', {
          sessionId,
          sdkSessionId,
        });
        return;
      }
      if (deferred) {
        const current = (await this.storage.get(sessionId))?.sdkSessionId;
        if (current && current !== sdkSessionId) {
          deferred.pending = sdkSessionId;
          this.logger.debug('deferred sdkSessionId until the remote turn succeeds', {
            sessionId,
            sdkSessionId,
          });
          return;
        }
        deferred.pending = undefined;
      }
      await this.storage.update(sessionId, { sdkSessionId });
    });
  }

  /** 这一轮成功结束:把暂存的新 vendor id 写成持久编号(与 persistSdkSessionId 同一条队列,保序)。 */
  private commitDeferredSdkSessionId(sessionId: string, deferred: DeferredSdkSessionCommit): Promise<void> {
    return this.enqueueSdkSessionPersistence(sessionId, async () => {
      const sdkSessionId = deferred.pending;
      deferred.pending = undefined;
      if (!sdkSessionId) return;
      if (this.invalidSdkSessionIds.get(sessionId)?.has(sdkSessionId)) return;
      await this.storage.update(sessionId, { sdkSessionId });
    });
  }

  /** 这一轮失联结束或会话关闭:丢掉暂存编号,库里保持上一个成功的编号。 */
  private discardDeferredSdkSessionId(sessionId: string, deferred: DeferredSdkSessionCommit): Promise<void> {
    return this.enqueueSdkSessionPersistence(sessionId, async () => {
      if (deferred.pending) {
        this.logger.warn('dropped uncommitted sdkSessionId after the remote turn did not finish', {
          sessionId,
          sdkSessionId: deferred.pending,
        });
      }
      deferred.pending = undefined;
    });
  }

  /** 拿到一个已激活的 session(不发起恢复) */
  getSession(id: string): Session | undefined {
    return this.activeSessions.get(id);
  }

  /** Read a live session's per-runtime Pi capability snapshot without creating or resuming it. */
  getSessionRuntimeCapabilities(id: string): PiRuntimeCapabilityManifest | undefined {
    return this.activeSessions.get(id)?.getRuntimeCapabilities();
  }

  /** Subscribe to a live session's per-runtime Pi catalog without sharing state across sessions. */
  onSessionRuntimeCapabilitiesChange(
    id: string,
    listener: (manifest: PiRuntimeCapabilityManifest | undefined) => void,
  ): () => void {
    return this.activeSessions.get(id)?.onRuntimeCapabilitiesChange(listener) ?? (() => undefined);
  }

  /**
   * 读 session 持久化元数据 (title / agentKind / sdkSessionId / ...).
   * 主要给 IPC 层在 send 前查最新 title 作为日志诊断字段透传用 ——
   * 不走业务路径, 失败 (找不到) 返回 null 由调用方决定怎么降级。
   */
  async getSessionMeta(id: string): Promise<SessionMeta | null> {
    return this.storage.get(id);
  }

  /**
   * 查 session 是否在内存中且 SDK 子进程未关闭。
   * "在跑" 的权威来源 —— 不在 activeSessions Map 或 status==='closed' 都算 false。
   * sidebar / 归档防误伤等场景应走这个判断, 不要碰 DB (DB 的 status 是产品归档语义,
   * 跟运行态无关)。
   */
  isSessionAlive(id: string): boolean {
    const sess = this.activeSessions.get(id);
    return sess !== undefined && sess.getStatus() !== 'closed';
  }

  /**
   * Advance the local managed-package boundary synchronously. Any ordinary
   * local Pi startup that captured an older value will close before publish.
   */
  advanceLocalPiPackageRuntimeGeneration(): void {
    this.localPiPackageRuntimeGeneration += 1;
  }

  /** 列出所有当前激活的 session */
  listActiveSessions(): Session[] {
    return Array.from(this.activeSessions.values());
  }

  /** 列出所有元数据(含已关闭的) */
  async listAllMeta(): Promise<SessionMeta[]> {
    return this.storage.list();
  }

  /** Close only when this exact runtime instance is still current for its business id. */
  async closeSessionIfCurrent(
    session: Session,
    reason: Exclude<MakerSessionCloseReason, 'unexpected'> = 'requested',
    opts?: { afterCurrentTurn?: boolean; failureEvent?: () => AgentEvent },
  ): Promise<'closed' | 'deferred' | void> {
    if (this.activeSessions.get(session.id) !== session) return;
    // Deferred internal retirement is only intent. An explicit closer may
    // take ownership until Session actually starts teardown; after that the
    // cause stays fixed even if exit confirmation fails or another close races.
    const previousReason = this.closeReasons.get(session);
    if (previousReason === undefined || (
      previousReason === 'runtime-refresh' && !opts?.afterCurrentTurn && !session.hasStartedClosing()
    )) this.closeReasons.set(session, reason);
    if (opts?.afterCurrentTurn) return session.closeAfterCurrentTurn(opts);
    await session.close();
    return 'closed';
    // status listener 会自动清理 activeSessions 并 emit
  }

  /** 关闭并移除一个 session */
  async closeSession(
    id: string,
    reason: Exclude<MakerSessionCloseReason, 'unexpected'> = 'requested',
  ): Promise<void> {
    const session = this.activeSessions.get(id);
    if (session) await this.closeSessionIfCurrent(session, reason);
    // 已经不在内存里就 no-op —— 没有持久化的运行态需要更新。
  }

  /**
   * Return the close cause for the exact runtime Session instance.
   *
   * A missing explicit cause means the vendor/Session closed itself. Keep this
   * keyed by instance rather than business session id: a replacement can be
   * created before a late close notification from the old instance arrives.
   */
  getSessionCloseReason(session: Session): MakerSessionCloseReason {
    return this.closeReasons.get(session) ?? 'unexpected';
  }

  /**
   * Maker 进程级 shutdown — app.before-quit / 信号 / 崩溃 hook 调一次。
   *
   * **强制退出语义** (与 normal logout 路径不同): agent.dispose() 和 session.close()
   * 完全并发跑, 不再串行"先 session 再 agent"。
   *
   * 之前的"Layer 1 先于 Layer 2"是为了 codex session.close 的 subscription.release
   * 看到的 host subscribers Map 还在 (语义洁癖)。但 release() 用闭包 + cur === handlers
   * 身份比较做幂等 (host.ts:427-436), 即便 host 已清空 Map 也安全。
   *
   * **关键修复 (Windows lingering process bug)**: 之前串行结构下, Codex SIGTERM 是
   * Layer 2 才发出的 — 如果 Layer 1 任何一个 session.close 卡住 (例如 Claude SDK
   * abort 没让 cli.js 子进程及时退出), lifecycle 6s 超时一到 → app.exit(0) →
   * Codex app-server 子进程在 Windows 上不会随父死 → 残留孤儿, 持有 binary 文件锁。
   * 现在并发跑, agent.dispose 不被任何 session.close 阻塞, SIGTERM 一定先被排进
   * Node event queue, 退出窗口期内可靠送达。
   *
   * 调用方:**只调一次**这个方法就够了。不需要再单独遍历 sessions。
   * 失败一律 swallow + 聚合日志, 不抛 (before-quit 阶段不能阻断退出流程)。
   */
  async shutdown(opts?: { reason?: AgentSessionTeardownReason }): Promise<MakerShutdownReport> {
    this.shutdownStarted = true;
    // Fail closed: a caller that cannot name its boundary is treated as an
    // account boundary, so adapters with detached, credential-holding children
    // (Pi durable Subagents) always stop them rather than letting them run on
    // into the next owner. The two real callers name themselves explicitly
    // (`app-quit` from before-quit, `account-boundary` from logout/switch).
    const teardown: AgentSessionTeardownOptions = { reason: opts?.reason ?? 'account-boundary' };
    const agentEntries = Object.entries(this.agents);
    const errors: Array<{ kind: string; name: string; error: unknown }> = [];
    const sessionFailures: MakerShutdownReport['sessionFailures'] = [];

    // Snapshot current sessions before the creation barrier. Existing local
    // Claude/PI processes must start terminating immediately; a stuck startup
    // must not consume the entire host quit window before their detach begins.
    const initialSessionSnapshot = [...this.activeSessions.values(), ...this.localAgentSessions];
    const initialSessionIdentities = new Set(initialSessionSnapshot);
    const queueSessionDetaches = (
      sessions: readonly Session[],
      phase: 'initial' | 'late',
    ): Array<Promise<void>> => {
      for (const session of sessions) {
        if (!this.closeReasons.has(session)) this.closeReasons.set(session, 'requested');
      }
      return sessions.map((session) =>
        Promise.resolve()
          .then(() => session.detach(teardown))
          .catch((e) => {
            errors.push({ kind: `session-${phase}`, name: session.id, error: e });
            // Reported, not just logged: a detach that threw may have left the
            // agent's process alive, which the caller has to weigh before
            // handing the runtime to someone else.
            sessionFailures.push({ sessionId: session.id, agentKind: session.agentKind, error: e });
          }),
      );
    };

    // Queue agent-level process shutdown and the initial Session snapshot
    // before waiting for session creation. PiAgent.dispose() owns its startup
    // barrier; Session detach owns already-published local agent processes.
    const initialAgentDisposes = agentEntries.map(([kind, agent]) =>
      Promise.resolve()
        .then(() => agent.dispose())
        .catch((e) => {
          errors.push({ kind: 'agent', name: kind, error: e });
        }),
    );
    const initialSessionDetaches = queueSessionDetaches(initialSessionSnapshot, 'initial');

    // createSession registers its promise before yielding. Blocking new calls
    // above makes this a stable barrier: after it settles, every handle started
    // before shutdown is active, closed, or present in failedHandleCleanups.
    const creationSnapshot = Array.from(this.pendingSessionCreations);
    await Promise.allSettled(creationSnapshot);

    const finalAgentDisposes = agentEntries.map(([kind, agent], index) =>
      initialAgentDisposes[index]!
        .then(() => agent.dispose())
        .catch((e) => {
          errors.push({ kind: 'agent-final', name: kind, error: e });
        }),
    );

    // Only sessions published while the creation barrier was settling belong
    // to the late pass. Identity filtering avoids detaching an initial Session
    // twice when it remains in activeSessions until its first detach settles.
    const lateSessionSnapshot = [...this.activeSessions.values(), ...this.localAgentSessions]
      .filter((session) => !initialSessionIdentities.has(session));
    const lateSessionDetaches = queueSessionDetaches(lateSessionSnapshot, 'late');
    const failedHandleCleanupSnapshot = Array.from(this.failedHandleCleanups.entries());

    const failedHandleCloses = failedHandleCleanupSnapshot.map(([sessionId, entry]) =>
      Promise.resolve()
        .then(() => this.retryFailedHandleCleanup(sessionId, entry))
        .catch((e) => {
          errors.push({ kind: 'unpublished-handle', name: sessionId, error: e });
        }),
    );

    await Promise.allSettled([
      ...initialSessionDetaches,
      ...finalAgentDisposes,
      ...failedHandleCloses,
      ...lateSessionDetaches,
    ]);

    // Session close notifications enqueue host-owned cleanup (for example
    // runtime worktree lease release). Keep the quit barrier open until every
    // hook that was queued by a detach has settled.
    while (this.pendingLifecycleCloses.size > 0) {
      await Promise.allSettled(Array.from(this.pendingLifecycleCloses));
    }

    if (errors.length > 0) {
      // Maker 没注入 logger; host 端 stdout 能看到 (before-quit 阶段, 不阻塞流程)
      console.error('[Maker.shutdown] some disposers failed', errors);
    }

    // 最后: maker memory db pool (synchronous close, idempotent)。
    // 放在 await 之后是因为 better-sqlite3 close() 是同步 I/O, 没必要并发;
    // 且 agent / session 不依赖 memory db, 顺序无关。
    try {
      this.makerMemory?.dispose();
    } catch (e) {
      console.error('[Maker.shutdown] makerMemory.dispose failed', e);
    }
    return { sessionFailures };
  }

  /** 获取某 agent 的能力声明(用于 UI 在创建 session 前就能查能力) */
  getCapabilities(agentKind: AgentKind) {
    return this.requireAgent(agentKind).capabilities;
  }

  /** 列出已注册的 agent kind */
  listAvailableAgents(): AgentKind[] {
    return Object.keys(this.agents) as AgentKind[];
  }

  /**
   * Register an optional agent after Maker construction.
   *
   * Hosts may provision optional runtimes asynchronously (for example after a
   * transient network failure during startup). Registration is intentionally
   * additive and idempotent so existing sessions and agent instances remain
   * untouched.
   */
  registerAgent(kind: AgentKind, agent: BaseAgent): boolean {
    if (this.shutdownStarted) return false;
    if (this.agents[kind]) return false;
    this.agents[kind] = agent;
    return true;
  }

  /**
   * 设备托管:同账号另一台电脑上的任务让 Agent 在本机运行。直接用本机的 agent 启动会话,
   * 不建本机 Session 与持久化记录(任务、消息与状态都在对方电脑上);opts.deviceHosted 必填。
   */
  async startHostedAgentSession(kind: AgentKind, opts: StartSessionOptions): Promise<AgentSessionHandle> {
    if (this.shutdownStarted) throw new Error('Maker is shutting down; refusing to start a hosted session');
    if (!opts.deviceHosted) throw new Error('hosted sessions require deviceHosted');
    if (opts.remoteHostId) throw new Error('hosted sessions cannot target an SSH host');
    if (opts.fastModePolicy && !(opts.fastModePolicy.isRequestAllowed?.() ?? opts.fastModePolicy.isAllowed())) opts.fastMode = false;
    return withFastModePolicy(await this.requireAgent(kind).startSession(opts), opts.fastModePolicy);
  }

  /** A local application owns the transcript; supplier execution stays in Maker. */
  async startLocalAgentSession(kind: AgentKind, opts: StartSessionOptions): Promise<Session> {
    if (this.shutdownStarted) throw new Error('Maker is shutting down');
    if (!opts[LOCAL_AGENT_CLIENT] || opts.deviceHosted || opts.remoteHostId) {
      throw new Error('Local application sessions require a Main-process capability');
    }
    const deviceId = opts[LOCAL_AGENT_CLIENT]!.agentDeviceId;
    const agent = deviceId ? undefined : this.requireAgent(kind);
    if (deviceId && !this.startDeviceAgentSession) throw new Error('Remote agent execution is unavailable');
    const creation = (async () => {
      const handle = deviceId
        ? await this.startDeviceAgentSession!({ agentKind: kind, deviceId, options: opts })
        : await agent!.startSession(opts);
      if (this.shutdownStarted) {
        await handle.close({ reason: 'account-boundary' });
        throw new Error('Maker stopped before the local application session started');
      }
      const session = new Session({
        id: opts.sessionId ?? generateSessionId(),
        agentKind: kind,
        workDir: opts.workingDir,
        handle,
        logger: this.logger,
        permissionMode: opts.permissionMode,
        capabilities: deviceId ? applicationHandleCapabilities(handle) : capabilitiesForSession(kind, agent!.capabilities, undefined, undefined, handle),
        toolLoopReviewer: this.toolLoopReviewer,
      });
      this.localAgentSessions.add(session);
      session.onStatusChange(status => {
        if (status === 'closed') this.localAgentSessions.delete(session);
      });
      return session;
    })();
    this.pendingSessionCreations.add(creation);
    try {
      return await creation;
    } finally {
      this.pendingSessionCreations.delete(creation);
    }
  }

  /**
   * Agent 内置 command (palette 'agent-builtin' 类目) —— 同步硬编码白名单。
   * 见 agents/<kind>/commands.ts。
   */
  listAgentCommands(agentKind: AgentKind): AgentBuiltinCommand[] {
    return this.requireAgent(agentKind).listAgentCommands();
  }

  /**
   * Agent 用户/项目目录扫出的 skill (palette 'agent-skill' 类目) —— 异步, 有 IO。
   */
  async listAgentSkills(
    agentKind: AgentKind,
    opts: ListAgentSkillsOptions & { sessionId?: string },
  ): Promise<ListAgentSkillsResult> {
    const { sessionId, ...agentOpts } = opts;
    const sessionMeta = sessionId ? await this.storage.get(sessionId) : null;
    const includeManagedPiPackages = agentKind === 'pi'
      && (!sessionId || (
        sessionMeta?.agentKind === 'pi'
        && sessionMeta.reviewMode !== true
        && !sessionMeta.remoteHostId
      ));
    const agent = this.requireAgent(agentKind);
    const session = sessionId ? this.getSession(sessionId) : undefined;
    const filter = (result: ListAgentSkillsResult) => agent.filterActiveSkillCommands(
      result, agentOpts.remoteHostId ?? sessionMeta?.remoteHostId ?? undefined,
      session?.agentKind === agentKind ? session.getDisabledSkillPaths() : undefined,
    );
    const result = filter(await agent.listAgentSkills({
      ...agentOpts,
      includeManagedPiPackages,
    }));
    if (agentKind !== 'pi' || !sessionId) return result;
    if (
      session?.agentKind !== 'pi'
      || !opts.workingDir
      || canonicalPiRuntimePath(opts.workingDir) !== canonicalPiRuntimePath(session.workDir)
    ) {
      return result;
    }
    return filter(await mergePiRuntimeSkillStatuses(result, session.getRuntimeCapabilities()));
  }

  /** Host-only runtime view used when a capability must match the live engine winner. */
  async listAgentRuntimeSkills(
    agentKind: AgentKind,
    opts: ListRuntimeSkillsOptions & { sessionId?: string },
  ): Promise<ListAgentSkillsResult> {
    const { sessionId, ...agentOpts } = opts;
    const agent = this.requireAgent(agentKind);
    const session = sessionId ? this.getSession(sessionId) : undefined;
    const result = await agent.listRuntimeSkills(agentOpts);
    return agent.filterActiveSkillCommands(
      result,
      agentOpts.remoteHostId ?? session?.remoteHostId ?? undefined,
      session?.agentKind === agentKind ? session.getDisabledSkillPaths() : undefined,
    );
  }

  /** ChatInput `@` palette entries, routed by agent kind. */
  async scanAtResources(
    agentKind: AgentKind,
    opts: ScanAtResourcesOptions,
  ): Promise<ScanAtResourcesResult> {
    return this.requireAgent(agentKind).scanAtResources(opts);
  }

  /**
   * 列出某 agent (或所有 agent) 的本地 customization (skill / command / agent / ...)。
   *
   * 调用方式:
   *  - 指定 agentKind: 单 agent, 直返该 engine 的 result
   *  - 不指定 agentKind: 并行所有已注册 agent, 单个失败不影响其他, 失败合进 errors
   *
   * 不指定时 items 会包含混合 engine 的条目, UI 自己用 item.engine 分组。
   *
   * 设计意图: 给 SkillHub 这类"想看本地全集"的外部消费者一个单一入口,
   * main 进程不再需要知道 Claude 扫 ~/.claude / Codex 走 RPC 等实现细节。
   */
  async listCustomizations(
    opts: ListCustomizationsOptions & { agentKind?: AgentKind },
  ): Promise<ListCustomizationsResult> {
    const { agentKind, ...rest } = opts;
    if (agentKind) {
      return this.requireAgent(agentKind).listCustomizations(rest);
    }
    const kinds = this.listAvailableAgents();
    const results = await Promise.allSettled(
      kinds.map((k) => this.requireAgent(k).listCustomizations(rest)),
    );
    const merged: ListCustomizationsResult = { items: [], errors: [] };
    results.forEach((r, i) => {
      if (r.status === 'fulfilled') {
        merged.items.push(...r.value.items);
        merged.errors.push(...r.value.errors);
      } else {
        merged.errors.push({
          message: `[${kinds[i]}] ${r.reason instanceof Error ? r.reason.message : String(r.reason)}`,
        });
      }
    });
    return merged;
  }

  /**
   * 一次性 LLM 调用 —— 路由到对应 agent 的 oneShot 实现。
   * 用途: 起标题 / 命名 / 总结摘要 / skillReview 等 "纯文本 → 文本" 任务,
   * 不需要 session 生命周期 / 事件流 / 持久化。
   *
   * 各 agent 默认模型 (Claude → haiku-4-5, Codex → gpt-5.4-mini), 鉴权与正常 session 同源。
   * 失败抛 OneShotError (reason: timeout/auth/network/malformed) —— 调用方按 reason
   * 决定 swallow (起标题) 还是上报 (skillReview)。
   */
  async oneShot(agentKind: AgentKind, prompt: string, opts?: OneShotOptions): Promise<string> {
    return this.requireAgent(agentKind).oneShot(prompt, opts);
  }

  /**
   * Fork SDK session — 不依赖 live session, 不查 activeSessions。
   * Claude 走 SDK jsonl 截断;Codex 走 thread/fork + 可选 thread/rollback。
   *
   * 业务编排在 host 一侧: 计算 agent 截断信息 + SQLite 事务。
   */
  async forkSdkSession(agentKind: AgentKind, opts: ForkSdkSessionOptions): Promise<ForkSdkSessionResult> {
    return this.requireAgent(agentKind).forkSdkSession(opts);
  }

  async requiresCodexThreadHostTransfer(
    opts: Parameters<BaseAgent['requiresCodexThreadHostTransfer']>[0],
  ): Promise<boolean> {
    return this.requireAgent('codex').requiresCodexThreadHostTransfer(opts);
  }

  // ── Agent 鉴权 ───────────────────────────────────────────────────────────
  // 透传到 agent.deps.auth, 让 host 的 maker:auth:* IPC 不必直接拿 AuthAdapter,
  // renderer 也不需要写死任何 vendor 名 (统一 maker:auth:get-state(agentKind) 入口)。

  async getAgentAuthState(agentKind: AgentKind) {
    return this.requireAgent(agentKind).getAuthState();
  }

  async triggerAgentLogin(agentKind: AgentKind, opts?: AuthLoginOptions) {
    return this.requireAgent(agentKind).triggerLogin(opts);
  }

  async logoutAgent(agentKind: AgentKind): Promise<void> {
    return this.requireAgent(agentKind).logout();
  }

  /** 刷新指定 agent 的本机运行时模型清单;不支持或结果已过期时返回 false。 */
  async refreshAgentLocalModels(
    agentKind: AgentKind,
    options?: RefreshLocalModelsOptions,
  ): Promise<boolean> {
    return this.requireAgent(agentKind).refreshLocalModels(options);
  }

  /** Read account quota and banked reset credits through the selected agent runtime. */
  async readAgentAccountRateLimits(agentKind: AgentKind, providerId?: string) {
    return this.requireAgent(agentKind).readAccountRateLimits(providerId);
  }

  /** Consume one banked account reset credit through the selected agent runtime. */
  async consumeAgentAccountRateLimitResetCredit(
    agentKind: AgentKind,
    params: ConsumeAccountRateLimitResetCreditParams,
    providerId?: string,
  ) {
    return this.requireAgent(agentKind).consumeAccountRateLimitResetCredit(params, providerId);
  }

  /** Codex 浏览器登录中途取消; Claude 之类同步弹窗式登录调到底层 no-op。 */
  cancelAgentLogin(agentKind: AgentKind): void {
    this.requireAgent(agentKind).cancelLogin();
  }

  // ── Memory 控制 (跨 agent 统一入口) ──────────────────────────────────────
  // BaseAgent 的 getMemoryStatus / setMemory / resetMemory 是 protected? 不,
  // 是 public 抽象 (基类默认 throw NotSupported, 子类按需实现)。这里包成 public
  // wrapper 让 host (xdt-maker IPC) 通过 (agentKind) 选 agent, 跟 getAgentAuthState
  // / triggerAgentLogin 同模式 — host 不需要直接持 BaseAgent 引用。

  async getAgentMemoryStatus(agentKind: AgentKind): Promise<MemoryStatus> {
    return this.requireAgent(agentKind).getMemoryStatus();
  }

  async setAgentMemory(agentKind: AgentKind, enabled: boolean): Promise<MemorySetResult> {
    return this.requireAgent(agentKind).setMemory(enabled);
  }

  async resetAgentMemory(agentKind: AgentKind): Promise<MemoryResetResult> {
    return this.requireAgent(agentKind).resetMemory();
  }

  /**
   * Agent 联合状态查询 (binary 是否就绪 + 是否登录)。
   * 老 codex:binary:status 的功能等价物, 现在跨 agent 统一。
   *
   * binaryReady: 已注册 agent 由其 binaryPath 判定;平台不支持或 provision 尚未完成的
   *              optional runtime 不注册 agent,并在这里明确返回 false。
   * authReady / identity: 走 deps.auth.getState()。
   */
  async getAgentStatus(agentKind: AgentKind): Promise<{
    binaryReady: boolean;
    binaryPath: string | null;
    authReady: boolean;
    identity?: string;
  }> {
    const agent = this.agents[agentKind];
    // Optional runtimes (currently Pi on unsupported/unprepared platforms) are
    // intentionally not registered. Status is the one discovery API that must
    // represent that state instead of throwing and hiding it as an auth error.
    if (!agent) {
      return { binaryReady: false, binaryPath: null, authReady: false };
    }
    const auth = await agent.getAuthState();
    return {
      binaryReady: !!agent.getBinaryPath(),
      binaryPath: agent.getBinaryPath(),
      authReady: auth.authenticated,
      identity: auth.identity,
    };
  }

  // ── 事件 ─────────────────────────────────────────────────────────────────

  on(listener: MakerEventListener): () => void {
    this.listeners.add(listener);
    return () => this.listeners.delete(listener);
  }

  protected emit(event: MakerEvent): void {
    this.listeners.forEach((cb) => {
      try { cb(event); } catch (e) { this.logger.error('maker event listener threw', { error: String(e) }); }
    });
  }

  protected requireAgent(kind: AgentKind): BaseAgent {
    const agent = this.agents[kind];
    if (!agent) {
      throw new Error(`Agent '${kind}' is not registered (available: ${this.listAvailableAgents().join(', ')})`);
    }
    return agent;
  }
}