@kiturone/kapibala 0.0.9 → 0.1.0

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, {
@@ -517,15 +532,50 @@ import path from "path";
 
 // src/context/jsonl-lines.ts
 import fs from "fs";
-function* readJsonlLines(file) {
+function assertHistoryReadBudget(bytes, options) {
+  const limit = options.maxReadBytes;
+  if (limit === void 0) return;
+  if (!Number.isSafeInteger(limit) || limit <= 0)
+    throw new KapibalaError("Invalid history read budget", { code: "CONFIG_INVALID" });
+  if (bytes > limit)
+    throw new KapibalaError("History exceeds the configured read budget", {
+      code: "HISTORY_READ_LIMIT",
+      retryPolicy: "after_user_action",
+      safeMessage: "\u5386\u53F2\u6587\u4EF6\u8D85\u8FC7\u8BFB\u53D6\u9884\u7B97\uFF0C\u539F\u6587\u4EF6\u4FDD\u6301\u4E0D\u53D8"
+    });
+}
+function readHistoryBytes(file, options = {}) {
+  const fd = fs.openSync(file, "r");
+  try {
+    assertHistoryReadBudget(fs.fstatSync(fd).size, options);
+    const chunks = [];
+    const buffer = Buffer.allocUnsafe(64 * 1024);
+    let total = 0;
+    while (true) {
+      const length = fs.readSync(fd, buffer, 0, buffer.length, null);
+      if (!length) break;
+      total += length;
+      assertHistoryReadBudget(total, options);
+      chunks.push(Buffer.from(buffer.subarray(0, length)));
+    }
+    return Buffer.concat(chunks, total);
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+function* readJsonlLines(file, options = {}) {
   const fd = fs.openSync(file, "r");
   const buffer = Buffer.allocUnsafe(64 * 1024);
   let pending = Buffer.alloc(0);
   let offset = 0;
+  let total = 0;
   try {
+    assertHistoryReadBudget(fs.fstatSync(fd).size, options);
     while (true) {
       const length = fs.readSync(fd, buffer, 0, buffer.length, null);
       if (!length) break;
+      total += length;
+      assertHistoryReadBudget(total, options);
       pending = Buffer.concat([pending, buffer.subarray(0, length)]);
       let start = 0;
       let end = pending.indexOf(10, start);
@@ -559,7 +609,7 @@ var SESSION_SCHEMA_VERSION_V2 = 2;
 var SESSION_SCHEMA_VERSION = SESSION_SCHEMA_VERSION_V2;
 var MAIN_BRANCH_ID = "main";
 function isGlobalControlRecordType(type) {
-  return type === "header" || type === "branch_created" || type === "branch_selected" || type === "title" || type === "archive_state" || type === "usage" || type === "legacy_import";
+  return type === "header" || type === "branch_created" || type === "branch_selected" || type === "title" || type === "archive_state" || type === "pin_state" || type === "usage" || type === "legacy_import";
 }
 var types = /* @__PURE__ */ new Set([
   "header",
@@ -578,7 +628,8 @@ var types = /* @__PURE__ */ new Set([
   "branch_created",
   "branch_selected",
   "branch_summary",
-  "archive_state"
+  "archive_state",
+  "pin_state"
 ]);
 function supportsSessionState(store) {
   return "appendRecord" in store && typeof store.appendRecord === "function" && "loadState" in store && typeof store.loadState === "function";
@@ -661,6 +712,13 @@ function assertClosedToolTransaction(records, targetRecordId) {
   }
 }
 var SessionStore = class _SessionStore {
+  constructor(filePath, schemaVersion = SESSION_SCHEMA_VERSION_V2, readOptions = {}) {
+    this.readOptions = readOptions;
+    assertHistoryReadBudget(0, readOptions);
+    this.filePath = path.resolve(filePath);
+    this.schemaVersion = schemaVersion;
+  }
+  readOptions;
   filePath;
   queue = Promise.resolve();
   records = [];
@@ -670,10 +728,6 @@ var SessionStore = class _SessionStore {
   schemaVersion = SESSION_SCHEMA_VERSION_V2;
   activeBranchId = "main";
   branchLeaves = /* @__PURE__ */ new Map();
-  constructor(filePath, schemaVersion = SESSION_SCHEMA_VERSION_V2) {
-    this.filePath = path.resolve(filePath);
-    this.schemaVersion = schemaVersion;
-  }
   /** 获取当前会话文件使用的 Schema 版本（1 或 2）。 */
   getSchemaVersion() {
     return this.schemaVersion;
@@ -696,8 +750,8 @@ var SessionStore = class _SessionStore {
     this.onDiagnostic = onDiagnostic;
   }
   /** 以独占创建方式安装新头部（默认生成 Schema v2 格式），已有文件明确失败，绝不覆盖其它会话。 */
-  static async create(filePath, header) {
-    const store = new _SessionStore(filePath, SESSION_SCHEMA_VERSION_V2);
+  static async create(filePath, header, options = {}) {
+    const store = new _SessionStore(filePath, SESSION_SCHEMA_VERSION_V2, { ...options });
     fs2.mkdirSync(path.dirname(store.filePath), { recursive: true });
     const record = store.makeRecord("header", {
       ...header,
@@ -718,8 +772,8 @@ var SessionStore = class _SessionStore {
     return store;
   }
   /** 打开并验证已有会话；尾部残片先保存到隔离文件，中部损坏与未知版本拒绝恢复。 */
-  static async open(filePath) {
-    const store = new _SessionStore(filePath);
+  static async open(filePath, options = {}) {
+    const store = new _SessionStore(filePath, SESSION_SCHEMA_VERSION_V2, { ...options });
     store.records = store.readFile(true);
     store.refreshStamp();
     return store;
@@ -813,6 +867,24 @@ var SessionStore = class _SessionStore {
     }
     return false;
   }
+  /**
+   * 追加会话置顶控制记录。
+   *
+   * 约束：
+   * - 置顶状态记录为全局控制记录（parentId 为 null，不推进分支上下文叶子）；
+   * - payload 结构为 { pinned: boolean }，最后一次写入生效；
+   * - 置顶只影响列表排序，不改变正文活动时间，因此不会让会话挤进「最近」；
+   * - v1 历史会话禁止变更置顶状态。
+   */
+  async setPinnedState(pinned) {
+    if (this.isReadOnly()) {
+      throw new KapibalaError("Cannot modify pin state of legacy v1 session", {
+        code: "LEGACY_SESSION_READ_ONLY",
+        safeMessage: "\u65E0\u6CD5\u53D8\u66F4\u53EA\u8BFB\u5386\u53F2\u4F1A\u8BDD\u7684\u7F6E\u9876\u72B6\u6001"
+      });
+    }
+    return this.appendRecord("pin_state", { pinned });
+  }
   /**
    * 获取当前会话中所有已知分支的元数据与状态列表。
    */
@@ -1104,14 +1176,15 @@ ${summaryText}` }]
   }
   /** 校验每个完整记录，只有最后非空行的 JSON 残片可隔离，语义损坏绝不作为残片吞掉。 */
   readFile(recover) {
-    const iterator = readJsonlLines(this.filePath);
+    const iterator = readJsonlLines(this.filePath, this.readOptions);
     let lastTerminated = true;
     let blankSeen = false;
     const records = [];
     const identities = /* @__PURE__ */ new Set();
     const messages = /* @__PURE__ */ new Set();
-    this.branchLeaves.clear();
-    this.activeBranchId = MAIN_BRANCH_ID;
+    const branchLeaves = /* @__PURE__ */ new Map();
+    let activeBranchId = MAIN_BRANCH_ID;
+    let schemaVersion = this.schemaVersion;
     let detectedSchemaVersion = null;
     let i = -1;
     for (const line of iterator) {
@@ -1126,7 +1199,7 @@ ${summaryText}` }]
       try {
         record = JSON.parse(line.text);
       } catch {
-        if (!recover || this.schemaVersion === SESSION_SCHEMA_VERSION_V1 || !records.length || Array.from(iterator).some((next) => next.text.trim()))
+        if (!recover || schemaVersion === SESSION_SCHEMA_VERSION_V1 || !records.length || Array.from(iterator).some((next) => next.text.trim()))
           throw new Error(`Session corrupt at line ${i + 1}`);
         fs2.writeFileSync(
           `${this.filePath}.corrupt-${createMessageId()}`,
@@ -1150,7 +1223,7 @@ ${summaryText}` }]
           throw new Error("Unsupported session schema version");
         }
         detectedSchemaVersion = record.schemaVersion;
-        this.schemaVersion = detectedSchemaVersion;
+        schemaVersion = detectedSchemaVersion;
       } else if (record.schemaVersion !== detectedSchemaVersion) {
         throw new Error(`Session corrupt schema version mismatch at line ${i + 1}`);
       }
@@ -1167,11 +1240,11 @@ ${summaryText}` }]
       } else if (record.type === "header") {
         throw new Error("Session corrupt: repeated header");
       }
-      if (this.schemaVersion === SESSION_SCHEMA_VERSION_V1) {
+      if (schemaVersion === SESSION_SCHEMA_VERSION_V1) {
         if (record.parentId !== (records.at(-1)?.recordId ?? null)) {
           throw new Error(`Session corrupt parent at line ${i + 1}`);
         }
-        this.branchLeaves.set(MAIN_BRANCH_ID, record.recordId);
+        branchLeaves.set(MAIN_BRANCH_ID, record.recordId);
       } else {
         if (typeof record.seq !== "number" || record.seq !== records.length) {
           throw new Error(`Session corrupt seq at line ${i + 1}`);
@@ -1185,37 +1258,37 @@ ${summaryText}` }]
             throw new Error(`Session corrupt control record parent at line ${i + 1}`);
           }
           if (record.type === "header") {
-            this.branchLeaves.set(MAIN_BRANCH_ID, record.recordId);
-            this.activeBranchId = MAIN_BRANCH_ID;
+            branchLeaves.set(MAIN_BRANCH_ID, record.recordId);
+            activeBranchId = MAIN_BRANCH_ID;
           } else if (record.type === "branch_created") {
             const bId = record.payload.branchId;
             const baseId = record.payload.baseRecordId;
             if (typeof bId !== "string" || !bId) {
               throw new Error(`Session corrupt branch_created branchId at line ${i + 1}`);
             }
-            if (this.branchLeaves.has(bId)) {
+            if (branchLeaves.has(bId)) {
               throw new Error(`Duplicate branch ID: ${bId}`);
             }
             if (typeof baseId !== "string" || !identities.has(baseId)) {
               throw new Error(`Session corrupt branch_created baseRecordId at line ${i + 1}`);
             }
-            this.branchLeaves.set(bId, baseId);
+            branchLeaves.set(bId, baseId);
           } else if (record.type === "branch_selected") {
             const bId = record.payload.branchId;
-            if (typeof bId !== "string" || !this.branchLeaves.has(bId)) {
+            if (typeof bId !== "string" || !branchLeaves.has(bId)) {
               throw new Error(`Selected branch not found: ${bId}`);
             }
-            this.activeBranchId = bId;
+            activeBranchId = bId;
           }
         } else {
           const bId = record.branchId;
-          if (typeof bId !== "string" || !this.branchLeaves.has(bId)) {
+          if (typeof bId !== "string" || !branchLeaves.has(bId)) {
             throw new Error(`Session corrupt branchId at line ${i + 1}`);
           }
           if (typeof record.parentId !== "string" || !identities.has(record.parentId)) {
             throw new Error(`Session corrupt parent at line ${i + 1}`);
           }
-          this.branchLeaves.set(bId, record.recordId);
+          branchLeaves.set(bId, record.recordId);
         }
       }
       identities.add(record.recordId);
@@ -1234,7 +1307,7 @@ ${summaryText}` }]
     if (!records.length) {
       throw new Error("Session corrupt header");
     }
-    if (recover && !lastTerminated && records.length === i + 1 && this.schemaVersion !== SESSION_SCHEMA_VERSION_V1) {
+    if (recover && !lastTerminated && records.length === i + 1 && schemaVersion !== SESSION_SCHEMA_VERSION_V1) {
       const fd = fs2.openSync(this.filePath, "a");
       try {
         fs2.writeFileSync(fd, "\n");
@@ -1243,6 +1316,9 @@ ${summaryText}` }]
         fs2.closeSync(fd);
       }
     }
+    this.branchLeaves = branchLeaves;
+    this.activeBranchId = activeBranchId;
+    this.schemaVersion = schemaVersion;
     return records;
   }
 };
@@ -1274,19 +1350,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 +1386,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 +1421,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 +1452,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) {
@@ -1521,18 +1606,21 @@ function resolveWorkspaceContext(input) {
 function normalizedProjectRoot(root) {
   return process.platform === "win32" ? root.replaceAll("\\", "/").toLowerCase() : root;
 }
-function resolveSessionProject(cwd) {
+function resolveSessionProject(cwd, mode = "git") {
   const realCwd = toNativePhysicalPath(cwd);
   let root = realCwd;
   let gitBranch;
   let gitWorktree = false;
   try {
-    root = toNativePhysicalPath(
+    const gitRoot = toNativePhysicalPath(
       execFileSync("git", ["-C", realCwd, "rev-parse", "--show-toplevel"], {
         encoding: "utf8",
         stdio: ["ignore", "pipe", "ignore"]
       }).trim()
     );
+    if (mode === "git") root = gitRoot;
+    if (normalizedProjectRoot(gitRoot) !== normalizedProjectRoot(root))
+      return { projectRoot: root, cwd: realCwd, projectKey: computeProjectKey(root) };
     gitWorktree = true;
     gitBranch = execFileSync("git", ["-C", realCwd, "symbolic-ref", "--short", "-q", "HEAD"], {
       encoding: "utf8",
@@ -1540,11 +1628,10 @@ function resolveSessionProject(cwd) {
     }).trim() || void 0;
   } catch {
   }
-  const normalized = normalizedProjectRoot(root);
   return {
     projectRoot: root,
     cwd: realCwd,
-    projectKey: createHash4("sha256").update(normalized).digest("hex"),
+    projectKey: computeProjectKey(root),
     gitBranch,
     gitWorktree
   };
@@ -1562,7 +1649,10 @@ var SessionManager = class {
   directory;
   handles = /* @__PURE__ */ new Map();
   diagnostic;
+  readOptions;
   constructor(options = {}) {
+    this.readOptions = { maxReadBytes: options.maxReadBytes };
+    assertHistoryReadBudget(0, this.readOptions);
     const rootCandidate = options.workspaceRoot ?? options.projectRoot ?? options.cwd;
     if (!rootCandidate) {
       throw new KapibalaError("Workspace root is required for SessionManager", {
@@ -1570,7 +1660,7 @@ var SessionManager = class {
         safeMessage: "\u5FC5\u987B\u663E\u5F0F\u6307\u5B9A\u5DE5\u4F5C\u533A\u6839\u8DEF\u5F84\u6216\u9879\u76EE\u76EE\u5F55"
       });
     }
-    this.project = resolveSessionProject(rootCandidate);
+    this.project = resolveSessionProject(rootCandidate, options.projectRootMode);
     this.directory = path4.join(
       options.homeDirectory ?? os.homedir(),
       ".kapibala",
@@ -1586,12 +1676,16 @@ var SessionManager = class {
     const file = path4.join(this.directory, `${Date.now()}_${conversationId}.jsonl`);
     const lock = await SessionLock.acquire(this.lockPath(conversationId));
     try {
-      const store = await SessionStore.create(file, {
-        conversationId,
-        projectRoot: this.project.projectRoot,
-        initialCwd: this.project.cwd,
-        gitBranch: this.project.gitBranch
-      });
+      const store = await SessionStore.create(
+        file,
+        {
+          conversationId,
+          projectRoot: this.project.projectRoot,
+          initialCwd: this.project.cwd,
+          gitBranch: this.project.gitBranch
+        },
+        this.readOptions
+      );
       return await this.attach(store, lock);
     } catch (error) {
       await lock.release();
@@ -1600,89 +1694,146 @@ var SessionManager = class {
   }
   /**
    * 按正文活动排序分页；有效 sidecar 只读元数据，不读取完整 JSONL。默认排除已归档会话。
-   * pageSize 由调用方显式给出时必须在 1–100 之间；非法页参数直接失败，不静默修正。
+   * pageSize 由调用方显式给出时必须在 1–100 之间；filter 在分页前筛选元数据，调用方须自行处理敏感信息。
+   * 置顶项整体前置、组内仍按活动时间排序；排序只作用于本方法的返回值，不影响 continueRecent。
    */
   async list(page = 1, options) {
     const pageSize = options?.pageSize ?? 20;
     if (!Number.isSafeInteger(page) || page < 1 || !Number.isSafeInteger(pageSize) || pageSize < 1 || pageSize > 100)
-      throw new Error("History page must be a positive integer");
+      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);
+    const visible = options?.includeArchived ? all : all.filter((m) => !m.archived);
+    const filtered = options?.filter ? visible.filter(options.filter) : visible;
+    const ordered = [
+      ...filtered.filter((item) => item.pinned),
+      ...filtered.filter((item) => !item.pinned)
+    ];
     return {
-      items: filtered.slice((page - 1) * pageSize, page * pageSize),
-      total: filtered.length,
+      items: ordered.slice((page - 1) * pageSize, page * pageSize),
+      total: ordered.length,
       page,
-      pages: Math.max(1, Math.ceil(filtered.length / pageSize))
+      pages: Math.max(1, Math.ceil(ordered.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];
   }
   /**
-   * 逻辑归档指定会话。
+   * 归档、恢复、重命名与置顶都向正文追加一条全局控制记录，共用同一套前置约束。
    *
    * 约束：
    * - 必须取得会话独占锁；
-   * - 若会话当前正处于活动打开状态，拒绝归档并抛出 SESSION_IN_USE；
-   * - 向会话正文追加 archive_state { archived: true } 并刷新 sidecar 缓存。
+   * - 若会话当前正处于活动打开状态，拒绝并抛出 SESSION_IN_USE（调用方先关闭句柄）；
+   * - v1 只读历史不能变更，明确以 LEGACY_SESSION_READ_ONLY 失败而不是静默忽略；
+   * - 写入后按正文重建 sidecar，状态只以正文记录为准。
    */
-  async archiveSession(id) {
+  async appendControlRecord(id, subject, append) {
     const { fileName, conversationId } = this.resolveSession(id);
     if (this.handles.has(conversationId)) {
-      throw new KapibalaError("Session is currently active or in use, cannot archive", {
+      throw new KapibalaError("Session is currently active or in use", {
         code: "SESSION_IN_USE",
-        safeMessage: "\u4F1A\u8BDD\u6B63\u5728\u4F7F\u7528\u4E2D\uFF0C\u65E0\u6CD5\u5F52\u6863"
+        safeMessage: `\u4F1A\u8BDD\u6B63\u5728\u4F7F\u7528\u4E2D\uFF0C\u65E0\u6CD5${subject}`
       });
     }
     const targetFile = path4.join(this.directory, fileName);
     const lock = await SessionLock.acquire(this.lockPath(conversationId));
     try {
-      const store = await SessionStore.open(targetFile);
+      const store = await SessionStore.open(targetFile, this.readOptions);
       if (store.isReadOnly()) {
-        throw new KapibalaError("Cannot archive legacy v1 session", {
+        throw new KapibalaError("Cannot modify legacy v1 session state", {
           code: "LEGACY_SESSION_READ_ONLY",
-          safeMessage: "\u65E0\u6CD5\u53D8\u66F4\u53EA\u8BFB\u5386\u53F2\u4F1A\u8BDD\u7684\u5F52\u6863\u72B6\u6001"
+          safeMessage: `\u65E0\u6CD5\u53D8\u66F4\u53EA\u8BFB\u5386\u53F2\u4F1A\u8BDD\u7684${subject}\u72B6\u6001`
         });
       }
-      await store.setArchiveState(true);
-      const records = await store.readRecords();
-      const meta = this.buildMetadata(targetFile, records);
-      meta.archived = true;
-      this.writeMetadata(targetFile, meta);
+      await append(store);
+      this.writeMetadata(targetFile, this.buildMetadata(targetFile, await store.readRecords()));
     } finally {
       await lock.release();
     }
   }
   /**
-   * 恢复已逻辑归档的会话。
+   * 逻辑归档指定会话：向正文追加 archive_state { archived: true } 并刷新 sidecar 缓存。
+   */
+  async archiveSession(id) {
+    await this.appendControlRecord(id, "\u5F52\u6863", (store) => store.setArchiveState(true));
+  }
+  /**
+   * 恢复已逻辑归档的会话：追加 archive_state { archived: false }，正文保持不动。
    */
   async restoreSession(id) {
+    await this.appendControlRecord(id, "\u5F52\u6863", (store) => store.setArchiveState(false));
+  }
+  /**
+   * 单独重命名指定会话，不保留句柄：追加 title 记录后立即释放写锁。
+   *
+   * 与 `rename` 的分工：本方法面向「没有打开该会话」的宿主（桌面侧栏、设置页），
+   * 因此不接受活动句柄；已打开的会话由宿主经自己的 Store 追加，避免同进程锁冲突。
+   */
+  async renameSession(id, title) {
+    const value = title.trim();
+    if (!value) throw new Error("Session title cannot be empty");
+    await this.appendControlRecord(
+      id,
+      "\u91CD\u547D\u540D",
+      (store) => store.appendRecord("title", { title: sanitizeSessionTitle(value) })
+    );
+  }
+  /**
+   * 切换会话置顶：追加 pin_state { pinned } 控制记录，只在列表排序时前置。
+   *
+   * 置顶不是「最近活动」，因此不写 run_started、也不改 lastActivityAt；
+   * 关闭置顶后会话回到按活动时间排序的原有位置。
+   */
+  async pinSession(id, pinned) {
+    await this.appendControlRecord(id, "\u7F6E\u9876", (store) => store.setPinnedState(pinned));
+  }
+  /**
+   * 物理删除指定会话的正文与 sidecar 缓存。
+   *
+   * 约束与边界：
+   * - 删除不可逆，本方法不提供回收站或软删除，调用方必须先取得用户确认；
+   * - 本 Manager 已持有句柄的会话拒绝（SESSION_IN_USE），避免删掉正在追加的文件；
+   * - 其它进程持锁时以 SESSION_LOCKED 失败，不抢占他人写入权，也不做「先等一会儿」的重试；
+   * - 只删该会话自己的 `.jsonl` 与 `.meta.json`；桶目录内其它文件（含 `*.tmp-*` 残片）不动；
+   * - 删除前复核首条头部身份与桶归属：文件名匹配但正文身份不符的残留文件删除会放大错误；
+   * - 缓存先删、正文后删：缓存本可重建，若正文删除失败该会话会在下次浏览时自动重建缓存。
+   */
+  async deleteSession(id) {
     const { fileName, conversationId } = this.resolveSession(id);
+    if (this.handles.has(conversationId)) {
+      throw new KapibalaError("Session is currently active or in use, cannot delete", {
+        code: "SESSION_IN_USE",
+        safeMessage: "\u4F1A\u8BDD\u6B63\u5728\u4F7F\u7528\u4E2D\uFF0C\u65E0\u6CD5\u5220\u9664"
+      });
+    }
     const targetFile = path4.join(this.directory, fileName);
     const lock = await SessionLock.acquire(this.lockPath(conversationId));
     try {
-      const store = await SessionStore.open(targetFile);
-      if (store.isReadOnly()) {
-        throw new KapibalaError("Cannot restore legacy v1 session", {
-          code: "LEGACY_SESSION_READ_ONLY",
-          safeMessage: "\u65E0\u6CD5\u53D8\u66F4\u53EA\u8BFB\u5386\u53F2\u4F1A\u8BDD\u7684\u5F52\u6863\u72B6\u6001"
-        });
+      const headerLines = this.readDiscoveryRecords(targetFile);
+      let header;
+      try {
+        header = headerLines.next().value.payload;
+      } finally {
+        headerLines.return(void 0);
       }
-      await store.setArchiveState(false);
-      const records = await store.readRecords();
-      const meta = this.buildMetadata(targetFile, records);
-      meta.archived = false;
-      this.writeMetadata(targetFile, meta);
+      if (header.conversationId !== conversationId || normalizedProjectRoot(header.projectRoot) !== normalizedProjectRoot(this.project.projectRoot))
+        throw new Error("Foreign session identity");
+      const metadata = this.metadataPath(targetFile);
+      if (fs5.existsSync(metadata)) fs5.unlinkSync(metadata);
+      fs5.unlinkSync(targetFile);
+      syncSessionDirectory(this.directory);
     } finally {
       await lock.release();
     }
@@ -1694,6 +1845,11 @@ var SessionManager = class {
       const file = path4.join(this.directory, fileName);
       try {
         let meta = this.readMetadata(file);
+        if (this.readOptions.maxReadBytes !== void 0 && fs5.statSync(file).size > this.readOptions.maxReadBytes) {
+          meta ??= this.readOversizedMetadata(file);
+          all.push({ ...meta, unavailableReason: "HISTORY_READ_LIMIT" });
+          continue;
+        }
         if (!meta) {
           const records = this.readDiscoveryRecords(file);
           meta = this.buildMetadata(file, records);
@@ -1704,7 +1860,17 @@ var SessionManager = class {
           }
         }
         all.push(meta);
-      } catch {
+      } catch (error) {
+        if (error instanceof KapibalaError && error.code === "HISTORY_READ_LIMIT") {
+          try {
+            all.push({
+              ...this.readOversizedMetadata(file),
+              unavailableReason: "HISTORY_READ_LIMIT"
+            });
+            continue;
+          } catch {
+          }
+        }
         this.report(`Cannot discover session: ${fileName}`);
       }
     }
@@ -1754,7 +1920,10 @@ var SessionManager = class {
       }
       if (header.conversationId !== meta.conversationId || normalizedProjectRoot(header.projectRoot) !== normalizedProjectRoot(this.project.projectRoot))
         throw new Error("Foreign session identity");
-      const store = await SessionStore.open(path4.join(this.directory, meta.fileName));
+      const store = await SessionStore.open(
+        path4.join(this.directory, meta.fileName),
+        this.readOptions
+      );
       if ((await store.loadState()).header.conversationId !== meta.conversationId)
         throw new Error("Session identity mismatch");
       await store.load();
@@ -1766,7 +1935,9 @@ var SessionManager = class {
   }
   /** 继续最近有正文的会话；没有历史才新建，显式打开失败绝不回退为空会话。 */
   async continueRecent(options) {
-    const latest = (await this.allMetadata()).find((m) => m.messageCount > 0);
+    const latest = (await this.allMetadata()).find(
+      (m) => m.messageCount > 0 || m.unavailableReason
+    );
     if (latest)
       return this.open(latest.conversationId, {
         autoUpgradeLegacy: options?.autoUpgradeLegacy ?? true
@@ -1774,11 +1945,21 @@ var SessionManager = class {
     this.report("No previous session with content; created a new session");
     return this.create();
   }
-  /** 标题作为独立耐久记录；标题或浏览不改变正文活动排序。 */
+  /**
+   * 重命名已打开或待打开的会话；标题作为独立耐久记录，标题或浏览都不改变正文活动排序。
+   *
+   * 未持有句柄时临时打开并在追加后释放：只改标题不该把会话一直挂在写锁上，
+   * 否则同进程后续的归档、删除与置顶都会被自己占住的锁挡掉。
+   */
   async rename(id, title) {
     if (!title.trim()) throw new Error("Session title cannot be empty");
+    const alreadyOpen = this.handles.has(this.resolveSession(id).conversationId);
     const handle = await this.open(id, { autoUpgradeLegacy: true });
-    await handle.store.appendRecord("title", { title: sanitizeSessionTitle(title) });
+    try {
+      await handle.store.appendRecord("title", { title: sanitizeSessionTitle(title) });
+    } finally {
+      if (!alreadyOpen) await handle.release();
+    }
   }
   /** 等候所有存储队列后释放句柄；宿主必须先结束 AgentSession 的工具/摘要清理。 */
   async close() {
@@ -1798,7 +1979,7 @@ var SessionManager = class {
     for (const source of sources) {
       if (!fs5.existsSync(source)) continue;
       const before = fs5.statSync(source);
-      const bytes = fs5.readFileSync(source);
+      const bytes = readHistoryBytes(source, this.readOptions);
       const identity = createHash4("sha256").update(fs5.realpathSync.native(source)).update("\0").update(bytes).digest("hex");
       const importLock = await SessionLock.acquire(
         path4.join(this.directory, `import-${identity}.lock`)
@@ -1824,19 +2005,23 @@ var SessionManager = class {
         const id = createMessageId();
         const target = path4.join(this.directory, `${Date.now()}_${id}.jsonl`);
         temp = `${target}.tmp-${createMessageId()}`;
-        const store = await SessionStore.create(temp, {
-          conversationId: id,
-          projectRoot: this.project.projectRoot,
-          initialCwd: this.project.cwd,
-          gitBranch: this.project.gitBranch,
-          importIdentity: identity
-        });
+        const store = await SessionStore.create(
+          temp,
+          {
+            conversationId: id,
+            projectRoot: this.project.projectRoot,
+            initialCwd: this.project.cwd,
+            gitBranch: this.project.gitBranch,
+            importIdentity: identity
+          },
+          this.readOptions
+        );
         await store.appendRecord("legacy_import", { source, identity });
         await store.appendRecord("title", { title: "\u65E7\u5386\u53F2\u5BFC\u5165" });
         for (const message of identifyHistory(raw, identity)) await store.append(message);
         await store.load();
         const after = fs5.statSync(source);
-        if (before.size !== after.size || before.mtimeMs !== after.mtimeMs || !fs5.readFileSync(source).equals(bytes)) {
+        if (before.size !== after.size || before.mtimeMs !== after.mtimeMs || !readHistoryBytes(source, this.readOptions).equals(bytes)) {
           this.report("Legacy history is changing; import postponed");
           continue;
         }
@@ -1884,17 +2069,22 @@ 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);
-    const bytes = fs5.readFileSync(nativeSource);
+    const bytes = readHistoryBytes(nativeSource, this.readOptions);
     const upgradeIdentity = createHash4("sha256").update(nativeSource).update("\0").update(bytes).digest("hex");
     const existingMeta = (await this.allMetadata()).find(
       (m) => m.upgradeIdentity === upgradeIdentity
@@ -1913,7 +2103,7 @@ var SessionManager = class {
       if (doubleCheck) {
         return this.open(doubleCheck.conversationId);
       }
-      const sourceStore = await SessionStore.open(nativeSource);
+      const sourceStore = await SessionStore.open(nativeSource, this.readOptions);
       if (sourceStore.getSchemaVersion() !== SESSION_SCHEMA_VERSION_V1) {
         const state = await sourceStore.loadState();
         return this.open(state.header.conversationId);
@@ -1980,7 +2170,7 @@ var SessionManager = class {
         fs5.closeSync(fd);
       }
       const afterStat = fs5.statSync(nativeSource);
-      if (beforeStat.size !== afterStat.size || beforeStat.mtimeMs !== afterStat.mtimeMs || !fs5.readFileSync(nativeSource).equals(bytes)) {
+      if (beforeStat.size !== afterStat.size || beforeStat.mtimeMs !== afterStat.mtimeMs || !readHistoryBytes(nativeSource, this.readOptions).equals(bytes)) {
         throw new Error("Source legacy session changed during upgrade; retry aborted");
       }
       fs5.renameSync(tempPath, targetPath);
@@ -2143,7 +2333,7 @@ var SessionManager = class {
     store.setAppendObserver(
       (record) => {
         const previous = JSON.parse(
-          fs5.readFileSync(this.metadataPath(store.filePath), "utf8")
+          readHistoryBytes(this.metadataPath(store.filePath), this.readOptions).toString("utf8")
         );
         const currentPrev = record.prevRecordId ?? record.parentId;
         if (previous.conversationId !== header.conversationId || currentPrev !== null && currentPrev !== (previous.logRevision ?? previous.revision))
@@ -2188,10 +2378,28 @@ var SessionManager = class {
     this.handles.set(header.conversationId, handle);
     return handle;
   }
+  /** 超限列表只解析有界头部并核对桶身份，不读取正文、不生成可误用的耐久缓存。 */
+  readOversizedMetadata(file) {
+    const fd = fs5.openSync(file, "r");
+    try {
+      const buffer = Buffer.alloc(Math.min(this.readOptions.maxReadBytes, 64 * 1024));
+      const length = fs5.readSync(fd, buffer, 0, buffer.length, 0);
+      const end = buffer.subarray(0, length).indexOf(10);
+      if (end < 0) throw new Error("Session header exceeds discovery budget");
+      const header = JSON.parse(buffer.subarray(0, end).toString("utf8"));
+      if (header.type !== "header" || ![1, 2].includes(header.schemaVersion))
+        throw new Error("Session corrupt header");
+      return { ...this.buildMetadata(file, [header]), title: "\u5386\u53F2\u8D85\u8FC7\u8BFB\u53D6\u9884\u7B97" };
+    } finally {
+      fs5.closeSync(fd);
+    }
+  }
   /** 缓存通过文件名、身份、统计与正文 stat 校验；失败交由正文重建。 */
   readMetadata(file) {
     try {
-      const meta = JSON.parse(fs5.readFileSync(this.metadataPath(file), "utf8"));
+      const meta = JSON.parse(
+        readHistoryBytes(this.metadataPath(file), this.readOptions).toString("utf8")
+      );
       const stat = fs5.statSync(file);
       if ((meta.schemaVersion === 1 || meta.schemaVersion === 2) && meta.fileName === path4.basename(file) && typeof meta.conversationId === "string" && path4.basename(file).endsWith(`_${meta.conversationId}.jsonl`) && normalizedProjectRoot(meta.projectRoot) === normalizedProjectRoot(this.project.projectRoot) && typeof meta.title === "string" && Number.isFinite(meta.createdAt) && Number.isFinite(meta.lastActivityAt) && Number.isSafeInteger(meta.messageCount) && meta.messageCount >= 0 && typeof meta.revision === "string" && meta.size === stat.size && meta.mtimeMs === stat.mtimeMs)
         return meta;
@@ -2201,7 +2409,7 @@ var SessionManager = class {
   }
   /** 浏览仅解析完整记录；严格打开由 SessionStore 验证，浏览不能改写残片。 */
   *readDiscoveryRecords(file) {
-    const iterator = readJsonlLines(file);
+    const iterator = readJsonlLines(file, this.readOptions);
     let first = true;
     let blankSeen = false;
     for (const line of iterator) {
@@ -2256,7 +2464,8 @@ var SessionManager = class {
         contentRevision: first.value.recordId,
         activeBranchId: MAIN_BRANCH_ID,
         activeLeafId: first.value.recordId,
-        archived: false
+        archived: false,
+        pinned: false
       };
       const branchLeaves = /* @__PURE__ */ new Map();
       branchLeaves.set(MAIN_BRANCH_ID, first.value.recordId);
@@ -2309,6 +2518,8 @@ var SessionManager = class {
       if (bId) meta.activeBranchId = bId;
     } else if (record.type === "archive_state") {
       meta.archived = Boolean(record.payload.archived);
+    } else if (record.type === "pin_state") {
+      meta.pinned = Boolean(record.payload.pinned);
     }
     if (branchLeaves && !isGlobalControlRecordType(record.type)) {
       const bId = record.branchId ?? meta.activeBranchId ?? MAIN_BRANCH_ID;
@@ -2815,6 +3026,7 @@ var CrossProjectSessionCatalog = class {
       let title = "\u65B0\u4F1A\u8BDD";
       let activeBranchId = MAIN_BRANCH_ID;
       let archived = false;
+      let pinned = false;
       let lastRecordId = headerRecord.recordId;
       for (const line of iterator) {
         if (!line.text.trim()) continue;
@@ -2835,6 +3047,8 @@ var CrossProjectSessionCatalog = class {
             title = String(rec.payload.title);
           } else if (rec.type === "archive_state") {
             archived = Boolean(rec.payload.archived);
+          } else if (rec.type === "pin_state") {
+            pinned = Boolean(rec.payload.pinned);
           } else if (rec.type === "branch_selected") {
             activeBranchId = String(rec.payload.branchId);
           }
@@ -2853,6 +3067,7 @@ var CrossProjectSessionCatalog = class {
         title,
         activeBranchId,
         archived,
+        pinned,
         size: stat.size,
         mtimeMs: stat.mtimeMs,
         revision: lastRecordId,
@@ -3259,7 +3474,6 @@ var WorkspaceLeaseCoordinator = class {
     }
   }
 };
-var sharedWorkspaceLeaseCoordinator = new WorkspaceLeaseCoordinator();
 
 // src/context/manager.ts
 import { createHash as createHash7 } from "crypto";
@@ -5991,7 +6205,8 @@ function stopProcessTree(child, nativeGroup) {
   try {
     process.kill(-child.pid, "SIGTERM");
     return true;
-  } catch {
+  } catch (error) {
+    if (error.code === "ESRCH") return true;
     try {
       child.kill("SIGTERM");
     } catch {
@@ -6012,7 +6227,8 @@ function forceProcessTree(child, nativeGroup) {
   try {
     process.kill(-child.pid, "SIGKILL");
     return true;
-  } catch {
+  } catch (error) {
+    if (error.code === "ESRCH") return true;
     try {
       child.kill("SIGKILL");
     } catch {
@@ -6033,13 +6249,31 @@ async function confirmProcessTreeStopped(child, terminationSucceeded, nativeGrou
   if (process.platform === "win32") return true;
   const deadline = Date.now() + 1e3;
   while (Date.now() < deadline) {
+    let exists;
     try {
       process.kill(-child.pid, 0);
+      exists = true;
     } catch (error) {
-      if (error.code === "ESRCH") return true;
-      return false;
+      const code = error.code;
+      if (code === "ESRCH") return true;
+      if (code !== "EPERM") return false;
+      exists = true;
+    }
+    if (groupHasLiveProcess(child.pid)) {
+      await new Promise((resolve) => setTimeout(resolve, 50));
+      continue;
     }
-    await new Promise((resolve) => setTimeout(resolve, 50));
+    return true;
+  }
+  return false;
+}
+function groupHasLiveProcess(pgid) {
+  const result = spawnSync2("ps", ["-axo", "pgid=", "stat="], { timeout: 2e3, encoding: "utf8" });
+  if (result.status !== 0 || result.error) return true;
+  for (const row of result.stdout.split("\n")) {
+    const columns = row.trim().split(/\s+/);
+    if (columns.length < 2 || Number(columns[0]) !== pgid) continue;
+    if (!columns[1].startsWith("Z")) return true;
   }
   return false;
 }
@@ -7407,90 +7641,419 @@ var HookRegistry = class {
 };
 
 // src/runtime/executor/index.ts
-import { createHash as createHash12 } from "crypto";
 import path17 from "path";
-var DEFAULT_TOOL_TIMEOUT_MS = 12e4;
-var ToolExecutor = class {
-  hardDenial;
-  onToolResult;
-  tools;
-  hooks;
-  workspaceRoot;
-  executionCwd;
-  sandbox;
-  leaseCoordinator;
-  rootDir;
-  signal;
-  logger;
-  toolTimeoutMs;
-  eventLogger;
-  sessionId;
-  runId;
-  branchId;
-  rootTaskId;
-  depth;
-  agentId;
-  committedActions = [];
-  rollbackActions = [];
-  mode;
-  permissionRules;
-  approvalChannel;
-  approvalCache;
-  policy = new PermissionPolicy();
-  neverFailures = /* @__PURE__ */ new Set();
-  cancellation = new AbortController();
-  constructor(options) {
-    this.hardDenial = options.hardDenial;
-    this.onToolResult = options.onToolResult;
-    this.tools = options.tools;
-    this.hooks = options.hooks;
-    this.workspaceRoot = options.workspaceRoot ?? options.rootDir;
-    this.executionCwd = options.executionCwd ?? options.rootDir;
-    this.sandbox = options.sandbox;
-    this.leaseCoordinator = options.leaseCoordinator;
-    this.rootDir = options.rootDir;
-    this.signal = options.signal ? AbortSignal.any([options.signal, this.cancellation.signal]) : this.cancellation.signal;
-    this.logger = options.logger;
-    this.toolTimeoutMs = options.toolTimeoutMs ?? DEFAULT_TOOL_TIMEOUT_MS;
-    this.eventLogger = options.eventLogger;
-    this.sessionId = options.sessionId;
-    this.runId = options.runId;
-    this.branchId = options.branchId;
-    this.rootTaskId = options.rootTaskId;
-    this.depth = options.depth;
-    this.agentId = options.agentId;
-    this.mode = options.mode ?? "Approval";
-    this.permissionRules = options.permissionRules ?? [];
-    this.approvalChannel = options.approvalChannel;
-    this.approvalCache = options.approvalCache ?? new SessionApprovalCache();
-  }
-  /**
-   * 父工具事务提交成功后调用，按注册顺序执行所有提交动作。
-   * 动作执行成功后逐项清理对应回滚动作，若某项失败保留剩余回滚动作。
-   */
-  async commit() {
-    while (this.committedActions.length > 0) {
-      const action = this.committedActions.shift();
-      await action();
-      this.rollbackActions.shift();
+
+// src/runtime/executor/approval.ts
+import { createHash as createHash12 } from "crypto";
+async function resolveToolApproval(deps) {
+  const {
+    call,
+    finalInput,
+    tool,
+    rootDir,
+    executionCwd,
+    mode,
+    permissionRules,
+    approvalChannel,
+    approvalCache,
+    hardDenial,
+    neverFailures,
+    policy,
+    signal,
+    audit,
+    failure
+  } = deps;
+  let shell = deps.shell;
+  const executionIdentity = deps.executionIdentity;
+  let auditFields = {};
+  for (let attempt = 0; attempt < 2; attempt++) {
+    const request = {
+      toolName: call.name,
+      capabilities: tool.metadata?.permissions ?? [],
+      input: finalInput,
+      rootDir,
+      ...shell ? { shell } : {},
+      ...executionIdentity ? { executionIdentity } : {},
+      // 解释器内建查询与内容已绑定摘要的工作区直引脚本可确认不受外部脚本变更影响，
+      // 允许会话级批准；其余 shell 命令仅允许单次批准。
+      // 非 shell 工具（含深度绑定 executionIdentity 的外部工具）允许会话级批准。
+      sessionAllowed: !shell || /^(?:pwd|get-location)$/i.test(shell.command.trim()) || shell.scriptDigest !== void 0
+    };
+    const repeatKey = createHash12("sha256").update(stableJsonStringify([call.name, finalInput])).digest("hex");
+    if (neverFailures.has(repeatKey)) {
+      try {
+        await audit("tool.decided", { decision: "deny", decisionSource: "repeat_block" });
+        await audit("tool.finished", { status: "blocked", errorCode: "REPEAT_BLOCKED" });
+      } catch {
+        return {
+          result: failure(
+            "Audit unavailable; tool was not started",
+            "AUDIT_UNAVAILABLE",
+            "after_user_action",
+            {
+              version: 1,
+              dispatchOutcome: "not_sent",
+              hostError: { phase: "audit", code: "AUDIT_UNAVAILABLE" }
+            }
+          )
+        };
+      }
+      return {
+        result: failure(
+          "Identical failed tool call cannot be repeated in this run",
+          "REPEAT_BLOCKED"
+        )
+      };
     }
-    this.rollbackActions.length = 0;
-  }
-  /**
-   * 父工具事务提交失败或取消时调用，按逆序执行所有回滚清理动作。
-   */
-  async rollback() {
-    const actions = [...this.rollbackActions].reverse();
-    this.committedActions.length = 0;
-    this.rollbackActions.length = 0;
-    for (const action of actions) {
+    const hardDenied = hardDenial?.(tool, finalInput);
+    const cached = approvalCache.get(request);
+    const decision = policy.decide({
+      hardDenied: hardDenied !== void 0,
+      mode: typeof mode === "function" ? mode() : mode,
+      toolName: call.name,
+      capabilities: request.capabilities,
+      dangerous: tool.metadata?.dangerous,
+      cachedApproval: cached === "allow",
+      cachedDenial: cached === "deny",
+      rules: permissionRules,
+      ...shell ? { shell } : {}
+    });
+    let permitted = decision.decision === "allow";
+    let source = decision.source;
+    let approvalChoice;
+    if (decision.decision === "ask") {
+      let choice = "deny_once";
       try {
-        await action();
+        choice = await approvalChannel?.requestApproval(request, signal) ?? "deny_once";
+      } catch {
+        choice = "cancel";
+      }
+      approvalChoice = choice;
+      if (choice === "allow_session" && request.sessionAllowed) approvalCache.set(request, "allow");
+      if (choice === "deny_session") approvalCache.set(request, "deny");
+      permitted = choice === "allow_once" || choice === "allow_session" && request.sessionAllowed;
+      source = approvalChannel ? "human" : "non_interactive";
+    }
+    auditFields = shell ? {
+      shell: shell.interpreter,
+      cwdDigest: createHash12("sha256").update(shell.cwd).digest("hex"),
+      executableDigest: shell.executableDigest,
+      executionFingerprint: shell.executionFingerprint,
+      ...commandAuditSummary(shell.command)
+    } : executionIdentity ? {
+      serverIdentity: executionIdentity.serverIdentity,
+      connectionGeneration: executionIdentity.connectionGeneration,
+      catalogEpoch: executionIdentity.catalogEpoch,
+      toolDigest: executionIdentity.toolDigest
+    } : {};
+    try {
+      await audit("tool.decided", {
+        decision: permitted ? "allow" : "deny",
+        decisionSource: source,
+        ...approvalChoice ? { approvalChoice } : {},
+        ...hardDenied?.fields ?? {},
+        ...auditFields
+      });
+    } catch {
+      return {
+        result: failure(
+          "Audit unavailable; tool was not started",
+          "AUDIT_UNAVAILABLE",
+          "after_user_action",
+          {
+            version: 1,
+            dispatchOutcome: "not_sent",
+            hostError: { phase: "audit", code: "AUDIT_UNAVAILABLE" }
+          }
+        )
+      };
+    }
+    if (!permitted || signal?.aborted) {
+      const code = signal?.aborted ? "ABORTED" : hardDenied?.code ?? "PERMISSION_DENIED";
+      try {
+        await audit("tool.finished", { status: "denied", errorCode: code });
       } catch {
+        return {
+          result: failure("Audit result unavailable", "AUDIT_UNAVAILABLE", "after_user_action", {
+            version: 1,
+            dispatchOutcome: "not_sent",
+            hostError: { phase: "audit", code: "AUDIT_UNAVAILABLE" }
+          })
+        };
       }
+      return {
+        result: failure(
+          signal?.aborted ? "Operation cancelled" : hardDenied?.message ?? "Tool permission denied",
+          code,
+          signal?.aborted ? "after_user_action" : hardDenied?.retryPolicy ?? "after_user_action"
+        )
+      };
     }
-  }
-  /** 中止本轮正在等待或执行的工具；调用方仍须等待 runAll 完成资源回收及结果审计。 */
+    if (shell) {
+      try {
+        const next = tool.approvalScope?.(finalInput, rootDir, executionCwd);
+        if (next?.executionFingerprint !== shell.executionFingerprint) {
+          if (attempt === 0 && next) {
+            try {
+              await audit("tool.target_changed", { status: "redeciding" });
+            } catch {
+              return {
+                result: failure(
+                  "Audit unavailable; tool was not started",
+                  "AUDIT_UNAVAILABLE",
+                  "after_user_action",
+                  {
+                    version: 1,
+                    dispatchOutcome: "not_sent",
+                    hostError: { phase: "audit", code: "AUDIT_UNAVAILABLE" }
+                  }
+                )
+              };
+            }
+            shell = next;
+            continue;
+          }
+          await audit("tool.finished", { status: "target_changed", errorCode: "TARGET_CHANGED" });
+          return {
+            result: failure(
+              "Execution target changed after approval",
+              "TARGET_CHANGED",
+              "after_user_action"
+            )
+          };
+        }
+      } catch {
+        return {
+          result: failure(
+            "Execution target changed after approval",
+            "TARGET_CHANGED",
+            "after_user_action"
+          )
+        };
+      }
+    }
+    if (executionIdentity) {
+      try {
+        const nextIdentity = tool.executionIdentity?.(finalInput, rootDir);
+        if (!nextIdentity || nextIdentity.serverIdentity !== executionIdentity.serverIdentity || nextIdentity.connectionGeneration !== executionIdentity.connectionGeneration || nextIdentity.catalogEpoch !== executionIdentity.catalogEpoch || nextIdentity.toolDigest !== executionIdentity.toolDigest) {
+          await audit("tool.finished", {
+            status: "identity_changed",
+            errorCode: "MCP_TOOL_CHANGED"
+          });
+          return {
+            result: failure(
+              "Tool execution identity changed after approval",
+              "MCP_TOOL_CHANGED",
+              "after_user_action",
+              {
+                version: 1,
+                dispatchOutcome: "not_sent",
+                hostError: { phase: "validation", code: "MCP_TOOL_CHANGED" }
+              }
+            )
+          };
+        }
+      } catch {
+        return {
+          result: failure(
+            "Tool execution identity check failed after approval",
+            "MCP_TOOL_CHANGED",
+            "after_user_action",
+            {
+              version: 1,
+              dispatchOutcome: "not_sent"
+            }
+          )
+        };
+      }
+    }
+    break;
+  }
+  return { shell, auditFields };
+}
+
+// src/runtime/executor/result.ts
+import { createHash as createHash13 } from "crypto";
+async function closeToolResult(deps) {
+  const { call, tool, finalInput, hookCtx, hooks, neverFailures, audit, onToolResult, startedAt } = deps;
+  const resultBlock = {
+    type: "tool_result",
+    toolUseId: call.id,
+    content: deps.output.content,
+    isError: deps.output.isError,
+    ...deps.output.errorCode ? { errorCode: deps.output.errorCode, retryPolicy: deps.output.retryPolicy } : {},
+    execution: deps.output.execution
+  };
+  if (resultBlock.isError && resultBlock.errorCode) {
+    resultBlock.content = JSON.stringify({
+      code: resultBlock.errorCode,
+      retryPolicy: resultBlock.retryPolicy,
+      message: deps.output.content
+    });
+  }
+  try {
+    for (const hook of hooks.get("tool:after")) {
+      await hook(
+        hookCtx,
+        { id: call.id, name: call.name, input: finalInput },
+        { output: deps.output.content, isError: deps.output.isError }
+      );
+    }
+  } catch {
+    resultBlock.content = JSON.stringify({
+      code: "HOOK_ERROR",
+      retryPolicy: "after_user_action",
+      message: "Tool finished but result processing failed"
+    });
+    resultBlock.isError = true;
+    resultBlock.errorCode = "HOOK_ERROR";
+    resultBlock.retryPolicy = "after_user_action";
+    resultBlock.execution = {
+      version: 1,
+      dispatchOutcome: resultBlock.execution?.dispatchOutcome ?? "failed",
+      hostError: {
+        phase: "hook",
+        code: "HOOK_ERROR"
+      }
+    };
+  }
+  resultBlock.durationMs = Math.max(0, Date.now() - startedAt);
+  if (resultBlock.isError && resultBlock.retryPolicy === "never") {
+    neverFailures.add(
+      createHash13("sha256").update(stableJsonStringify([call.name, finalInput])).digest("hex")
+    );
+  }
+  try {
+    await audit("tool.finished", {
+      status: resultBlock.isError ? "failed" : "completed",
+      ...resultBlock.errorCode ? { errorCode: resultBlock.errorCode } : {},
+      durationMs: resultBlock.durationMs
+    });
+  } catch {
+    resultBlock.isError = true;
+    resultBlock.errorCode = "OUTCOME_UNKNOWN";
+    resultBlock.retryPolicy = "after_user_action";
+    resultBlock.content = JSON.stringify({
+      code: "OUTCOME_UNKNOWN",
+      retryPolicy: "after_user_action",
+      message: "Tool outcome is unknown because the audit result could not be written"
+    });
+    resultBlock.execution = {
+      version: 1,
+      dispatchOutcome: resultBlock.execution?.dispatchOutcome ?? "succeeded",
+      hostError: {
+        phase: "audit",
+        code: "AUDIT_UNAVAILABLE"
+      }
+    };
+    return resultBlock;
+  }
+  await onToolResult?.(tool, finalInput, resultBlock);
+  return resultBlock;
+}
+
+// src/runtime/executor/timeout.ts
+function withToolTimeout(promise, toolName, timeoutMs, executionController) {
+  let timer;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => {
+      const error = new KapibalaError(`Tool '${toolName}' timed out after ${timeoutMs}ms`, {
+        code: "OUTCOME_UNKNOWN",
+        retryPolicy: "after_user_action",
+        safeMessage: "Tool timed out; completion of side effects is unknown"
+      });
+      reject(error);
+      executionController.abort(error);
+    }, timeoutMs);
+  });
+  return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
+}
+
+// src/runtime/executor/types.ts
+var DEFAULT_TOOL_TIMEOUT_MS = 12e4;
+
+// src/runtime/executor/index.ts
+var ToolExecutor = class {
+  hardDenial;
+  onToolResult;
+  tools;
+  hooks;
+  workspaceRoot;
+  executionCwd;
+  sandbox;
+  leaseCoordinator;
+  rootDir;
+  signal;
+  logger;
+  toolTimeoutMs;
+  eventLogger;
+  sessionId;
+  runId;
+  branchId;
+  rootTaskId;
+  depth;
+  agentId;
+  committedActions = [];
+  rollbackActions = [];
+  mode;
+  permissionRules;
+  approvalChannel;
+  approvalCache;
+  policy = new PermissionPolicy();
+  neverFailures = /* @__PURE__ */ new Set();
+  cancellation = new AbortController();
+  constructor(options) {
+    this.hardDenial = options.hardDenial;
+    this.onToolResult = options.onToolResult;
+    this.tools = options.tools;
+    this.hooks = options.hooks;
+    this.workspaceRoot = options.workspaceRoot ?? options.rootDir;
+    this.executionCwd = options.executionCwd ?? options.rootDir;
+    this.sandbox = options.sandbox;
+    this.leaseCoordinator = options.leaseCoordinator;
+    this.rootDir = options.rootDir;
+    this.signal = options.signal ? AbortSignal.any([options.signal, this.cancellation.signal]) : this.cancellation.signal;
+    this.logger = options.logger;
+    this.toolTimeoutMs = options.toolTimeoutMs ?? DEFAULT_TOOL_TIMEOUT_MS;
+    this.eventLogger = options.eventLogger;
+    this.sessionId = options.sessionId;
+    this.runId = options.runId;
+    this.branchId = options.branchId;
+    this.rootTaskId = options.rootTaskId;
+    this.depth = options.depth;
+    this.agentId = options.agentId;
+    this.mode = options.mode ?? "Approval";
+    this.permissionRules = options.permissionRules ?? [];
+    this.approvalChannel = options.approvalChannel;
+    this.approvalCache = options.approvalCache ?? new SessionApprovalCache();
+  }
+  /**
+   * 父工具事务提交成功后调用，按注册顺序执行所有提交动作。
+   * 动作执行成功后逐项清理对应回滚动作，若某项失败保留剩余回滚动作。
+   */
+  async commit() {
+    while (this.committedActions.length > 0) {
+      const action = this.committedActions.shift();
+      await action();
+      this.rollbackActions.shift();
+    }
+    this.rollbackActions.length = 0;
+  }
+  /**
+   * 父工具事务提交失败或取消时调用，按逆序执行所有回滚清理动作。
+   */
+  async rollback() {
+    const actions = [...this.rollbackActions].reverse();
+    this.committedActions.length = 0;
+    this.rollbackActions.length = 0;
+    for (const action of actions) {
+      try {
+        await action();
+      } catch {
+      }
+    }
+  }
+  /** 中止本轮正在等待或执行的工具；调用方仍须等待 runAll 完成资源回收及结果审计。 */
   cancel() {
     this.cancellation.abort();
   }
@@ -7725,191 +8288,28 @@ var ToolExecutor = class {
       }
       return failure("Invalid tool execution identity", "INVALID_TARGET");
     }
-    let auditFields = {};
-    for (let attempt = 0; attempt < 2; attempt++) {
-      const request = {
-        toolName: call.name,
-        capabilities: tool.metadata?.permissions ?? [],
-        input: finalInput,
-        rootDir: this.rootDir,
-        ...shell ? { shell } : {},
-        ...executionIdentity ? { executionIdentity } : {},
-        // 解释器内建查询与内容已绑定摘要的工作区直引脚本可确认不受外部脚本变更影响，
-        // 允许会话级批准；其余 shell 命令仅允许单次批准。
-        // 非 shell 工具（含深度绑定 executionIdentity 的外部工具）允许会话级批准。
-        sessionAllowed: !shell || /^(?:pwd|get-location)$/i.test(shell.command.trim()) || shell.scriptDigest !== void 0
-      };
-      const repeatKey = createHash12("sha256").update(stableJsonStringify([call.name, finalInput])).digest("hex");
-      if (this.neverFailures.has(repeatKey)) {
-        try {
-          await audit("tool.decided", { decision: "deny", decisionSource: "repeat_block" });
-          await audit("tool.finished", { status: "blocked", errorCode: "REPEAT_BLOCKED" });
-        } catch {
-          return failure(
-            "Audit unavailable; tool was not started",
-            "AUDIT_UNAVAILABLE",
-            "after_user_action",
-            {
-              version: 1,
-              dispatchOutcome: "not_sent",
-              hostError: { phase: "audit", code: "AUDIT_UNAVAILABLE" }
-            }
-          );
-        }
-        return failure(
-          "Identical failed tool call cannot be repeated in this run",
-          "REPEAT_BLOCKED"
-        );
-      }
-      const hardDenied = this.hardDenial?.(tool, finalInput);
-      const cached = this.approvalCache.get(request);
-      const decision = this.policy.decide({
-        hardDenied: hardDenied !== void 0,
-        mode: typeof this.mode === "function" ? this.mode() : this.mode,
-        toolName: call.name,
-        capabilities: request.capabilities,
-        dangerous: tool.metadata?.dangerous,
-        cachedApproval: cached === "allow",
-        cachedDenial: cached === "deny",
-        rules: this.permissionRules,
-        ...shell ? { shell } : {}
-      });
-      let permitted = decision.decision === "allow";
-      let source = decision.source;
-      let approvalChoice;
-      if (decision.decision === "ask") {
-        let choice = "deny_once";
-        try {
-          choice = await this.approvalChannel?.requestApproval(request, this.signal) ?? "deny_once";
-        } catch {
-          choice = "cancel";
-        }
-        approvalChoice = choice;
-        if (choice === "allow_session" && request.sessionAllowed)
-          this.approvalCache.set(request, "allow");
-        if (choice === "deny_session") this.approvalCache.set(request, "deny");
-        permitted = choice === "allow_once" || choice === "allow_session" && request.sessionAllowed;
-        source = this.approvalChannel ? "human" : "non_interactive";
-      }
-      auditFields = shell ? {
-        shell: shell.interpreter,
-        cwdDigest: createHash12("sha256").update(shell.cwd).digest("hex"),
-        executableDigest: shell.executableDigest,
-        executionFingerprint: shell.executionFingerprint,
-        ...commandAuditSummary(shell.command)
-      } : executionIdentity ? {
-        serverIdentity: executionIdentity.serverIdentity,
-        connectionGeneration: executionIdentity.connectionGeneration,
-        catalogEpoch: executionIdentity.catalogEpoch,
-        toolDigest: executionIdentity.toolDigest
-      } : {};
-      try {
-        await audit("tool.decided", {
-          decision: permitted ? "allow" : "deny",
-          decisionSource: source,
-          ...approvalChoice ? { approvalChoice } : {},
-          ...hardDenied?.fields ?? {},
-          ...auditFields
-        });
-      } catch {
-        return failure(
-          "Audit unavailable; tool was not started",
-          "AUDIT_UNAVAILABLE",
-          "after_user_action",
-          {
-            version: 1,
-            dispatchOutcome: "not_sent",
-            hostError: { phase: "audit", code: "AUDIT_UNAVAILABLE" }
-          }
-        );
-      }
-      if (!permitted || this.signal?.aborted) {
-        const code = this.signal?.aborted ? "ABORTED" : hardDenied?.code ?? "PERMISSION_DENIED";
-        try {
-          await audit("tool.finished", { status: "denied", errorCode: code });
-        } catch {
-          return failure("Audit result unavailable", "AUDIT_UNAVAILABLE", "after_user_action", {
-            version: 1,
-            dispatchOutcome: "not_sent",
-            hostError: { phase: "audit", code: "AUDIT_UNAVAILABLE" }
-          });
-        }
-        return failure(
-          this.signal?.aborted ? "Operation cancelled" : hardDenied?.message ?? "Tool permission denied",
-          code,
-          this.signal?.aborted ? "after_user_action" : hardDenied?.retryPolicy ?? "after_user_action"
-        );
-      }
-      if (shell) {
-        try {
-          const next = tool.approvalScope?.(finalInput, this.rootDir, this.executionCwd);
-          if (next?.executionFingerprint !== shell.executionFingerprint) {
-            if (attempt === 0 && next) {
-              try {
-                await audit("tool.target_changed", { status: "redeciding" });
-              } catch {
-                return failure(
-                  "Audit unavailable; tool was not started",
-                  "AUDIT_UNAVAILABLE",
-                  "after_user_action",
-                  {
-                    version: 1,
-                    dispatchOutcome: "not_sent",
-                    hostError: { phase: "audit", code: "AUDIT_UNAVAILABLE" }
-                  }
-                );
-              }
-              shell = next;
-              continue;
-            }
-            await audit("tool.finished", { status: "target_changed", errorCode: "TARGET_CHANGED" });
-            return failure(
-              "Execution target changed after approval",
-              "TARGET_CHANGED",
-              "after_user_action"
-            );
-          }
-        } catch {
-          return failure(
-            "Execution target changed after approval",
-            "TARGET_CHANGED",
-            "after_user_action"
-          );
-        }
-      }
-      if (executionIdentity) {
-        try {
-          const nextIdentity = tool.executionIdentity?.(finalInput, this.rootDir);
-          if (!nextIdentity || nextIdentity.serverIdentity !== executionIdentity.serverIdentity || nextIdentity.connectionGeneration !== executionIdentity.connectionGeneration || nextIdentity.catalogEpoch !== executionIdentity.catalogEpoch || nextIdentity.toolDigest !== executionIdentity.toolDigest) {
-            await audit("tool.finished", {
-              status: "identity_changed",
-              errorCode: "MCP_TOOL_CHANGED"
-            });
-            return failure(
-              "Tool execution identity changed after approval",
-              "MCP_TOOL_CHANGED",
-              "after_user_action",
-              {
-                version: 1,
-                dispatchOutcome: "not_sent",
-                hostError: { phase: "validation", code: "MCP_TOOL_CHANGED" }
-              }
-            );
-          }
-        } catch {
-          return failure(
-            "Tool execution identity check failed after approval",
-            "MCP_TOOL_CHANGED",
-            "after_user_action",
-            {
-              version: 1,
-              dispatchOutcome: "not_sent"
-            }
-          );
-        }
-      }
-      break;
-    }
+    const approval = await resolveToolApproval({
+      call,
+      finalInput,
+      tool,
+      shell,
+      executionIdentity,
+      rootDir: this.rootDir,
+      executionCwd: this.executionCwd,
+      mode: this.mode,
+      permissionRules: this.permissionRules,
+      approvalChannel: this.approvalChannel,
+      approvalCache: this.approvalCache,
+      hardDenial: this.hardDenial,
+      neverFailures: this.neverFailures,
+      policy: this.policy,
+      signal: this.signal,
+      audit,
+      failure
+    });
+    if (approval.result) return approval.result;
+    shell = approval.shell;
+    const auditFields = approval.auditFields ?? {};
     try {
       await audit("tool.started", { status: "started", ...auditFields });
     } catch {
@@ -7938,6 +8338,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,
@@ -7968,9 +8369,10 @@ var ToolExecutor = class {
             { signal: executionController.signal }
           );
         }
-        const rawResult = tool.metadata?.managesTimeout ? await tool.execute(finalInput, toolCtx) : await this.withTimeout(
+        const rawResult = tool.metadata?.managesTimeout ? await tool.execute(finalInput, toolCtx) : await withToolTimeout(
           tool.execute(finalInput, toolCtx),
           call.name,
+          this.toolTimeoutMs,
           executionController
         );
         if (typeof tool.toExecutionResult === "function") {
@@ -8031,105 +8433,18 @@ var ToolExecutor = class {
         dispatchOutcome: outcome
       };
     }
-    const resultBlock = {
-      type: "tool_result",
-      toolUseId: call.id,
-      content: outputStr,
-      isError,
-      ...errorCode ? { errorCode, retryPolicy } : {},
-      execution
-    };
-    if (resultBlock.isError && resultBlock.errorCode) {
-      resultBlock.content = JSON.stringify({
-        code: resultBlock.errorCode,
-        retryPolicy: resultBlock.retryPolicy,
-        message: outputStr
-      });
-    }
-    try {
-      for (const hook of this.hooks.get("tool:after")) {
-        await hook(
-          hookCtx,
-          { id: call.id, name: call.name, input: finalInput },
-          { output: outputStr, isError }
-        );
-      }
-    } catch {
-      resultBlock.content = JSON.stringify({
-        code: "HOOK_ERROR",
-        retryPolicy: "after_user_action",
-        message: "Tool finished but result processing failed"
-      });
-      resultBlock.isError = true;
-      resultBlock.errorCode = "HOOK_ERROR";
-      resultBlock.retryPolicy = "after_user_action";
-      resultBlock.execution = {
-        version: 1,
-        dispatchOutcome: resultBlock.execution?.dispatchOutcome ?? "failed",
-        hostError: {
-          phase: "hook",
-          code: "HOOK_ERROR"
-        }
-      };
-    }
-    resultBlock.durationMs = Math.max(0, Date.now() - startedAt);
-    if (resultBlock.isError && resultBlock.retryPolicy === "never") {
-      this.neverFailures.add(
-        createHash12("sha256").update(stableJsonStringify([call.name, finalInput])).digest("hex")
-      );
-    }
-    try {
-      await audit("tool.finished", {
-        status: resultBlock.isError ? "failed" : "completed",
-        ...resultBlock.errorCode ? { errorCode: resultBlock.errorCode } : {},
-        durationMs: resultBlock.durationMs
-      });
-    } catch {
-      resultBlock.isError = true;
-      resultBlock.errorCode = "OUTCOME_UNKNOWN";
-      resultBlock.retryPolicy = "after_user_action";
-      resultBlock.content = JSON.stringify({
-        code: "OUTCOME_UNKNOWN",
-        retryPolicy: "after_user_action",
-        message: "Tool outcome is unknown because the audit result could not be written"
-      });
-      resultBlock.execution = {
-        version: 1,
-        dispatchOutcome: resultBlock.execution?.dispatchOutcome ?? "succeeded",
-        hostError: {
-          phase: "audit",
-          code: "AUDIT_UNAVAILABLE"
-        }
-      };
-      return resultBlock;
-    }
-    await this.onToolResult?.(tool, finalInput, resultBlock);
-    return resultBlock;
-  }
-  /**
-   * 给工具执行加超时护栏：Promise.race 在超时后reject，循环拿到 isError 结果继续运转，
-   * 不会因某个异步工具(如未来接入的网络/exec 工具)挂起而永久卡死。
-   *
-   * 局限：同步 CPU 密集型实现会阻塞事件循环，timer 同样无法触发；
-   * 因此内置工具仍需避免执行用户可控的同步高复杂度计算。
-   */
-  withTimeout(promise, toolName, executionController) {
-    let timer;
-    const timeout = new Promise((_, reject) => {
-      timer = setTimeout(() => {
-        const error = new KapibalaError(
-          `Tool '${toolName}' timed out after ${this.toolTimeoutMs}ms`,
-          {
-            code: "OUTCOME_UNKNOWN",
-            retryPolicy: "after_user_action",
-            safeMessage: "Tool timed out; completion of side effects is unknown"
-          }
-        );
-        reject(error);
-        executionController.abort(error);
-      }, this.toolTimeoutMs);
+    return closeToolResult({
+      call,
+      tool,
+      finalInput,
+      hookCtx,
+      hooks: this.hooks,
+      neverFailures: this.neverFailures,
+      audit,
+      onToolResult: this.onToolResult,
+      startedAt,
+      output: { content: outputStr, isError, errorCode, retryPolicy, execution }
     });
-    return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
   }
   /**
    * 构建当前会话在派生时刻的父权限策略快照。
@@ -8728,7 +9043,7 @@ var OpenAICompatibleProvider = class {
 };
 
 // src/models/anthropic/index.ts
-import { createHash as createHash13 } from "crypto";
+import { createHash as createHash14 } from "crypto";
 function invalidResponse2() {
   throw new ModelError("Invalid Anthropic response state", {
     code: "MODEL_INVALID_RESPONSE",
@@ -8743,7 +9058,7 @@ function wireToolId(id) {
       stage: "request",
       retryable: false
     });
-  return /^[A-Za-z0-9_-]{1,64}$/.test(id) ? id : `call_${createHash13("sha256").update(id).digest("hex").slice(0, 48)}`;
+  return /^[A-Za-z0-9_-]{1,64}$/.test(id) ? id : `call_${createHash14("sha256").update(id).digest("hex").slice(0, 48)}`;
 }
 var AnthropicProvider = class {
   name = "anthropic";
@@ -9109,7 +9424,7 @@ var AnthropicProvider = class {
 };
 
 // src/models/openai-responses/index.ts
-import { createHash as createHash14 } from "crypto";
+import { createHash as createHash15 } from "crypto";
 function invalid(message = "Invalid Responses output Item") {
   throw new ModelError(message, {
     code: "MODEL_INVALID_RESPONSE",
@@ -9130,7 +9445,7 @@ function wireCallId(id) {
       stage: "request",
       retryable: false
     });
-  return /^[A-Za-z0-9_-]{1,64}$/.test(id) ? id : `call_${createHash14("sha256").update(id).digest("hex").slice(0, 48)}`;
+  return /^[A-Za-z0-9_-]{1,64}$/.test(id) ? id : `call_${createHash15("sha256").update(id).digest("hex").slice(0, 48)}`;
 }
 function validateItem(item, final) {
   if (!item || typeof item !== "object" || !nonempty(item.id)) invalid();
@@ -9827,13 +10142,99 @@ Follow these key behavioral rules:
     }
     return lines.join("\n");
   }
-  getL3Environment() {
-    const platform = os6.platform();
-    return `# Environment Context:
-- Current Working Directory (Workspace Root): ${this.rootDir}
-- Operating System: ${platform}`;
+  getL3Environment() {
+    const platform = os6.platform();
+    return `# Environment Context:
+- Current Working Directory (Workspace Root): ${this.rootDir}
+- Operating System: ${platform}`;
+  }
+};
+
+// src/runtime/loop/hook-integrity.ts
+function assertHookToolDefinitionsIntact(request, snapshot) {
+  if (!request.tools) return;
+  for (const t of request.tools) {
+    const original = snapshot.get(t.name);
+    if (!original) {
+      throw new ModelError(`Hook injected tool '${t.name}' not present in snapshot`, {
+        stage: "request",
+        retryable: false
+      });
+    }
+    if (t.description !== original.description || JSON.stringify(t.parameters) !== JSON.stringify(original.parameters)) {
+      throw new ModelError(
+        `Hook mutated tool definition for '${t.name}' (description or parameters drifted from snapshot)`,
+        {
+          stage: "request",
+          retryable: false
+        }
+      );
+    }
+  }
+}
+function snapshotAssistantIntegrity(message) {
+  return {
+    identity: stableSerialize({ ...message, content: void 0 }),
+    originalTools: stableSerialize(
+      message.content.filter((block) => block.type === "tool_use" || block.type === "tool_result")
+    ),
+    originalContent: stableSerialize(message.content),
+    privateOutput: message.content.some(
+      (block) => block.type === "provider_state" || block.type === "redacted_thinking" || block.type === "thinking" && Boolean(block.origin || block.signature)
+    ),
+    hasToolCalls: message.content.some((block) => block.type === "tool_use")
+  };
+}
+function assertAssistantMessageUntampered(message, snapshot) {
+  if (snapshot.identity !== stableSerialize({ ...message, content: void 0 }))
+    throw new ModelError("Hook changed assistant message identity", {
+      stage: "request",
+      retryable: false
+    });
+  if (snapshot.originalTools !== stableSerialize(
+    message.content.filter((block) => block.type === "tool_use" || block.type === "tool_result")
+  ))
+    throw new ModelError("Hook changed validated tool model output", {
+      stage: "request",
+      retryable: false
+    });
+  if (snapshot.originalContent !== stableSerialize(message.content)) {
+    if (snapshot.privateOutput || message.content.some(
+      (block) => block.type === "provider_state" || block.type === "redacted_thinking" || block.type === "thinking" && Boolean(block.origin || block.signature)
+    ))
+      throw new ModelError("Hook changed signed or private model output", {
+        stage: "request",
+        retryable: false
+      });
+    if (snapshot.hasToolCalls)
+      throw new ModelError("Hook changed validated tool model output", {
+        stage: "request",
+        retryable: false
+      });
+    for (const block of message.content)
+      if (block.type === "text" || block.type === "tool_use") block.protocolMeta = void 0;
+  }
+}
+
+// src/runtime/loop/tool-call-validation.ts
+function assertToolCallsExecutable(history, toolCalls) {
+  const knownCalls = new Set(
+    history.flatMap(
+      (message) => message.content.filter((block) => block.type === "tool_use").map((block) => block.id)
+    )
+  );
+  for (const call of toolCalls) {
+    if (!call.name?.trim() || !call.input || typeof call.input !== "object" || Array.isArray(call.input))
+      throw new ModelError("Invalid tool call arguments or name; no tools executed", {
+        code: "MODEL_INVALID_RESPONSE",
+        stage: "stream",
+        retryable: false
+      });
+    if (!call.id?.trim() || knownCalls.has(call.id))
+      throw new ModelError("Duplicate tool call ID; no tools executed");
+    knownCalls.add(call.id);
   }
-};
+}
 
 // src/runtime/loop/index.ts
 var AgentLoop = class {
@@ -9917,26 +10318,7 @@ var AgentLoop = class {
           request = modified;
         }
       }
-      if (request.tools) {
-        for (const t of request.tools) {
-          const original = toolSnapshot.get(t.name);
-          if (!original) {
-            throw new ModelError(`Hook injected tool '${t.name}' not present in snapshot`, {
-              stage: "request",
-              retryable: false
-            });
-          }
-          if (t.description !== original.description || JSON.stringify(t.parameters) !== JSON.stringify(original.parameters)) {
-            throw new ModelError(
-              `Hook mutated tool definition for '${t.name}' (description or parameters drifted from snapshot)`,
-              {
-                stage: "request",
-                retryable: false
-              }
-            );
-          }
-        }
-      }
+      assertHookToolDefinitionsIntact(request, toolSnapshot);
       if (this.prepareRequest) request = yield* this.prepareRequest(request, history);
       yield {
         type: "step_log",
@@ -10087,22 +10469,7 @@ var AgentLoop = class {
                 stage: "stream",
                 retryable: false
               });
-            const knownCalls = new Set(
-              history.flatMap(
-                (message) => message.content.filter((block) => block.type === "tool_use").map((block) => block.id)
-              )
-            );
-            for (const call of toolCalls) {
-              if (!call.name?.trim() || !call.input || typeof call.input !== "object" || Array.isArray(call.input))
-                throw new ModelError("Invalid tool call arguments or name; no tools executed", {
-                  code: "MODEL_INVALID_RESPONSE",
-                  stage: "stream",
-                  retryable: false
-                });
-              if (!call.id?.trim() || knownCalls.has(call.id))
-                throw new ModelError("Duplicate tool call ID; no tools executed");
-              knownCalls.add(call.id);
-            }
+            assertToolCallsExecutable(history, toolCalls);
             break;
           } catch (error) {
             if (!(error instanceof ContextOverflowError) || outputSeen || accumulatedText || accumulatedThinking || toolCalls.length || overflowRetried || !this.prepareRequest || this.signal?.aborted)
@@ -10215,47 +10582,9 @@ var AgentLoop = class {
         timestamp: Date.now()
       };
       validateProtocolContent(assistantMessage.content);
-      const originalContent = stableSerialize(assistantMessage.content);
-      const identity = stableSerialize({ ...assistantMessage, content: void 0 });
-      const originalTools = stableSerialize(
-        assistantMessage.content.filter(
-          (block) => block.type === "tool_use" || block.type === "tool_result"
-        )
-      );
-      const privateOutput = assistantMessage.content.some(
-        (block) => block.type === "provider_state" || block.type === "redacted_thinking" || block.type === "thinking" && Boolean(block.origin || block.signature)
-      );
+      const integrity = snapshotAssistantIntegrity(assistantMessage);
       await this.hooks.emit("model:after", hookCtx, { message: assistantMessage });
-      if (identity !== stableSerialize({ ...assistantMessage, content: void 0 }))
-        throw new ModelError("Hook changed assistant message identity", {
-          stage: "request",
-          retryable: false
-        });
-      if (originalTools !== stableSerialize(
-        assistantMessage.content.filter(
-          (block) => block.type === "tool_use" || block.type === "tool_result"
-        )
-      ))
-        throw new ModelError("Hook changed validated tool model output", {
-          stage: "request",
-          retryable: false
-        });
-      if (originalContent !== stableSerialize(assistantMessage.content)) {
-        if (privateOutput || assistantMessage.content.some(
-          (block) => block.type === "provider_state" || block.type === "redacted_thinking" || block.type === "thinking" && Boolean(block.origin || block.signature)
-        ))
-          throw new ModelError("Hook changed signed or private model output", {
-            stage: "request",
-            retryable: false
-          });
-        if (toolCalls.length)
-          throw new ModelError("Hook changed validated tool model output", {
-            stage: "request",
-            retryable: false
-          });
-        for (const block of assistantMessage.content)
-          if (block.type === "text" || block.type === "tool_use") block.protocolMeta = void 0;
-      }
+      assertAssistantMessageUntampered(assistantMessage, integrity);
       validateProtocolContent(assistantMessage.content);
       if (toolCalls.length === 0) {
         history.push(assistantMessage);
@@ -10660,6 +10989,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();
@@ -10743,6 +11073,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",
@@ -10885,6 +11222,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);
@@ -10937,6 +11275,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();
@@ -10962,7 +11301,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;
@@ -11011,14 +11353,17 @@ var AgentRuntime = class {
         task.status = "failed";
       }
       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)) {
         task.status = "failed";
         task.error = runError?.message ?? "Unknown execution failure";
       }
+      if (task.status === "failed") {
+        await this.cascadeCancelChildren(task.agentId, task.error ?? "Parent task failed");
+      }
       task.finishedAt = Date.now();
       this.releaseTaskSlotOnce(task);
       this.outbox.enqueueFromTask(task);
@@ -11088,6 +11433,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;
@@ -11196,6 +11542,7 @@ var AgentRuntime = class {
     }
     this.timers.clear();
     this.controllers.clear();
+    this.runnerContexts.clear();
     this.stateListeners.clear();
   }
   /**
@@ -11336,9 +11683,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",
@@ -11617,6 +11970,274 @@ function cancellableGenerator(create, external) {
   };
 }
 
+// src/context/session/persistence.ts
+async function persistAssistantMessage(event, store, markUnknownUsage) {
+  if (store) await store.append(event.message);
+  if (!event.usage) markUnknownUsage();
+}
+async function persistToolMessages(messages, store) {
+  if (!store) return;
+  for (const message of messages) await store.append(message);
+}
+function buildInterruptedToolMessage(assistantEvent) {
+  return {
+    id: createMessageId(),
+    role: "tool",
+    content: assistantEvent.message.content.filter((block) => block.type === "tool_use").map((toolUse) => ({
+      type: "tool_result",
+      toolUseId: toolUse.id,
+      content: JSON.stringify({
+        code: "OUTCOME_UNKNOWN",
+        retryPolicy: "after_user_action",
+        message: "Tool execution was interrupted; outcome is unknown"
+      }),
+      isError: true,
+      errorCode: "OUTCOME_UNKNOWN",
+      retryPolicy: "after_user_action"
+    })),
+    timestamp: Date.now()
+  };
+}
+function findClosedToolMessages(history, assistantEvent) {
+  const assistantIndex = history.lastIndexOf(assistantEvent.message);
+  if (assistantIndex < 0) return [];
+  const expected = new Set(
+    assistantEvent.message.content.filter((block) => block.type === "tool_use").map((toolUse) => toolUse.id)
+  );
+  const messages = [];
+  for (let index2 = assistantIndex + 1; index2 < history.length; index2++) {
+    const message = history[index2];
+    if (message.role !== "tool") break;
+    messages.push(message);
+    for (const block of message.content) {
+      if (block.type === "tool_result") expected.delete(block.toolUseId);
+    }
+  }
+  return expected.size === 0 ? messages : [];
+}
+
+// src/context/session/request-prepare.ts
+function verifyPrivateBlockIntegrity(projected, sourceView) {
+  for (const message of projected) {
+    const original = sourceView.find((source) => source.id === message.id);
+    const privateBag = /* @__PURE__ */ new Map();
+    const blockBag = /* @__PURE__ */ new Map();
+    for (const block of original?.content ?? []) {
+      const serialized = stableSerialize(block);
+      if (block.type === "provider_state" || block.type === "redacted_thinking" || block.type === "thinking" && block.origin)
+        privateBag.set(serialized, (privateBag.get(serialized) ?? 0) + 1);
+      blockBag.set(serialized, (blockBag.get(serialized) ?? 0) + 1);
+    }
+    const take = (bag, serialized) => {
+      const count = bag.get(serialized) ?? 0;
+      if (!count) return false;
+      if (count === 1) bag.delete(serialized);
+      else bag.set(serialized, count - 1);
+      return true;
+    };
+    for (const block of message.content) {
+      if (block.type === "provider_state" || block.type === "redacted_thinking" || block.type === "thinking" && block.origin) {
+        if (!original || !take(privateBag, stableSerialize(block)))
+          throw new ModelError("Hook changed signed or private request provenance", {
+            stage: "request",
+            retryable: false
+          });
+      }
+      if (block.type !== "text" && block.type !== "tool_use") continue;
+      if (block.protocolMeta && !take(blockBag, stableSerialize(block)))
+        block.protocolMeta = void 0;
+    }
+  }
+}
+function assertSignedContinuationStable(check) {
+  const { candidate, previousRequest, history, runId, nativeBinding, projectHistory } = check;
+  const frozen = Boolean(
+    previousRequest && history.some(
+      (message) => message.interactionId === runId && message.content.some(
+        (block) => block.type === "provider_state" || block.type === "redacted_thinking" || block.type === "thinking" && Boolean(block.signature && block.origin?.runId === runId)
+      )
+    )
+  );
+  if (frozen) {
+    const generated = nativeBinding ? projectProtocolHistory(
+      projectHistory(history).filter(
+        (message) => message.interactionId === runId && message.role !== "user"
+      ),
+      nativeBinding,
+      candidate.context
+    ) : [];
+    for (const original of generated) {
+      const matches = candidate.messages.filter((message) => message.id === original.id);
+      if (matches.length !== 1 || stableSerialize(matches[0]) !== stableSerialize(original))
+        throw new ModelError("Signed continuation prefix or tool chain changed", {
+          stage: "request",
+          retryable: false
+        });
+    }
+  }
+  if (frozen && previousRequest && (stableSerialize(candidate.messages.slice(0, previousRequest.messages.length)) !== stableSerialize(previousRequest.messages) || candidate.systemPrompt !== previousRequest.systemPrompt || stableSerialize(candidate.tools) !== stableSerialize(previousRequest.tools)))
+    throw new ModelError("Signed continuation prefix changed", {
+      stage: "request",
+      retryable: false
+    });
+  return frozen;
+}
+
+// src/context/session/skills.ts
+function createSkillResourceAuditor(eventLogger, sessionId) {
+  return async (source, input, page) => {
+    try {
+      await eventLogger.recordAudit({
+        level: "info",
+        event: "skill.resource_read",
+        sessionId,
+        runId: source.runId,
+        fields: {
+          skillName: source.name,
+          contentDigest: source.contentDigest,
+          invocationId: source.invocationId,
+          pathDigest: skillDigest(input.path),
+          resourceDigest: skillDigest(page.text),
+          outputBytes: Buffer.byteLength(page.text),
+          outputTruncated: page.truncated,
+          offset: input.offset,
+          startLine: input.startLine,
+          endLine: input.endLine
+        }
+      });
+    } catch {
+      throw new KapibalaError("Skill resource audit unavailable", {
+        code: "AUDIT_UNAVAILABLE",
+        retryPolicy: "after_user_action",
+        safeMessage: "\u6280\u80FD\u8D44\u6E90\u8BFB\u53D6\u5BA1\u8BA1\u4E0D\u53EF\u7528\uFF0C\u672C\u8F6E\u505C\u6B62"
+      });
+    }
+  };
+}
+async function commitSkillEvents(deps) {
+  const { skillRuntime, eventLogger, sessionId, runId, persistence } = deps;
+  if (!skillRuntime) return [];
+  return skillRuntime.commit(async (source, messageId) => {
+    try {
+      await eventLogger.recordAudit({
+        level: "info",
+        event: "skill.loaded",
+        sessionId,
+        runId,
+        fields: {
+          skillName: source.name,
+          skillScope: source.scope,
+          contentDigest: source.contentDigest,
+          renderedDigest: source.renderedDigest,
+          pathDigest: skillDigest(source.filePath),
+          caller: source.caller,
+          invocationId: source.invocationId,
+          messageId
+        }
+      });
+    } catch {
+      throw new KapibalaError("Skill commit audit unavailable", {
+        code: "AUDIT_UNAVAILABLE",
+        retryPolicy: "after_user_action",
+        safeMessage: "\u6280\u80FD\u63D0\u4EA4\u5BA1\u8BA1\u4E0D\u53EF\u7528\uFF0C\u672C\u8F6E\u505C\u6B62"
+      });
+    }
+  }, persistence);
+}
+async function authorizeExplicitSkill(deps) {
+  const {
+    name,
+    runId,
+    signal,
+    rootDir,
+    mode,
+    permissionRules,
+    approvalChannel,
+    approvalCache,
+    eventLogger,
+    sessionId
+  } = deps;
+  const request = {
+    toolName: "load_skill",
+    capabilities: ["fs:read"],
+    input: { name },
+    rootDir,
+    sessionAllowed: true
+  };
+  const cached = approvalCache.get(request);
+  const decision = new PermissionPolicy().decide({
+    toolName: request.toolName,
+    capabilities: request.capabilities,
+    mode,
+    rules: permissionRules,
+    cachedApproval: cached === "allow",
+    cachedDenial: cached === "deny"
+  });
+  let permitted = decision.decision === "allow";
+  let approvalChoice;
+  if (decision.decision === "ask") {
+    try {
+      approvalChoice = await approvalChannel?.requestApproval(request, signal) ?? "deny_once";
+    } catch {
+      approvalChoice = "cancel";
+    }
+    permitted = approvalChoice === "allow_once" || approvalChoice === "allow_session";
+    if (approvalChoice === "allow_session") approvalCache.set(request, "allow");
+    if (approvalChoice === "deny_session") approvalCache.set(request, "deny");
+  }
+  await eventLogger.recordAudit({
+    level: "info",
+    event: "skill.decided",
+    sessionId,
+    runId,
+    fields: {
+      skillName: name,
+      caller: "user",
+      decision: permitted && !signal?.aborted ? "allow" : "deny",
+      decisionSource: decision.decision === "ask" ? approvalChannel ? "human" : "non_interactive" : decision.source,
+      approvalChoice
+    }
+  });
+  if (!permitted) throw skillFailure("SKILL_INVOCATION_FORBIDDEN", "\u5BBF\u4E3B\u6743\u9650\u7981\u6B62\u663E\u5F0F\u6280\u80FD\u8BFB\u53D6");
+  signal?.throwIfAborted();
+}
+
+// src/context/session/usage.ts
+function recordUsage(attemptId, usage, accountedAttempts, usageStats) {
+  if (accountedAttempts.has(attemptId)) return "duplicate";
+  if (!usage || ![usage.promptTokens, usage.completionTokens, usage.totalTokens].every(
+    (n) => Number.isSafeInteger(n) && n >= 0
+  ))
+    return "unknown";
+  accountedAttempts.add(attemptId);
+  usageStats.promptTokens += usage.promptTokens;
+  usageStats.completionTokens += usage.completionTokens;
+  usageStats.totalTokens += usage.totalTokens;
+  return "recorded";
+}
+function recordSummaryUsage(attemptId, usage, summaryAttempts, summaryUsage) {
+  if (summaryAttempts.has(attemptId)) return "duplicate";
+  if (!usage || ![usage.promptTokens, usage.completionTokens, usage.totalTokens].every(
+    (n) => Number.isSafeInteger(n) && n >= 0
+  ))
+    return "unknown";
+  summaryAttempts.add(attemptId);
+  summaryUsage.promptTokens += usage.promptTokens;
+  summaryUsage.completionTokens += usage.completionTokens;
+  summaryUsage.totalTokens += usage.totalTokens;
+  return "recorded";
+}
+function computeContextUsage(profile, usedTokens, estimatedUsage = false) {
+  const contextWindow = resolveContextWindow(profile.contextWindow);
+  return {
+    usedTokens,
+    limitTokens: contextWindow.tokens,
+    percent: usedTokens === void 0 ? void 0 : usedTokens / contextWindow.tokens * 100,
+    estimatedLimit: contextWindow.estimated,
+    ...estimatedUsage ? { estimatedUsage: true } : {}
+  };
+}
+
 // src/context/session/index.ts
 var AgentSession = class {
   skillRegistry;
@@ -11701,41 +12322,27 @@ 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.userInstructionsPath = config.userInstructionsPath;
+    const sinks = config.eventLogger ? void 0 : createDefaultLogSinks(config.loggingDirectory);
+    const eventLogger = config.eventLogger ?? new StructuredLogger({
+      operationSink: sinks.operationSink,
+      auditSink: sinks.auditSink,
+      debug: config.logger !== void 0,
+      onDiagnostic: config.onDiagnostic ?? config.logger
+    });
+    this.eventLogger = {
+      record: (input) => eventLogger.record({ ...input, conversationId: this.persistentId }),
+      recordAudit: (input) => eventLogger.recordAudit({ ...input, conversationId: this.persistentId })
+    };
+    this.auditRecoveryDirectory = config.auditRecoveryDirectory ?? sinks?.auditSink.directory;
     this.tools = new ToolRegistry();
     if (config.skills) {
       this.skillRegistry = new SkillRegistry(config.skills);
       this.skillRuntime = new SkillRuntime(
         this.skillRegistry,
         this.tools,
-        async (source, input, page) => {
-          try {
-            await this.eventLogger.recordAudit({
-              level: "info",
-              event: "skill.resource_read",
-              sessionId: this.sessionId,
-              runId: source.runId,
-              fields: {
-                skillName: source.name,
-                contentDigest: source.contentDigest,
-                invocationId: source.invocationId,
-                pathDigest: skillDigest(input.path),
-                resourceDigest: skillDigest(page.text),
-                outputBytes: Buffer.byteLength(page.text),
-                outputTruncated: page.truncated,
-                offset: input.offset,
-                startLine: input.startLine,
-                endLine: input.endLine
-              }
-            });
-          } catch {
-            throw new KapibalaError("Skill resource audit unavailable", {
-              code: "AUDIT_UNAVAILABLE",
-              retryPolicy: "after_user_action",
-              safeMessage: "\u6280\u80FD\u8D44\u6E90\u8BFB\u53D6\u5BA1\u8BA1\u4E0D\u53EF\u7528\uFF0C\u672C\u8F6E\u505C\u6B62"
-            });
-          }
-        }
+        createSkillResourceAuditor(this.eventLogger, this.sessionId)
       );
     }
     this.hooks = new HookRegistry();
@@ -11748,19 +12355,6 @@ var AgentSession = class {
     this.mode = config.mode ?? "Approval";
     this.permissionRules = config.permissionRules ?? [];
     this.approvalChannel = config.approvalChannel;
-    this.userInstructionsPath = config.userInstructionsPath;
-    const sinks = config.eventLogger ? void 0 : createDefaultLogSinks(config.loggingDirectory);
-    const eventLogger = config.eventLogger ?? new StructuredLogger({
-      operationSink: sinks.operationSink,
-      auditSink: sinks.auditSink,
-      debug: config.logger !== void 0,
-      onDiagnostic: config.onDiagnostic ?? config.logger
-    });
-    this.eventLogger = {
-      record: (input) => eventLogger.record({ ...input, conversationId: this.persistentId }),
-      recordAudit: (input) => eventLogger.recordAudit({ ...input, conversationId: this.persistentId })
-    };
-    this.auditRecoveryDirectory = config.auditRecoveryDirectory ?? sinks?.auditSink.directory;
     this.rootTaskId = config.rootTaskId;
     this.depth = config.depth ?? 0;
     this.agentId = config.agentId;
@@ -12365,71 +12959,21 @@ var AgentSession = class {
             runId,
             modelId: profile.id
           }) : this.context.project(history);
-          for (const message of projected) {
-            const original = sourceView.find((source) => source.id === message.id);
-            const privateBag = /* @__PURE__ */ new Map();
-            const blockBag = /* @__PURE__ */ new Map();
-            for (const block of original?.content ?? []) {
-              const serialized = stableSerialize(block);
-              if (block.type === "provider_state" || block.type === "redacted_thinking" || block.type === "thinking" && block.origin)
-                privateBag.set(serialized, (privateBag.get(serialized) ?? 0) + 1);
-              blockBag.set(serialized, (blockBag.get(serialized) ?? 0) + 1);
-            }
-            const take = (bag, serialized) => {
-              const count = bag.get(serialized) ?? 0;
-              if (!count) return false;
-              if (count === 1) bag.delete(serialized);
-              else bag.set(serialized, count - 1);
-              return true;
-            };
-            for (const block of message.content) {
-              if (block.type === "provider_state" || block.type === "redacted_thinking" || block.type === "thinking" && block.origin) {
-                if (!original || !take(privateBag, stableSerialize(block)))
-                  throw new ModelError("Hook changed signed or private request provenance", {
-                    stage: "request",
-                    retryable: false
-                  });
-              }
-              if (block.type !== "text" && block.type !== "tool_use") continue;
-              if (block.protocolMeta && !take(blockBag, stableSerialize(block)))
-                block.protocolMeta = void 0;
-            }
-          }
-          const frozen = Boolean(
-            previousRequest && history.some(
-              (message) => message.interactionId === runId && message.content.some(
-                (block) => block.type === "provider_state" || block.type === "redacted_thinking" || block.type === "thinking" && Boolean(block.signature && block.origin?.runId === runId)
-              )
-            )
-          );
+          verifyPrivateBlockIntegrity(projected, sourceView);
           const candidate = {
             ...request,
             messages: projected,
             context: { runId, modelId: profile.id },
             signal: options?.signal
           };
-          if (frozen) {
-            const generated = nativeBinding ? projectProtocolHistory(
-              this.context.project(history).filter(
-                (message) => message.interactionId === runId && message.role !== "user"
-              ),
-              nativeBinding,
-              candidate.context
-            ) : [];
-            for (const original of generated) {
-              const matches = candidate.messages.filter((message) => message.id === original.id);
-              if (matches.length !== 1 || stableSerialize(matches[0]) !== stableSerialize(original))
-                throw new ModelError("Signed continuation prefix or tool chain changed", {
-                  stage: "request",
-                  retryable: false
-                });
-            }
-          }
-          if (frozen && previousRequest && (stableSerialize(candidate.messages.slice(0, previousRequest.messages.length)) !== stableSerialize(previousRequest.messages) || candidate.systemPrompt !== previousRequest.systemPrompt || stableSerialize(candidate.tools) !== stableSerialize(previousRequest.tools)))
-            throw new ModelError("Signed continuation prefix changed", {
-              stage: "request",
-              retryable: false
-            });
+          const frozen = assertSignedContinuationStable({
+            candidate,
+            previousRequest,
+            history,
+            runId,
+            nativeBinding,
+            projectHistory: (projectedHistory) => this.context.project(projectedHistory)
+          });
           const context = this.context;
           const skills = this.skillRuntime;
           const preparation = context.prepare(history, candidate, profile, runId, reason, !frozen);
@@ -12478,6 +13022,7 @@ var AgentSession = class {
       let persistedHistoryLength = this.history.length;
       let loopCompleted = false;
       let loopFailed = false;
+      let consumerInterrupted = false;
       try {
         for await (const event of loop.run(this.history)) {
           await this.logContextEvent(event, runId);
@@ -12552,7 +13097,12 @@ var AgentSession = class {
           if (event.type === "message_stop" || event.type === "tool_messages") {
             persistedHistoryLength = this.history.length;
           }
-          yield event;
+          try {
+            yield event;
+          } catch (error) {
+            consumerInterrupted = true;
+            throw error;
+          }
         }
         loopCompleted = true;
       } catch (error) {
@@ -12569,7 +13119,7 @@ var AgentSession = class {
         }
         throw error;
       } finally {
-        if (!loopCompleted && !loopFailed) {
+        if (!loopCompleted && (!loopFailed || consumerInterrupted)) {
           await executor.rollback();
           if (this.store) {
             for (const message of this.history.slice(persistedHistoryLength)) {
@@ -12701,102 +13251,44 @@ var AgentSession = class {
   }
   /** 完整消息提交后完成技能审计；审计失败保留真实历史，停止本轮且不发布成功事件。 */
   async commitSkills(runId) {
-    if (!this.skillRuntime) return [];
-    return this.skillRuntime.commit(
-      async (source, messageId) => {
-        try {
-          await this.eventLogger.recordAudit({
-            level: "info",
-            event: "skill.loaded",
-            sessionId: this.sessionId,
-            runId,
-            fields: {
-              skillName: source.name,
-              skillScope: source.scope,
-              contentDigest: source.contentDigest,
-              renderedDigest: source.renderedDigest,
-              pathDigest: skillDigest(source.filePath),
-              caller: source.caller,
-              invocationId: source.invocationId,
-              messageId
-            }
-          });
-        } catch {
-          throw new KapibalaError("Skill commit audit unavailable", {
-            code: "AUDIT_UNAVAILABLE",
-            retryPolicy: "after_user_action",
-            safeMessage: "\u6280\u80FD\u63D0\u4EA4\u5BA1\u8BA1\u4E0D\u53EF\u7528\uFF0C\u672C\u8F6E\u505C\u6B62"
-          });
-        }
-      },
-      this.store ? "disk" : "memory"
-    );
+    return commitSkillEvents({
+      skillRuntime: this.skillRuntime,
+      eventLogger: this.eventLogger,
+      sessionId: this.sessionId,
+      runId,
+      persistence: this.store ? "disk" : "memory"
+    });
   }
   /** 显式加载仍按同一读取策略、精确缓存与宿主审批裁决；拒绝/取消/审计失败时不追加用户任务。 */
-  async authorizeSkill(name, runId, signal) {
-    const request = {
-      toolName: "load_skill",
-      capabilities: ["fs:read"],
-      input: { name },
+  authorizeSkill(name, runId, signal) {
+    return authorizeExplicitSkill({
+      name,
+      runId,
+      signal,
       rootDir: this.rootDir,
-      sessionAllowed: true
-    };
-    const cached = this.approvalCache.get(request);
-    const decision = new PermissionPolicy().decide({
-      toolName: request.toolName,
-      capabilities: request.capabilities,
       mode: this.mode,
-      rules: this.permissionRules,
-      cachedApproval: cached === "allow",
-      cachedDenial: cached === "deny"
-    });
-    let permitted = decision.decision === "allow";
-    let approvalChoice;
-    if (decision.decision === "ask") {
-      try {
-        approvalChoice = await this.approvalChannel?.requestApproval(request, signal) ?? "deny_once";
-      } catch {
-        approvalChoice = "cancel";
-      }
-      permitted = approvalChoice === "allow_once" || approvalChoice === "allow_session";
-      if (approvalChoice === "allow_session") this.approvalCache.set(request, "allow");
-      if (approvalChoice === "deny_session") this.approvalCache.set(request, "deny");
-    }
-    await this.eventLogger.recordAudit({
-      level: "info",
-      event: "skill.decided",
-      sessionId: this.sessionId,
-      runId,
-      fields: {
-        skillName: name,
-        caller: "user",
-        decision: permitted && !signal?.aborted ? "allow" : "deny",
-        decisionSource: decision.decision === "ask" ? this.approvalChannel ? "human" : "non_interactive" : decision.source,
-        approvalChoice
-      }
+      permissionRules: this.permissionRules,
+      approvalChannel: this.approvalChannel,
+      approvalCache: this.approvalCache,
+      eventLogger: this.eventLogger,
+      sessionId: this.sessionId
     });
-    if (!permitted) throw skillFailure("SKILL_INVOCATION_FORBIDDEN", "\u5BBF\u4E3B\u6743\u9650\u7981\u6B62\u663E\u5F0F\u6280\u80FD\u8BFB\u53D6");
-    signal?.throwIfAborted();
   }
   /**
    * 计算最近一次内部模型请求的上下文占用；无 usage 时显式标注预算估算。
    * run 累计 promptTokens 会重复计算每一步都重发的历史，不能用于窗口占用率。
    */
   createContextUsage(usedTokens, estimatedUsage = false) {
-    const contextWindow = resolveContextWindow(
-      (this.lastPrimaryProfile ?? this.getActiveProfile()).contextWindow
-    );
-    return {
+    return computeContextUsage(
+      this.lastPrimaryProfile ?? this.getActiveProfile(),
       usedTokens,
-      limitTokens: contextWindow.tokens,
-      percent: usedTokens === void 0 ? void 0 : usedTokens / contextWindow.tokens * 100,
-      estimatedLimit: contextWindow.estimated,
-      ...estimatedUsage ? { estimatedUsage: true } : {}
-    };
+      estimatedUsage
+    );
   }
   async persistAssistant(event) {
-    if (this.store) await this.store.append(event.message);
-    if (!event.usage) this.usageKnown = false;
+    await persistAssistantMessage(event, this.store, () => {
+      this.usageKnown = false;
+    });
   }
   /** 创建上下文协调器并注入当前路由；摘要不经过主任务 Loop，插件结果不默认为可剪裁。 */
   createContextManager() {
@@ -12815,17 +13307,8 @@ var AgentSession = class {
   }
   /** 摘要实际消耗按 attempt 身份独立累加；缺失消耗保留未知，不计入主任务指标。 */
   accountSummaryUsage(attemptId, usage) {
-    if (this.summaryAttempts.has(attemptId)) return;
-    this.summaryAttempts.add(attemptId);
-    if (!usage || ![usage.promptTokens, usage.completionTokens, usage.totalTokens].every(
-      (n) => Number.isSafeInteger(n) && n >= 0
-    )) {
-      this.summaryUsageKnown = false;
-      return;
-    }
-    this.summaryUsage.promptTokens += usage.promptTokens;
-    this.summaryUsage.completionTokens += usage.completionTokens;
-    this.summaryUsage.totalTokens += usage.totalTokens;
+    const outcome = recordSummaryUsage(attemptId, usage, this.summaryAttempts, this.summaryUsage);
+    if (outcome === "unknown") this.summaryUsageKnown = false;
   }
   /**
    * 空闲时手动摘要旧完整前缀，不创建用户任务、不执行工具，不突破当前与最近成功交互。
@@ -12898,61 +13381,21 @@ var AgentSession = class {
   }
   /** 以模型 attempt 身份幂等累加真实消耗；非法或缺失 usage 保持未知。 */
   accountUsage(attemptId, usage) {
-    if (this.accountedAttempts.has(attemptId)) return;
-    if (!usage || ![usage.promptTokens, usage.completionTokens, usage.totalTokens].every(
-      (n) => Number.isSafeInteger(n) && n >= 0
-    )) {
-      this.usageKnown = false;
-      return;
-    }
-    this.accountedAttempts.add(attemptId);
-    this.usageStats.promptTokens += usage.promptTokens;
-    this.usageStats.completionTokens += usage.completionTokens;
-    this.usageStats.totalTokens += usage.totalTokens;
+    const outcome = recordUsage(attemptId, usage, this.accountedAttempts, this.usageStats);
+    if (outcome === "unknown") this.usageKnown = false;
   }
   async persistToolMessages(messages) {
-    if (!this.store) return;
-    for (const message of messages) await this.store.append(message);
+    await persistToolMessages(messages, this.store);
   }
   /** 中止时为缓冲 assistant 的每个 tool_use 生成 OUTCOME_UNKNOWN 结果并入历史，保持事务闭合。 */
   closeInterruptedToolCalls(assistantEvent, error) {
-    const message = {
-      id: createMessageId(),
-      role: "tool",
-      content: assistantEvent.message.content.filter((block) => block.type === "tool_use").map((toolUse) => ({
-        type: "tool_result",
-        toolUseId: toolUse.id,
-        content: JSON.stringify({
-          code: "OUTCOME_UNKNOWN",
-          retryPolicy: "after_user_action",
-          message: "Tool execution was interrupted; outcome is unknown"
-        }),
-        isError: true,
-        errorCode: "OUTCOME_UNKNOWN",
-        retryPolicy: "after_user_action"
-      })),
-      timestamp: Date.now()
-    };
+    const message = buildInterruptedToolMessage(assistantEvent);
     this.history.push(message);
     return [message];
   }
   /** 收集历史中紧跟该 assistant 的连续 tool 消息；仅当覆盖全部 tool_use 时视为已闭合。 */
   findClosedToolMessages(assistantEvent) {
-    const assistantIndex = this.history.lastIndexOf(assistantEvent.message);
-    if (assistantIndex < 0) return [];
-    const expected = new Set(
-      assistantEvent.message.content.filter((block) => block.type === "tool_use").map((toolUse) => toolUse.id)
-    );
-    const messages = [];
-    for (let index2 = assistantIndex + 1; index2 < this.history.length; index2++) {
-      const message = this.history[index2];
-      if (message.role !== "tool") break;
-      messages.push(message);
-      for (const block of message.content) {
-        if (block.type === "tool_result") expected.delete(block.toolUseId);
-      }
-    }
-    return expected.size === 0 ? messages : [];
+    return findClosedToolMessages(this.history, assistantEvent);
   }
 };
 export {
@@ -13029,6 +13472,7 @@ export {
   createLogId,
   createMessageId,
   createRunCommandTool,
+  createSessionError,
   createSpawnAgentTool,
   createWaitAgentTool,
   defineTool,
@@ -13084,7 +13528,6 @@ export {
   sanitizeModelErrorMessage,
   sanitizeSessionTitle,
   scanSkillRoot,
-  sharedWorkspaceLeaseCoordinator,
   skillDigest,
   skillFailure,
   skillPathKey,