@kiturone/kapibala 0.0.8 → 0.0.10

package/dist/index.d.cts

@@ -239,6 +239,18 @@ declare class KapibalaError extends Error {
         dispatchOutcome?: 'not_sent' | 'succeeded' | 'failed' | 'unknown';
     });
 }
+declare const SESSION_SAFE_MESSAGES: {
+    readonly SESSION_LOCKED: "会话已被其他持有者占用";
+    readonly SESSION_RECOVERY_IN_PROGRESS: "会话正在恢复";
+    readonly SESSION_LOCK_OWNER_CHANGED: "会话锁持有者已变化";
+    readonly SESSION_NOT_FOUND: "未找到指定会话";
+    readonly SESSION_ID_AMBIGUOUS: "会话前缀不唯一";
+    readonly HISTORY_PAGE_INVALID: "历史页参数无效";
+};
+/** 会话身份与存储锁的稳定分类；不将内部诊断文本当作机器协议。 */
+type SessionErrorCode = keyof typeof SESSION_SAFE_MESSAGES;
+/** 生成固定安全文案的会话错误；内部 message 保留兼容诊断，重试必须由调用者决定。 */
+declare function createSessionError(code: SessionErrorCode, message: string): KapibalaError;
 /** 工具向外部发送前在微任务复核或状态检查中被撤销/拒绝；dispatchOutcome 固定 not_sent。 */
 declare class PreDispatchError extends KapibalaError {
     constructor(message: string, options?: {
@@ -1151,9 +1163,13 @@ declare class SessionManager {
     constructor(options?: SessionManagerOptions);
     /** 默认新建独立空会话，写入头部并持有单写者锁；不读取其它正文。 */
     create(): Promise<ManagedSession>;
-    /** 每页 20 项按正文活动排序；有效 sidecar 只读元数据，不读取完整 JSONL。默认排除已归档会话。 */
+    /**
+     * 按正文活动排序分页；有效 sidecar 只读元数据，不读取完整 JSONL。默认排除已归档会话。
+     * pageSize 由调用方显式给出时必须在 1–100 之间；非法页参数直接失败，不静默修正。
+     */
     list(page?: number, options?: {
         includeArchived?: boolean;
+        pageSize?: number;
     }): Promise<{
         items: SessionMetadata[];
         total: number;
@@ -1889,6 +1905,8 @@ interface ToolMetadata {
 }
 /** 工具执行期由宿主注入的运行环境；信号取消后工具应尽快清理在途资源再返回。 */
 interface ToolContext {
+    /** 父会话实际协调器的内存引用；spawn 必须显式传递，禁止放入模型输入或持久记录。 */
+    readonly leaseCoordinator?: WorkspaceLeaseCoordinator;
     /** 显式工作区物理根路径，经 native realpath 规范化。 */
     workspaceRoot?: string;
     /** 显式命令执行工作目录绝对路径（位于 workspaceRoot 内部）。 */
@@ -2027,8 +2045,6 @@ declare class WorkspaceLeaseCoordinator {
         timeoutMs?: number;
     }): Promise<T>;
 }
-/** 运行时共享写租约协调器单例。 */
-declare const sharedWorkspaceLeaseCoordinator: WorkspaceLeaseCoordinator;
 
 type CompactionReason = 'threshold' | 'manual' | 'overflow';
 /**
@@ -3572,12 +3588,18 @@ declare class SessionInbox {
  */
 
 /** 子代理会话执行器类型；生产环境调用真实的 AgentSession，测试环境可注入 Mock。 */
-type SubagentSessionRunner = (record: AgentTaskRecord, signal: AbortSignal) => Promise<{
+type SubagentSessionRunner = (record: AgentTaskRecord, signal: AbortSignal, context: SubagentRunnerContext) => Promise<{
     summary: string;
     modelId?: string;
 }>;
+/** 子任务仅在内存中接收父协调器；runner 创建子会话时必须注入，不可序列化到任务记录。 */
+interface SubagentRunnerContext {
+    readonly leaseCoordinator: WorkspaceLeaseCoordinator;
+}
 /** 启动子代理时的调用方上下文。 */
 interface SpawnContext {
+    /** 父会话实际持有的协调器；缺失时在受理和持久副作用前拒绝启动。 */
+    readonly leaseCoordinator: WorkspaceLeaseCoordinator;
     /** 根任务标识；若为根会话直接派生，可缺省由 Runtime 自动初始化。 */
     rootTaskId?: string;
     /** 父会话会话 ID。 */
@@ -3613,6 +3635,7 @@ interface AgentRuntimeOptions {
  * 后台子代理任务树调度与状态机协调器。
  */
 declare class AgentRuntime {
+    private readonly runnerContexts;
     private readonly tasks;
     private readonly controllers;
     private readonly timers;
@@ -3807,8 +3830,8 @@ interface PreparedTaskResult {
     skillName?: string;
 }
 
-/** AgentSession 的构造配置；除主任务绑定外均可缺省，缺省行为见各字段。 */
-interface SessionConfig {
+/** 会话的非根选项；扩展配置时与 SessionConfig 的显式根联合组合，不能隐式推导工作区。 */
+interface SessionOptions {
     /** 宿主显式技能配置；缺省不扫描home，项目根需独立信任。 */
     skills?: SkillOptions;
     /** 持久会话身份；有版本化 Store 时须与头部一致，日志实例身份保持独立。 */
@@ -3822,12 +3845,8 @@ interface SessionConfig {
     defaultProvider: ModelProvider;
     /** 消息级落盘通道；支持状态能力的 Store 额外启用持久压缩与交互终态。 */
     store?: MessageStore;
-    /** 文件访问与沙箱隔离的物理根绝对路径，经 native realpath 规范化；缺失时抛出 WORKSPACE_ROOT_REQUIRED。 */
-    workspaceRoot?: string;
     /** 默认命令执行目录绝对路径，必须位于 workspaceRoot 内部；缺省为 workspaceRoot。 */
     executionCwd?: string;
-    /** 工具执行与会话基目录兼容别名；与 workspaceRoot 冲突时失败。 */
-    rootDir?: string;
     systemPrompt?: string;
     maxSteps?: number;
     logger?: (msg: string) => void;
@@ -3848,7 +3867,7 @@ interface SessionConfig {
     onDiagnostic?: (message: string) => void;
     /** 会话持有的沙箱实例；缺省基于 workspaceRoot 自动创建独占实例。 */
     sandbox?: PathSandbox;
-    /** 共享工作区写租约协调器；缺省使用全局共享单例。 */
+    /** 宿主显式共享的写租约协调器；缺省为本会话独占实例，不隐含跨会话互斥。 */
     leaseCoordinator?: WorkspaceLeaseCoordinator;
     /** 父任务或任务树根 ID，用于多智能体任务层级限制与追踪。 */
     rootTaskId?: string;
@@ -3857,6 +3876,14 @@ interface SessionConfig {
     /** 当前子会话对应的 agentId。 */
     agentId?: string;
 }
+/** 显式工作区根至少提供其一；保留 rootDir-only 兼容输入，双字段物理冲突在构造时拒绝。 */
+type SessionConfig = SessionOptions & ({
+    workspaceRoot: string;
+    rootDir?: string;
+} | {
+    workspaceRoot?: never;
+    rootDir: string;
+});
 /** getStats 返回的统计快照；全部字段为独立副本，宿主修改不影响会话内部状态。 */
 interface SessionStats {
     conversationId?: string;
@@ -4091,4 +4118,4 @@ declare class AgentSession {
     private findClosedToolMessages;
 }
 
-export { AbortError, AgentLoop, type AgentLoopOptions, type AgentNotification, type AgentPlugin, AgentRuntime, type AgentRuntimeOptions, AgentSession, type AgentTaskLimits, type AgentTaskOrigin, type AgentTaskRecord, type AgentTaskStatus, AnthropicProvider, type AnthropicProviderOptions, type ApprovalChannel, type ApprovalChoice, type ApprovalRequest, type BranchInfo, type CanonicalMessage, type Capability, type CatalogOptions, type ChatCapabilities, type ChildGrant, type ChildLimits, type CommandResult, type ConflictPolicy, type ContentBlock, type ContextBudget, ContextBudgetError, ContextManager, type ContextManagerOptions, ContextOverflowError, type ContextSnapshot, ContextStorageError, type ContextSummary, type ContextUsage, type ContextWindowValue, CrossProjectSessionCatalog, DEFAULT_CHILD_LIMITS, DEFAULT_CONTEXT_WINDOW_TOKENS, DEFAULT_MAX_STEPS, DEFAULT_MAX_SUBAGENT_DEPTH, DEFAULT_TIMEOUT_MS, type DerivedChildPolicy, type EventLogger, type ExecutorOptions, FatalError, type FileDetails, FileLogSink, type FileLogSinkOptions, type FileObservation, HARD_LIMIT_MAX_SUBAGENT_DEPTH, type HistoryRepair, type HookContext, type HookHandlers, type HookPoint, HookRegistry, type InstructionLoadOptions, type InstructionSnapshot, type InstructionSource, type InteractionBoundary, type InteractionTerminal, JSONLMessageStore, KapibalaError, type ListAgentsFilter, type LogChannel, type LogEvent, type LogField, type LogInput, type LogLevel, type LogSink, MAIN_BRANCH_ID, MAX_ACTIVE_TASKS_PER_RUNTIME, MAX_ACTIVE_TASKS_PER_TREE, MAX_TOTAL_TASKS_PER_TREE, type ManagedSession, type MessageRole, type MessageStore, ModelError, type ModelErrorCategory, type ModelErrorInfo, type ModelErrorOptions, type ModelEvent, type ModelProfile, type ModelProtocol, type ModelProvider, type ModelProviderBinding, type ModelRequest, type ModelRole, type ModelRouter, type NormalizedHistory, OpenAICompatibleProvider, type OpenAIProviderOptions, OpenAIResponsesProvider, type OpenAIResponsesProviderOptions, type ParentPolicySnapshot, PathSandbox, type PermissionAction, type PermissionDecision, PermissionPolicy, type PermissionRequest, type PermissionRule, type PluginCommandContribution, type PluginContext, type PluginContribution, PreDispatchError, type PreparedSkill, type PreparedTaskContext, type PreparedTaskResult, type PrimaryModelRole, type ProjectIdentity, PromptAssembler, type PromptAssemblerOptions, type PromptContentSource, type ProtocolItemMetadata, type ProtocolOrigin, type ProviderStateBlock, ROLE_PRESETS, type RedactedThinkingBlock, type RequestPreparation, type ResolvedContextWindow, type RolePresetDefinition, type RunCommandInput, type RunMetrics, SESSION_SCHEMA_VERSION, SESSION_SCHEMA_VERSION_V1, SESSION_SCHEMA_VERSION_V2, SKILL_LIMITS, SUMMARY_OUTPUT_BUFFER_MULTIPLIER, type SafeRegexMatchResult, type SandboxConfig, type SearchHit, type SearchOptions, type SearchResponse, SessionApprovalCache, SessionBusyError, type SessionCatalogEntry, type SessionConfig, type SessionEvent, type SessionHeader, SessionInbox, SessionLock, SessionManager, type SessionManagerOptions, type SessionMessageSink, type SessionMetadata, type SessionMode, type SessionRecord, type SessionRecordType, type SessionState, type SessionStats, SessionStore, type ShellDetectOptions, type ShellEnvironment, type ShellKind, type ShellPreference, type ShellScope, SimpleModelRouter, type SkillActivation, type SkillCatalog, type SkillContentSource, type SkillContextState, type SkillDefinition, type SkillDiagnostic, type SkillDocument, type SkillMetadata, type SkillOptions, type SkillQuery, type SkillQueryPage, SkillRegistry, type SkillResourceInput, type SkillResourcePage, type SkillRoot, SkillRuntime, type SkillScanResult, type SkillScope, type SpawnAgentParams, type SpawnAgentReceipt, type SpawnContext, type StatefulMessageStore, type StepLogEntry, type StepLogStage, StructuredLogger, SubagentOutbox, type SubagentOutboxOptions, type SubagentRole, type SubagentSessionRunner, type SubagentSourceMetadata, type SummaryCandidate, SummaryService, type SummaryServiceOptions, type TextBlock, type ThinkingBlock, type TokenEstimate, type TokenEstimator, type Tool, type ToolContext, type ToolDecision, type ToolDefinition, ToolError, type ToolExecutionIdentity, type ToolExecutionResult, ToolExecutor, type ToolHardDenial, type ToolInputValidation, type ToolMetadata, ToolNotFound, ToolRegistry, type ToolRegistrySnapshot, type ToolResultBlock, type ToolResultExecution, type ToolUseBlock, TransportError, type TurnMetrics, UnicodeTokenEstimator, type Usage, type WorkspaceContext, WorkspaceLeaseCoordinator, type WorkspaceResolutionInput, type WorkspaceWriteLease, assembleCanonicalToolResults, assertClosedToolTransaction, builtinTools, classifyBashOutput, cleanupCommandResults, commandAuditSummary, compareSkillPaths, computeProjectKey, createAgentTools, createCancelAgentTool, createContextBudget, createDefaultLogSinks, createListAgentsTool, createLogId, createMessageId, createRunCommandTool, createSpawnAgentTool, createWaitAgentTool, defineTool, deriveChildPolicy, describeModelError, detectShell, editFileTool, escapeSkillXml, estimateSkillTokens, executionFingerprint, extractFileDetails, findSkillContent, formatNotificationContent, formatSkillCatalog, getRolePreset, globTool, grepTool, identifyHistory, indexInteractions, inspectSkillContent, intersectSkillTools, isActiveTaskStatus, isGlobalControlRecordType, isPathInside, isSamePath, isSkillName, isTerminalTaskStatus, isTextBlock, isThinkingBlock, isToolResultBlock, isToolUseBlock, isWithinSkillRoot, isWriteOperation, listSkillResources, loadInstructions, normalizeDriveLetter, normalizeHistory, normalizeSkillTools, normalizedProjectRoot, parseSkillDocument, projectSafeFields, readBoundedSkillText, readFileTool, readSkillResource, recoverIncompleteAudit, renderFileDetails, renderSkillReloads, requestFingerprint, resolveContextWindow, resolveSessionProject, resolveWorkspaceContext, safeRegexMatch, sanitizeModelErrorMessage, sanitizeSessionTitle, scanSkillRoot, sharedWorkspaceLeaseCoordinator, skillDigest, skillFailure, skillPathKey, stableJsonStringify, stableSerialize, supportsSessionState, tightenMode, toNativePhysicalPath, toToolDefinition, truncateToolOutput, validateModelBinding, validatePermissionRules, validateSummary, visibleTools, writeFileTool };
+export { AbortError, AgentLoop, type AgentLoopOptions, type AgentNotification, type AgentPlugin, AgentRuntime, type AgentRuntimeOptions, AgentSession, type AgentTaskLimits, type AgentTaskOrigin, type AgentTaskRecord, type AgentTaskStatus, AnthropicProvider, type AnthropicProviderOptions, type ApprovalChannel, type ApprovalChoice, type ApprovalRequest, type BranchInfo, type CanonicalMessage, type Capability, type CatalogOptions, type ChatCapabilities, type ChildGrant, type ChildLimits, type CommandResult, type ConflictPolicy, type ContentBlock, type ContextBudget, ContextBudgetError, ContextManager, type ContextManagerOptions, ContextOverflowError, type ContextSnapshot, ContextStorageError, type ContextSummary, type ContextUsage, type ContextWindowValue, CrossProjectSessionCatalog, DEFAULT_CHILD_LIMITS, DEFAULT_CONTEXT_WINDOW_TOKENS, DEFAULT_MAX_STEPS, DEFAULT_MAX_SUBAGENT_DEPTH, DEFAULT_TIMEOUT_MS, type DerivedChildPolicy, type EventLogger, type ExecutorOptions, FatalError, type FileDetails, FileLogSink, type FileLogSinkOptions, type FileObservation, HARD_LIMIT_MAX_SUBAGENT_DEPTH, type HistoryRepair, type HookContext, type HookHandlers, type HookPoint, HookRegistry, type InstructionLoadOptions, type InstructionSnapshot, type InstructionSource, type InteractionBoundary, type InteractionTerminal, JSONLMessageStore, KapibalaError, type ListAgentsFilter, type LogChannel, type LogEvent, type LogField, type LogInput, type LogLevel, type LogSink, MAIN_BRANCH_ID, MAX_ACTIVE_TASKS_PER_RUNTIME, MAX_ACTIVE_TASKS_PER_TREE, MAX_TOTAL_TASKS_PER_TREE, type ManagedSession, type MessageRole, type MessageStore, ModelError, type ModelErrorCategory, type ModelErrorInfo, type ModelErrorOptions, type ModelEvent, type ModelProfile, type ModelProtocol, type ModelProvider, type ModelProviderBinding, type ModelRequest, type ModelRole, type ModelRouter, type NormalizedHistory, OpenAICompatibleProvider, type OpenAIProviderOptions, OpenAIResponsesProvider, type OpenAIResponsesProviderOptions, type ParentPolicySnapshot, PathSandbox, type PermissionAction, type PermissionDecision, PermissionPolicy, type PermissionRequest, type PermissionRule, type PluginCommandContribution, type PluginContext, type PluginContribution, PreDispatchError, type PreparedSkill, type PreparedTaskContext, type PreparedTaskResult, type PrimaryModelRole, type ProjectIdentity, PromptAssembler, type PromptAssemblerOptions, type PromptContentSource, type ProtocolItemMetadata, type ProtocolOrigin, type ProviderStateBlock, ROLE_PRESETS, type RedactedThinkingBlock, type RequestPreparation, type ResolvedContextWindow, type RolePresetDefinition, type RunCommandInput, type RunMetrics, SESSION_SCHEMA_VERSION, SESSION_SCHEMA_VERSION_V1, SESSION_SCHEMA_VERSION_V2, SKILL_LIMITS, SUMMARY_OUTPUT_BUFFER_MULTIPLIER, type SafeRegexMatchResult, type SandboxConfig, type SearchHit, type SearchOptions, type SearchResponse, SessionApprovalCache, SessionBusyError, type SessionCatalogEntry, type SessionConfig, type SessionErrorCode, type SessionEvent, type SessionHeader, SessionInbox, SessionLock, SessionManager, type SessionManagerOptions, type SessionMessageSink, type SessionMetadata, type SessionMode, type SessionOptions, type SessionRecord, type SessionRecordType, type SessionState, type SessionStats, SessionStore, type ShellDetectOptions, type ShellEnvironment, type ShellKind, type ShellPreference, type ShellScope, SimpleModelRouter, type SkillActivation, type SkillCatalog, type SkillContentSource, type SkillContextState, type SkillDefinition, type SkillDiagnostic, type SkillDocument, type SkillMetadata, type SkillOptions, type SkillQuery, type SkillQueryPage, SkillRegistry, type SkillResourceInput, type SkillResourcePage, type SkillRoot, SkillRuntime, type SkillScanResult, type SkillScope, type SpawnAgentParams, type SpawnAgentReceipt, type SpawnContext, type StatefulMessageStore, type StepLogEntry, type StepLogStage, StructuredLogger, SubagentOutbox, type SubagentOutboxOptions, type SubagentRole, type SubagentRunnerContext, type SubagentSessionRunner, type SubagentSourceMetadata, type SummaryCandidate, SummaryService, type SummaryServiceOptions, type TextBlock, type ThinkingBlock, type TokenEstimate, type TokenEstimator, type Tool, type ToolContext, type ToolDecision, type ToolDefinition, ToolError, type ToolExecutionIdentity, type ToolExecutionResult, ToolExecutor, type ToolHardDenial, type ToolInputValidation, type ToolMetadata, ToolNotFound, ToolRegistry, type ToolRegistrySnapshot, type ToolResultBlock, type ToolResultExecution, type ToolUseBlock, TransportError, type TurnMetrics, UnicodeTokenEstimator, type Usage, type WorkspaceContext, WorkspaceLeaseCoordinator, type WorkspaceResolutionInput, type WorkspaceWriteLease, assembleCanonicalToolResults, assertClosedToolTransaction, builtinTools, classifyBashOutput, cleanupCommandResults, commandAuditSummary, compareSkillPaths, computeProjectKey, createAgentTools, createCancelAgentTool, createContextBudget, createDefaultLogSinks, createListAgentsTool, createLogId, createMessageId, createRunCommandTool, createSessionError, createSpawnAgentTool, createWaitAgentTool, defineTool, deriveChildPolicy, describeModelError, detectShell, editFileTool, escapeSkillXml, estimateSkillTokens, executionFingerprint, extractFileDetails, findSkillContent, formatNotificationContent, formatSkillCatalog, getRolePreset, globTool, grepTool, identifyHistory, indexInteractions, inspectSkillContent, intersectSkillTools, isActiveTaskStatus, isGlobalControlRecordType, isPathInside, isSamePath, isSkillName, isTerminalTaskStatus, isTextBlock, isThinkingBlock, isToolResultBlock, isToolUseBlock, isWithinSkillRoot, isWriteOperation, listSkillResources, loadInstructions, normalizeDriveLetter, normalizeHistory, normalizeSkillTools, normalizedProjectRoot, parseSkillDocument, projectSafeFields, readBoundedSkillText, readFileTool, readSkillResource, recoverIncompleteAudit, renderFileDetails, renderSkillReloads, requestFingerprint, resolveContextWindow, resolveSessionProject, resolveWorkspaceContext, safeRegexMatch, sanitizeModelErrorMessage, sanitizeSessionTitle, scanSkillRoot, skillDigest, skillFailure, skillPathKey, stableJsonStringify, stableSerialize, supportsSessionState, tightenMode, toNativePhysicalPath, toToolDefinition, truncateToolOutput, validateModelBinding, validatePermissionRules, validateSummary, visibleTools, writeFileTool };

package/dist/index.d.ts

@@ -239,6 +239,18 @@ declare class KapibalaError extends Error {
         dispatchOutcome?: 'not_sent' | 'succeeded' | 'failed' | 'unknown';
     });
 }
+declare const SESSION_SAFE_MESSAGES: {
+    readonly SESSION_LOCKED: "会话已被其他持有者占用";
+    readonly SESSION_RECOVERY_IN_PROGRESS: "会话正在恢复";
+    readonly SESSION_LOCK_OWNER_CHANGED: "会话锁持有者已变化";
+    readonly SESSION_NOT_FOUND: "未找到指定会话";
+    readonly SESSION_ID_AMBIGUOUS: "会话前缀不唯一";
+    readonly HISTORY_PAGE_INVALID: "历史页参数无效";
+};
+/** 会话身份与存储锁的稳定分类；不将内部诊断文本当作机器协议。 */
+type SessionErrorCode = keyof typeof SESSION_SAFE_MESSAGES;
+/** 生成固定安全文案的会话错误；内部 message 保留兼容诊断，重试必须由调用者决定。 */
+declare function createSessionError(code: SessionErrorCode, message: string): KapibalaError;
 /** 工具向外部发送前在微任务复核或状态检查中被撤销/拒绝；dispatchOutcome 固定 not_sent。 */
 declare class PreDispatchError extends KapibalaError {
     constructor(message: string, options?: {
@@ -1151,9 +1163,13 @@ declare class SessionManager {
     constructor(options?: SessionManagerOptions);
     /** 默认新建独立空会话，写入头部并持有单写者锁；不读取其它正文。 */
     create(): Promise<ManagedSession>;
-    /** 每页 20 项按正文活动排序；有效 sidecar 只读元数据，不读取完整 JSONL。默认排除已归档会话。 */
+    /**
+     * 按正文活动排序分页；有效 sidecar 只读元数据，不读取完整 JSONL。默认排除已归档会话。
+     * pageSize 由调用方显式给出时必须在 1–100 之间；非法页参数直接失败，不静默修正。
+     */
     list(page?: number, options?: {
         includeArchived?: boolean;
+        pageSize?: number;
     }): Promise<{
         items: SessionMetadata[];
         total: number;
@@ -1889,6 +1905,8 @@ interface ToolMetadata {
 }
 /** 工具执行期由宿主注入的运行环境；信号取消后工具应尽快清理在途资源再返回。 */
 interface ToolContext {
+    /** 父会话实际协调器的内存引用；spawn 必须显式传递，禁止放入模型输入或持久记录。 */
+    readonly leaseCoordinator?: WorkspaceLeaseCoordinator;
     /** 显式工作区物理根路径，经 native realpath 规范化。 */
     workspaceRoot?: string;
     /** 显式命令执行工作目录绝对路径（位于 workspaceRoot 内部）。 */
@@ -2027,8 +2045,6 @@ declare class WorkspaceLeaseCoordinator {
         timeoutMs?: number;
     }): Promise<T>;
 }
-/** 运行时共享写租约协调器单例。 */
-declare const sharedWorkspaceLeaseCoordinator: WorkspaceLeaseCoordinator;
 
 type CompactionReason = 'threshold' | 'manual' | 'overflow';
 /**
@@ -3572,12 +3588,18 @@ declare class SessionInbox {
  */
 
 /** 子代理会话执行器类型；生产环境调用真实的 AgentSession，测试环境可注入 Mock。 */
-type SubagentSessionRunner = (record: AgentTaskRecord, signal: AbortSignal) => Promise<{
+type SubagentSessionRunner = (record: AgentTaskRecord, signal: AbortSignal, context: SubagentRunnerContext) => Promise<{
     summary: string;
     modelId?: string;
 }>;
+/** 子任务仅在内存中接收父协调器；runner 创建子会话时必须注入，不可序列化到任务记录。 */
+interface SubagentRunnerContext {
+    readonly leaseCoordinator: WorkspaceLeaseCoordinator;
+}
 /** 启动子代理时的调用方上下文。 */
 interface SpawnContext {
+    /** 父会话实际持有的协调器；缺失时在受理和持久副作用前拒绝启动。 */
+    readonly leaseCoordinator: WorkspaceLeaseCoordinator;
     /** 根任务标识；若为根会话直接派生，可缺省由 Runtime 自动初始化。 */
     rootTaskId?: string;
     /** 父会话会话 ID。 */
@@ -3613,6 +3635,7 @@ interface AgentRuntimeOptions {
  * 后台子代理任务树调度与状态机协调器。
  */
 declare class AgentRuntime {
+    private readonly runnerContexts;
     private readonly tasks;
     private readonly controllers;
     private readonly timers;
@@ -3807,8 +3830,8 @@ interface PreparedTaskResult {
     skillName?: string;
 }
 
-/** AgentSession 的构造配置；除主任务绑定外均可缺省，缺省行为见各字段。 */
-interface SessionConfig {
+/** 会话的非根选项；扩展配置时与 SessionConfig 的显式根联合组合，不能隐式推导工作区。 */
+interface SessionOptions {
     /** 宿主显式技能配置；缺省不扫描home，项目根需独立信任。 */
     skills?: SkillOptions;
     /** 持久会话身份；有版本化 Store 时须与头部一致，日志实例身份保持独立。 */
@@ -3822,12 +3845,8 @@ interface SessionConfig {
     defaultProvider: ModelProvider;
     /** 消息级落盘通道；支持状态能力的 Store 额外启用持久压缩与交互终态。 */
     store?: MessageStore;
-    /** 文件访问与沙箱隔离的物理根绝对路径，经 native realpath 规范化；缺失时抛出 WORKSPACE_ROOT_REQUIRED。 */
-    workspaceRoot?: string;
     /** 默认命令执行目录绝对路径，必须位于 workspaceRoot 内部；缺省为 workspaceRoot。 */
     executionCwd?: string;
-    /** 工具执行与会话基目录兼容别名；与 workspaceRoot 冲突时失败。 */
-    rootDir?: string;
     systemPrompt?: string;
     maxSteps?: number;
     logger?: (msg: string) => void;
@@ -3848,7 +3867,7 @@ interface SessionConfig {
     onDiagnostic?: (message: string) => void;
     /** 会话持有的沙箱实例；缺省基于 workspaceRoot 自动创建独占实例。 */
     sandbox?: PathSandbox;
-    /** 共享工作区写租约协调器；缺省使用全局共享单例。 */
+    /** 宿主显式共享的写租约协调器；缺省为本会话独占实例，不隐含跨会话互斥。 */
     leaseCoordinator?: WorkspaceLeaseCoordinator;
     /** 父任务或任务树根 ID，用于多智能体任务层级限制与追踪。 */
     rootTaskId?: string;
@@ -3857,6 +3876,14 @@ interface SessionConfig {
     /** 当前子会话对应的 agentId。 */
     agentId?: string;
 }
+/** 显式工作区根至少提供其一；保留 rootDir-only 兼容输入，双字段物理冲突在构造时拒绝。 */
+type SessionConfig = SessionOptions & ({
+    workspaceRoot: string;
+    rootDir?: string;
+} | {
+    workspaceRoot?: never;
+    rootDir: string;
+});
 /** getStats 返回的统计快照；全部字段为独立副本，宿主修改不影响会话内部状态。 */
 interface SessionStats {
     conversationId?: string;
@@ -4091,4 +4118,4 @@ declare class AgentSession {
     private findClosedToolMessages;
 }
 
-export { AbortError, AgentLoop, type AgentLoopOptions, type AgentNotification, type AgentPlugin, AgentRuntime, type AgentRuntimeOptions, AgentSession, type AgentTaskLimits, type AgentTaskOrigin, type AgentTaskRecord, type AgentTaskStatus, AnthropicProvider, type AnthropicProviderOptions, type ApprovalChannel, type ApprovalChoice, type ApprovalRequest, type BranchInfo, type CanonicalMessage, type Capability, type CatalogOptions, type ChatCapabilities, type ChildGrant, type ChildLimits, type CommandResult, type ConflictPolicy, type ContentBlock, type ContextBudget, ContextBudgetError, ContextManager, type ContextManagerOptions, ContextOverflowError, type ContextSnapshot, ContextStorageError, type ContextSummary, type ContextUsage, type ContextWindowValue, CrossProjectSessionCatalog, DEFAULT_CHILD_LIMITS, DEFAULT_CONTEXT_WINDOW_TOKENS, DEFAULT_MAX_STEPS, DEFAULT_MAX_SUBAGENT_DEPTH, DEFAULT_TIMEOUT_MS, type DerivedChildPolicy, type EventLogger, type ExecutorOptions, FatalError, type FileDetails, FileLogSink, type FileLogSinkOptions, type FileObservation, HARD_LIMIT_MAX_SUBAGENT_DEPTH, type HistoryRepair, type HookContext, type HookHandlers, type HookPoint, HookRegistry, type InstructionLoadOptions, type InstructionSnapshot, type InstructionSource, type InteractionBoundary, type InteractionTerminal, JSONLMessageStore, KapibalaError, type ListAgentsFilter, type LogChannel, type LogEvent, type LogField, type LogInput, type LogLevel, type LogSink, MAIN_BRANCH_ID, MAX_ACTIVE_TASKS_PER_RUNTIME, MAX_ACTIVE_TASKS_PER_TREE, MAX_TOTAL_TASKS_PER_TREE, type ManagedSession, type MessageRole, type MessageStore, ModelError, type ModelErrorCategory, type ModelErrorInfo, type ModelErrorOptions, type ModelEvent, type ModelProfile, type ModelProtocol, type ModelProvider, type ModelProviderBinding, type ModelRequest, type ModelRole, type ModelRouter, type NormalizedHistory, OpenAICompatibleProvider, type OpenAIProviderOptions, OpenAIResponsesProvider, type OpenAIResponsesProviderOptions, type ParentPolicySnapshot, PathSandbox, type PermissionAction, type PermissionDecision, PermissionPolicy, type PermissionRequest, type PermissionRule, type PluginCommandContribution, type PluginContext, type PluginContribution, PreDispatchError, type PreparedSkill, type PreparedTaskContext, type PreparedTaskResult, type PrimaryModelRole, type ProjectIdentity, PromptAssembler, type PromptAssemblerOptions, type PromptContentSource, type ProtocolItemMetadata, type ProtocolOrigin, type ProviderStateBlock, ROLE_PRESETS, type RedactedThinkingBlock, type RequestPreparation, type ResolvedContextWindow, type RolePresetDefinition, type RunCommandInput, type RunMetrics, SESSION_SCHEMA_VERSION, SESSION_SCHEMA_VERSION_V1, SESSION_SCHEMA_VERSION_V2, SKILL_LIMITS, SUMMARY_OUTPUT_BUFFER_MULTIPLIER, type SafeRegexMatchResult, type SandboxConfig, type SearchHit, type SearchOptions, type SearchResponse, SessionApprovalCache, SessionBusyError, type SessionCatalogEntry, type SessionConfig, type SessionEvent, type SessionHeader, SessionInbox, SessionLock, SessionManager, type SessionManagerOptions, type SessionMessageSink, type SessionMetadata, type SessionMode, type SessionRecord, type SessionRecordType, type SessionState, type SessionStats, SessionStore, type ShellDetectOptions, type ShellEnvironment, type ShellKind, type ShellPreference, type ShellScope, SimpleModelRouter, type SkillActivation, type SkillCatalog, type SkillContentSource, type SkillContextState, type SkillDefinition, type SkillDiagnostic, type SkillDocument, type SkillMetadata, type SkillOptions, type SkillQuery, type SkillQueryPage, SkillRegistry, type SkillResourceInput, type SkillResourcePage, type SkillRoot, SkillRuntime, type SkillScanResult, type SkillScope, type SpawnAgentParams, type SpawnAgentReceipt, type SpawnContext, type StatefulMessageStore, type StepLogEntry, type StepLogStage, StructuredLogger, SubagentOutbox, type SubagentOutboxOptions, type SubagentRole, type SubagentSessionRunner, type SubagentSourceMetadata, type SummaryCandidate, SummaryService, type SummaryServiceOptions, type TextBlock, type ThinkingBlock, type TokenEstimate, type TokenEstimator, type Tool, type ToolContext, type ToolDecision, type ToolDefinition, ToolError, type ToolExecutionIdentity, type ToolExecutionResult, ToolExecutor, type ToolHardDenial, type ToolInputValidation, type ToolMetadata, ToolNotFound, ToolRegistry, type ToolRegistrySnapshot, type ToolResultBlock, type ToolResultExecution, type ToolUseBlock, TransportError, type TurnMetrics, UnicodeTokenEstimator, type Usage, type WorkspaceContext, WorkspaceLeaseCoordinator, type WorkspaceResolutionInput, type WorkspaceWriteLease, assembleCanonicalToolResults, assertClosedToolTransaction, builtinTools, classifyBashOutput, cleanupCommandResults, commandAuditSummary, compareSkillPaths, computeProjectKey, createAgentTools, createCancelAgentTool, createContextBudget, createDefaultLogSinks, createListAgentsTool, createLogId, createMessageId, createRunCommandTool, createSpawnAgentTool, createWaitAgentTool, defineTool, deriveChildPolicy, describeModelError, detectShell, editFileTool, escapeSkillXml, estimateSkillTokens, executionFingerprint, extractFileDetails, findSkillContent, formatNotificationContent, formatSkillCatalog, getRolePreset, globTool, grepTool, identifyHistory, indexInteractions, inspectSkillContent, intersectSkillTools, isActiveTaskStatus, isGlobalControlRecordType, isPathInside, isSamePath, isSkillName, isTerminalTaskStatus, isTextBlock, isThinkingBlock, isToolResultBlock, isToolUseBlock, isWithinSkillRoot, isWriteOperation, listSkillResources, loadInstructions, normalizeDriveLetter, normalizeHistory, normalizeSkillTools, normalizedProjectRoot, parseSkillDocument, projectSafeFields, readBoundedSkillText, readFileTool, readSkillResource, recoverIncompleteAudit, renderFileDetails, renderSkillReloads, requestFingerprint, resolveContextWindow, resolveSessionProject, resolveWorkspaceContext, safeRegexMatch, sanitizeModelErrorMessage, sanitizeSessionTitle, scanSkillRoot, sharedWorkspaceLeaseCoordinator, skillDigest, skillFailure, skillPathKey, stableJsonStringify, stableSerialize, supportsSessionState, tightenMode, toNativePhysicalPath, toToolDefinition, truncateToolOutput, validateModelBinding, validatePermissionRules, validateSummary, visibleTools, writeFileTool };
+export { AbortError, AgentLoop, type AgentLoopOptions, type AgentNotification, type AgentPlugin, AgentRuntime, type AgentRuntimeOptions, AgentSession, type AgentTaskLimits, type AgentTaskOrigin, type AgentTaskRecord, type AgentTaskStatus, AnthropicProvider, type AnthropicProviderOptions, type ApprovalChannel, type ApprovalChoice, type ApprovalRequest, type BranchInfo, type CanonicalMessage, type Capability, type CatalogOptions, type ChatCapabilities, type ChildGrant, type ChildLimits, type CommandResult, type ConflictPolicy, type ContentBlock, type ContextBudget, ContextBudgetError, ContextManager, type ContextManagerOptions, ContextOverflowError, type ContextSnapshot, ContextStorageError, type ContextSummary, type ContextUsage, type ContextWindowValue, CrossProjectSessionCatalog, DEFAULT_CHILD_LIMITS, DEFAULT_CONTEXT_WINDOW_TOKENS, DEFAULT_MAX_STEPS, DEFAULT_MAX_SUBAGENT_DEPTH, DEFAULT_TIMEOUT_MS, type DerivedChildPolicy, type EventLogger, type ExecutorOptions, FatalError, type FileDetails, FileLogSink, type FileLogSinkOptions, type FileObservation, HARD_LIMIT_MAX_SUBAGENT_DEPTH, type HistoryRepair, type HookContext, type HookHandlers, type HookPoint, HookRegistry, type InstructionLoadOptions, type InstructionSnapshot, type InstructionSource, type InteractionBoundary, type InteractionTerminal, JSONLMessageStore, KapibalaError, type ListAgentsFilter, type LogChannel, type LogEvent, type LogField, type LogInput, type LogLevel, type LogSink, MAIN_BRANCH_ID, MAX_ACTIVE_TASKS_PER_RUNTIME, MAX_ACTIVE_TASKS_PER_TREE, MAX_TOTAL_TASKS_PER_TREE, type ManagedSession, type MessageRole, type MessageStore, ModelError, type ModelErrorCategory, type ModelErrorInfo, type ModelErrorOptions, type ModelEvent, type ModelProfile, type ModelProtocol, type ModelProvider, type ModelProviderBinding, type ModelRequest, type ModelRole, type ModelRouter, type NormalizedHistory, OpenAICompatibleProvider, type OpenAIProviderOptions, OpenAIResponsesProvider, type OpenAIResponsesProviderOptions, type ParentPolicySnapshot, PathSandbox, type PermissionAction, type PermissionDecision, PermissionPolicy, type PermissionRequest, type PermissionRule, type PluginCommandContribution, type PluginContext, type PluginContribution, PreDispatchError, type PreparedSkill, type PreparedTaskContext, type PreparedTaskResult, type PrimaryModelRole, type ProjectIdentity, PromptAssembler, type PromptAssemblerOptions, type PromptContentSource, type ProtocolItemMetadata, type ProtocolOrigin, type ProviderStateBlock, ROLE_PRESETS, type RedactedThinkingBlock, type RequestPreparation, type ResolvedContextWindow, type RolePresetDefinition, type RunCommandInput, type RunMetrics, SESSION_SCHEMA_VERSION, SESSION_SCHEMA_VERSION_V1, SESSION_SCHEMA_VERSION_V2, SKILL_LIMITS, SUMMARY_OUTPUT_BUFFER_MULTIPLIER, type SafeRegexMatchResult, type SandboxConfig, type SearchHit, type SearchOptions, type SearchResponse, SessionApprovalCache, SessionBusyError, type SessionCatalogEntry, type SessionConfig, type SessionErrorCode, type SessionEvent, type SessionHeader, SessionInbox, SessionLock, SessionManager, type SessionManagerOptions, type SessionMessageSink, type SessionMetadata, type SessionMode, type SessionOptions, type SessionRecord, type SessionRecordType, type SessionState, type SessionStats, SessionStore, type ShellDetectOptions, type ShellEnvironment, type ShellKind, type ShellPreference, type ShellScope, SimpleModelRouter, type SkillActivation, type SkillCatalog, type SkillContentSource, type SkillContextState, type SkillDefinition, type SkillDiagnostic, type SkillDocument, type SkillMetadata, type SkillOptions, type SkillQuery, type SkillQueryPage, SkillRegistry, type SkillResourceInput, type SkillResourcePage, type SkillRoot, SkillRuntime, type SkillScanResult, type SkillScope, type SpawnAgentParams, type SpawnAgentReceipt, type SpawnContext, type StatefulMessageStore, type StepLogEntry, type StepLogStage, StructuredLogger, SubagentOutbox, type SubagentOutboxOptions, type SubagentRole, type SubagentRunnerContext, type SubagentSessionRunner, type SubagentSourceMetadata, type SummaryCandidate, SummaryService, type SummaryServiceOptions, type TextBlock, type ThinkingBlock, type TokenEstimate, type TokenEstimator, type Tool, type ToolContext, type ToolDecision, type ToolDefinition, ToolError, type ToolExecutionIdentity, type ToolExecutionResult, ToolExecutor, type ToolHardDenial, type ToolInputValidation, type ToolMetadata, ToolNotFound, ToolRegistry, type ToolRegistrySnapshot, type ToolResultBlock, type ToolResultExecution, type ToolUseBlock, TransportError, type TurnMetrics, UnicodeTokenEstimator, type Usage, type WorkspaceContext, WorkspaceLeaseCoordinator, type WorkspaceResolutionInput, type WorkspaceWriteLease, assembleCanonicalToolResults, assertClosedToolTransaction, builtinTools, classifyBashOutput, cleanupCommandResults, commandAuditSummary, compareSkillPaths, computeProjectKey, createAgentTools, createCancelAgentTool, createContextBudget, createDefaultLogSinks, createListAgentsTool, createLogId, createMessageId, createRunCommandTool, createSessionError, createSpawnAgentTool, createWaitAgentTool, defineTool, deriveChildPolicy, describeModelError, detectShell, editFileTool, escapeSkillXml, estimateSkillTokens, executionFingerprint, extractFileDetails, findSkillContent, formatNotificationContent, formatSkillCatalog, getRolePreset, globTool, grepTool, identifyHistory, indexInteractions, inspectSkillContent, intersectSkillTools, isActiveTaskStatus, isGlobalControlRecordType, isPathInside, isSamePath, isSkillName, isTerminalTaskStatus, isTextBlock, isThinkingBlock, isToolResultBlock, isToolUseBlock, isWithinSkillRoot, isWriteOperation, listSkillResources, loadInstructions, normalizeDriveLetter, normalizeHistory, normalizeSkillTools, normalizedProjectRoot, parseSkillDocument, projectSafeFields, readBoundedSkillText, readFileTool, readSkillResource, recoverIncompleteAudit, renderFileDetails, renderSkillReloads, requestFingerprint, resolveContextWindow, resolveSessionProject, resolveWorkspaceContext, safeRegexMatch, sanitizeModelErrorMessage, sanitizeSessionTitle, scanSkillRoot, skillDigest, skillFailure, skillPathKey, stableJsonStringify, stableSerialize, supportsSessionState, tightenMode, toNativePhysicalPath, toToolDefinition, truncateToolOutput, validateModelBinding, validatePermissionRules, validateSummary, visibleTools, writeFileTool };

package/dist/index.js

@@ -129,6 +129,21 @@ var KapibalaError = class extends Error {
     this.dispatchOutcome = options?.dispatchOutcome;
   }
 };
+var SESSION_SAFE_MESSAGES = {
+  SESSION_LOCKED: "\u4F1A\u8BDD\u5DF2\u88AB\u5176\u4ED6\u6301\u6709\u8005\u5360\u7528",
+  SESSION_RECOVERY_IN_PROGRESS: "\u4F1A\u8BDD\u6B63\u5728\u6062\u590D",
+  SESSION_LOCK_OWNER_CHANGED: "\u4F1A\u8BDD\u9501\u6301\u6709\u8005\u5DF2\u53D8\u5316",
+  SESSION_NOT_FOUND: "\u672A\u627E\u5230\u6307\u5B9A\u4F1A\u8BDD",
+  SESSION_ID_AMBIGUOUS: "\u4F1A\u8BDD\u524D\u7F00\u4E0D\u552F\u4E00",
+  HISTORY_PAGE_INVALID: "\u5386\u53F2\u9875\u53C2\u6570\u65E0\u6548"
+};
+function createSessionError(code, message) {
+  return new KapibalaError(message, {
+    code,
+    safeMessage: SESSION_SAFE_MESSAGES[code],
+    retryPolicy: "after_user_action"
+  });
+}
 var PreDispatchError = class extends KapibalaError {
   constructor(message, options) {
     super(message, {
@@ -1274,19 +1289,23 @@ var SessionLock = class _SessionLock {
       if (error.code !== "EEXIST") throw error;
       const stale = _SessionLock.readOwner(lockPath);
       if (!stale || !_SessionLock.isDead(stale.pid))
-        throw new Error(
+        throw createSessionError(
+          "SESSION_LOCKED",
           `Session locked by a live or unknown owner${stale ? ` (pid=${stale.pid})` : ""}`
         );
       try {
         fs3.mkdirSync(recovery);
       } catch {
-        throw new Error("Session locked: recovery in progress");
+        throw createSessionError(
+          "SESSION_RECOVERY_IN_PROGRESS",
+          "Session locked: recovery in progress"
+        );
       }
       try {
         fs3.writeFileSync(path2.join(recovery, "owner.json"), JSON.stringify(owner), { flag: "wx" });
         const current = _SessionLock.readOwner(lockPath);
         if (current?.nonce !== stale.nonce || current.pid !== stale.pid || !_SessionLock.isDead(current.pid)) {
-          throw new Error("Session locked: owner changed");
+          throw createSessionError("SESSION_LOCK_OWNER_CHANGED", "Session locked: owner changed");
         }
         const quarantine = `${lockPath}.stale-${randomUUID2()}`;
         fs3.renameSync(lockPath, quarantine);
@@ -1306,7 +1325,8 @@ var SessionLock = class _SessionLock {
           }
           if (installError.code === "EEXIST") {
             const winner = _SessionLock.readOwner(lockPath);
-            throw new Error(
+            throw createSessionError(
+              "SESSION_LOCKED",
               `Session locked by a live or unknown owner${winner ? ` (pid=${winner.pid})` : ""}`
             );
           }
@@ -1340,7 +1360,7 @@ var SessionLock = class _SessionLock {
     if (this.released) return;
     const current = _SessionLock.readOwner(this.lockPath);
     if (current?.nonce !== this.owner.nonce || current.pid !== this.owner.pid)
-      throw new Error("Session lock owner changed");
+      throw createSessionError("SESSION_LOCK_OWNER_CHANGED", "Session lock owner changed");
     fs3.unlinkSync(path2.join(this.lockPath, "owner.json"));
     fs3.rmdirSync(this.lockPath);
     this.released = true;
@@ -1371,7 +1391,11 @@ var SessionLock = class _SessionLock {
   /** 无残留或残留进程已死亡时放行；确认存活的回收进行中则明确失败。 */
   static ensureNoLiveRecovery(recovery) {
     _SessionLock.clearAbandonedRecovery(recovery);
-    if (fs3.existsSync(recovery)) throw new Error("Session locked: recovery in progress");
+    if (fs3.existsSync(recovery))
+      throw createSessionError(
+        "SESSION_RECOVERY_IN_PROGRESS",
+        "Session locked: recovery in progress"
+      );
   }
   /** 仅 ESRCH 表示确定死亡；PID 复用或 EPERM 均保持原锁。 */
   static isDead(pid) {
@@ -1598,30 +1622,36 @@ var SessionManager = class {
       throw error;
     }
   }
-  /** 每页 20 项按正文活动排序；有效 sidecar 只读元数据，不读取完整 JSONL。默认排除已归档会话。 */
+  /**
+   * 按正文活动排序分页；有效 sidecar 只读元数据，不读取完整 JSONL。默认排除已归档会话。
+   * pageSize 由调用方显式给出时必须在 1–100 之间；非法页参数直接失败，不静默修正。
+   */
   async list(page = 1, options) {
-    if (!Number.isSafeInteger(page) || page < 1)
-      throw new Error("History page must be a positive integer");
+    const pageSize = options?.pageSize ?? 20;
+    if (!Number.isSafeInteger(page) || page < 1 || !Number.isSafeInteger(pageSize) || pageSize < 1 || pageSize > 100)
+      throw createSessionError("HISTORY_PAGE_INVALID", "History page must be a positive integer");
     const all = await this.allMetadata();
     const filtered = options?.includeArchived ? all : all.filter((m) => !m.archived);
     return {
-      items: filtered.slice((page - 1) * 20, page * 20),
+      items: filtered.slice((page - 1) * pageSize, page * pageSize),
       total: filtered.length,
       page,
-      pages: Math.max(1, Math.ceil(filtered.length / 20))
+      pages: Math.max(1, Math.ceil(filtered.length / pageSize))
     };
   }
   /** 解析完整 ID 或唯一前缀对应的会话文件与 ID。 */
   resolveSession(id) {
-    if (!id || !/^[a-zA-Z0-9-]+$/.test(id)) throw new Error("Session not found");
+    if (!id || !/^[a-zA-Z0-9-]+$/.test(id))
+      throw createSessionError("SESSION_NOT_FOUND", "Session not found");
     const all = fs5.readdirSync(this.directory).filter((name) => /^\d+_[a-zA-Z0-9-]+\.jsonl$/.test(name)).map((fileName) => ({
       fileName,
       conversationId: fileName.slice(fileName.indexOf("_") + 1, -6)
     }));
     const exact = all.find((m) => m.conversationId === id || m.fileName === id);
     const matches = exact ? [exact] : all.filter((m) => m.conversationId.startsWith(id));
-    if (!matches.length) throw new Error(`Session not found: ${id}`);
-    if (matches.length !== 1) throw new Error(`Ambiguous session prefix: ${id}`);
+    if (!matches.length) throw createSessionError("SESSION_NOT_FOUND", `Session not found: ${id}`);
+    if (matches.length !== 1)
+      throw createSessionError("SESSION_ID_AMBIGUOUS", `Ambiguous session prefix: ${id}`);
     return matches[0];
   }
   /**
@@ -1880,13 +1910,18 @@ var SessionManager = class {
       }));
       const exact = all.find((m) => m.conversationId === idOrFileName);
       const matches = exact ? [exact] : all.filter((m) => m.conversationId.startsWith(idOrFileName));
-      if (!matches.length) throw new Error(`Session not found: ${idOrFileName}`);
-      if (matches.length !== 1) throw new Error(`Ambiguous session prefix: ${idOrFileName}`);
+      if (!matches.length)
+        throw createSessionError("SESSION_NOT_FOUND", `Session not found: ${idOrFileName}`);
+      if (matches.length !== 1)
+        throw createSessionError(
+          "SESSION_ID_AMBIGUOUS",
+          `Ambiguous session prefix: ${idOrFileName}`
+        );
       sourceFileName = matches[0].fileName;
     }
     const sourcePath = path4.join(this.directory, sourceFileName);
     if (!fs5.existsSync(sourcePath)) {
-      throw new Error(`Session not found: ${idOrFileName}`);
+      throw createSessionError("SESSION_NOT_FOUND", `Session not found: ${idOrFileName}`);
     }
     const nativeSource = toNativePhysicalPath(sourcePath);
     const beforeStat = fs5.statSync(nativeSource);
@@ -3255,7 +3290,6 @@ var WorkspaceLeaseCoordinator = class {
     }
   }
 };
-var sharedWorkspaceLeaseCoordinator = new WorkspaceLeaseCoordinator();
 
 // src/context/manager.ts
 import { createHash as createHash7 } from "crypto";
@@ -7934,6 +7968,7 @@ var ToolExecutor = class {
         this.signal?.addEventListener("abort", abortFromSession, { once: true });
       }
       const toolCtx = {
+        leaseCoordinator: this.leaseCoordinator,
         workspaceRoot: this.workspaceRoot,
         executionCwd: this.executionCwd,
         sandbox: this.sandbox,
@@ -10656,6 +10691,7 @@ var SessionInbox = class _SessionInbox {
 
 // src/runtime/agent/runtime.ts
 var AgentRuntime = class {
+  runnerContexts = /* @__PURE__ */ new Map();
   tasks = /* @__PURE__ */ new Map();
   controllers = /* @__PURE__ */ new Map();
   timers = /* @__PURE__ */ new Map();
@@ -10739,6 +10775,13 @@ var AgentRuntime = class {
    * - 登记为 preparing 状态并返回 accepted 回执，使父工具事务能立刻闭合。
    */
   async prepareSpawn(context, params) {
+    const coordinator = context.leaseCoordinator;
+    if (!coordinator || typeof coordinator !== "object" || typeof coordinator.isLocked !== "function" || typeof coordinator.getActiveLease !== "function" || typeof coordinator.tryAcquire !== "function" || typeof coordinator.acquire !== "function") {
+      throw new KapibalaError("Spawn requires the parent workspace lease coordinator", {
+        code: "CONFIG_INVALID",
+        safeMessage: "\u5FC5\u987B\u663E\u5F0F\u4F20\u5165\u7236\u4F1A\u8BDD\u5199\u79DF\u7EA6\u534F\u8C03\u5668"
+      });
+    }
     if (this.isClosed) {
       throw new KapibalaError("AgentRuntime is closed", {
         code: "CONFIG_INVALID",
@@ -10881,6 +10924,7 @@ var AgentRuntime = class {
         timeoutMs
       })
     };
+    this.runnerContexts.set(agentId, Object.freeze({ leaseCoordinator: context.leaseCoordinator }));
     this.tasks.set(agentId, taskRecord);
     this.totalActiveCount++;
     this.treeActiveCounts.set(rootTaskId, treeActive + 1);
@@ -10933,6 +10977,7 @@ var AgentRuntime = class {
     const task = this.tasks.get(agentId);
     if (!task) return;
     if (task.status === "preparing") {
+      this.runnerContexts.delete(agentId);
       task.status = "cancelled";
       task.error = "Parent transaction aborted before commit";
       task.finishedAt = Date.now();
@@ -10958,7 +11003,10 @@ var AgentRuntime = class {
     this.timers.set(task.agentId, timer);
     let runError;
     try {
-      const result = await this.runner(task, controller.signal);
+      const context = this.runnerContexts.get(task.agentId);
+      if (!context)
+        throw new KapibalaError("Runner context is unavailable", { code: "CONFIG_INVALID" });
+      const result = await this.runner(task, controller.signal, context);
       if (task.status === "cancelling") {
         task.status = "cancelled";
         return;
@@ -11009,6 +11057,7 @@ var AgentRuntime = class {
       task.error = runError.message;
       await this.cascadeCancelChildren(task.agentId, "Parent task failed");
     } finally {
+      this.runnerContexts.delete(task.agentId);
       this.clearTaskTimer(task.agentId);
       this.controllers.delete(task.agentId);
       if (!isTerminalTaskStatus(task.status)) {
@@ -11084,6 +11133,7 @@ var AgentRuntime = class {
     controller?.abort(new Error(reason));
     await this.cascadeCancelChildren(agentId, reason);
     const inFlight = this.runningPromises.get(agentId);
+    if (!inFlight) this.runnerContexts.delete(agentId);
     if (inFlight) {
       const GRACE_PERIOD_MS = 5e3;
       let timer;
@@ -11192,6 +11242,7 @@ var AgentRuntime = class {
     }
     this.timers.clear();
     this.controllers.clear();
+    this.runnerContexts.clear();
     this.stateListeners.clear();
   }
   /**
@@ -11332,9 +11383,15 @@ function createSpawnAgentTool(runtime) {
       required: ["description", "prompt", "role"]
     },
     async execute(input, ctx) {
+      if (!ctx.leaseCoordinator)
+        throw new KapibalaError("Missing parent lease coordinator", {
+          code: "CONFIG_INVALID",
+          safeMessage: "\u7F3A\u5C11\u7236\u4F1A\u8BDD\u5199\u79DF\u7EA6\u534F\u8C03\u5668"
+        });
       const workspaceRoot = ctx.workspaceRoot ?? ctx.rootDir;
       const executionCwd = ctx.executionCwd ?? workspaceRoot;
       const spawnContext = {
+        leaseCoordinator: ctx.leaseCoordinator,
         rootTaskId: ctx.rootTaskId,
         sessionId: ctx.sessionId ?? "session-default",
         branchId: ctx.branchId ?? "main",
@@ -11697,7 +11754,7 @@ var AgentSession = class {
     this.cwd = resolvedWorkspace.executionCwd;
     this.projectKey = resolvedWorkspace.projectKey;
     this.sandbox = config.sandbox ?? new PathSandbox({ workspaceRoot: this.workspaceRoot });
-    this.leaseCoordinator = config.leaseCoordinator ?? sharedWorkspaceLeaseCoordinator;
+    this.leaseCoordinator = config.leaseCoordinator ?? new WorkspaceLeaseCoordinator();
     this.tools = new ToolRegistry();
     if (config.skills) {
       this.skillRegistry = new SkillRegistry(config.skills);
@@ -13025,6 +13082,7 @@ export {
   createLogId,
   createMessageId,
   createRunCommandTool,
+  createSessionError,
   createSpawnAgentTool,
   createWaitAgentTool,
   defineTool,
@@ -13080,7 +13138,6 @@ export {
   sanitizeModelErrorMessage,
   sanitizeSessionTitle,
   scanSkillRoot,
-  sharedWorkspaceLeaseCoordinator,
   skillDigest,
   skillFailure,
   skillPathKey,