@agentdevjs/core 0.1.0 → 0.1.1

package/dist/index.js

@@ -1,9 +1,9 @@
 import {
   ExplorerAgent
-} from "./chunk-UCEIJEM5.js";
+} from "./chunk-V3WM6EII.js";
 import {
   BasicAgent
-} from "./chunk-TIJV6GJW.js";
+} from "./chunk-YYNP7MZC.js";
 import {
   AgentBase,
   CapabilityRegistry,
@@ -54,11 +54,11 @@ import {
   withDeadline,
   withDisplay,
   withImages
-} from "./chunk-YFSM6IYU.js";
+} from "./chunk-TKVOWEJ2.js";
 import {
   emitSessionEvent,
   subscribeSessionEvents
-} from "./chunk-KO4DJKM6.js";
+} from "./chunk-OFBE43IS.js";
 import {
   DebugHub,
   createLLMCharCount,
@@ -70,10 +70,10 @@ import {
   getDebugCapabilities,
   getDefaultUDSPath,
   resolveDebugTransportMode
-} from "./chunk-574NG4UB.js";
+} from "./chunk-U3LWOJ3Q.js";
 import {
   PlaceholderResolver
-} from "./chunk-BVF7RUXV.js";
+} from "./chunk-KCCLSQC4.js";
 import "./chunk-DGUM43GV.js";
 
 // src/features/skill/index.ts
@@ -1225,7 +1225,7 @@ var TodoToolFactory = class {
       },
       render: { call: "task-create", result: "task-create" },
       execute: ({ subject, description = "" }) => {
-        const task = self.createTaskFn(subject, description);
+        const task = self.createTaskFn(String(subject), String(description));
         return Promise.resolve(withDisplay(
           JSON.stringify({ ok: true, taskId: task.id, status: task.status }),
           {
@@ -1321,8 +1321,9 @@ var TodoToolFactory = class {
         required: ["taskId"]
       },
       render: { call: "task-update", result: "task-update" },
-      execute: ({ taskId, ...updates }) => {
-        const task = self.updateTaskFn(taskId, updates);
+      execute: (rawArgs) => {
+        const { taskId, ...rest } = rawArgs;
+        const task = self.updateTaskFn(taskId, rest);
         if (!task) {
           return Promise.resolve({ ok: false, error: `\u4EFB\u52A1 ${taskId} \u4E0D\u5B58\u5728` });
         }
@@ -1449,7 +1450,7 @@ var TodoFeature = class {
       try {
         this.reminderContent = await readFile3(templatePath, "utf-8");
         console.log("[TodoFeature] Loaded reminder template from: " + templatePath);
-      } catch (e) {
+      } catch {
         console.log("[TodoFeature] Failed to load template, using default reminder");
       }
     }
@@ -2026,18 +2027,18 @@ import {
   stat,
   unlink
 } from "fs/promises";
-import { dirname as dirname6, isAbsolute, join as join4, relative } from "path";
+import { dirname as dirname6, isAbsolute, join as join2, relative } from "path";
 import { homedir } from "os";
 var MAX_SNAPSHOTS = 100;
 function getBackupDir(sessionId) {
-  return join4(homedir(), ".agentdev", "file-history", sessionId);
+  return join2(homedir(), ".agentdev", "file-history", sessionId);
 }
 function getBackupFileName(filePath, version) {
   const hash = createHash("sha256").update(filePath).digest("hex").slice(0, 16);
   return `${hash}@v${version}`;
 }
 function resolveBackupPath(backupFileName, sessionId) {
-  return join4(getBackupDir(sessionId), backupFileName);
+  return join2(getBackupDir(sessionId), backupFileName);
 }
 function toTrackingPath(filePath, workspaceDir) {
   if (!isAbsolute(filePath)) return filePath;
@@ -2048,7 +2049,7 @@ function toTrackingPath(filePath, workspaceDir) {
 }
 function toAbsolutePath(trackingPath, workspaceDir) {
   if (isAbsolute(trackingPath)) return trackingPath;
-  return join4(workspaceDir, trackingPath);
+  return join2(workspaceDir, trackingPath);
 }
 async function createBackup(filePath, version, sessionId) {
   const backupFileName = getBackupFileName(filePath, version);
@@ -2158,9 +2159,8 @@ async function makeSnapshot(state) {
         const absolutePath = toAbsolutePath(trackingPath, state.workspaceDir);
         const lastBackup = latestSnapshot.trackedFileBackups[trackingPath];
         const nextVersion = lastBackup ? lastBackup.version + 1 : 1;
-        let fileStats;
         try {
-          fileStats = await stat(absolutePath);
+          await stat(absolutePath);
         } catch (e) {
           if (e.code === "ENOENT") {
             newBackups[trackingPath] = { backupFileName: null, version: nextVersion };
@@ -2475,7 +2475,7 @@ var FileHistoryFeature = class {
 // src/features/handoff-seed/index.ts
 import { fileURLToPath as fileURLToPath7 } from "url";
 import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
-import { join as join5, resolve, normalize as normalize3 } from "path";
+import { join as join3, resolve, normalize as normalize3 } from "path";
 var __filename4 = fileURLToPath7(import.meta.url);
 var MAX_FILE_CHARS = 8e3;
 var MAX_TOTAL_FILE_CHARS = 3e4;
@@ -2692,8 +2692,8 @@ var HandoffSeedFeature = class {
     const nameOnlyList = [];
     let totalChars = 0;
     for (const skillName of skills) {
-      const skillDir = join5(projectRoot, ".agentdev", "skills", skillName);
-      const skillMdPath = join5(skillDir, "SKILL.md");
+      const skillDir = join3(projectRoot, ".agentdev", "skills", skillName);
+      const skillMdPath = join3(skillDir, "SKILL.md");
       const content = this.tryReadFile(skillMdPath);
       const basePath = normalize3(skillDir);
       if (content === null) {
@@ -2762,8 +2762,8 @@ import { fileURLToPath as fileURLToPath8 } from "url";
 import { promises as fs } from "fs";
 
 // src/features/opencode-basic/tools.ts
-import { readFile as readFile5, writeFile, readdir, stat as stat2, mkdir as mkdir2 } from "fs/promises";
-import { glob } from "glob";
+import { open, readFile as readFile5, writeFile, opendir, stat as stat2, mkdir as mkdir2 } from "fs/promises";
+import { globIterate } from "glob";
 import { spawn } from "child_process";
 import { createTwoFilesPatch, diffLines } from "diff";
 import path from "path";
@@ -2771,7 +2771,6 @@ import { homedir as homedir2 } from "os";
 var DEFAULT_READ_LIMIT = 2e3;
 var MAX_LINE_LENGTH = 2e3;
 var MAX_BYTES = 50 * 1024;
-var LS_LIMIT = 100;
 var SEARCH_LIMIT = 100;
 var DEFAULT_WORKSPACE_DIR = process.cwd();
 var IGNORE_PATTERNS = [
@@ -2911,20 +2910,51 @@ function writeTextContent(filePath, content, encoding = "utf8", lineEndings = "L
   }
   return writeFile(filePath, toWrite, encoding);
 }
-var CURLY_QUOTES = [
+var EQUIVALENT_CHARS = /* @__PURE__ */ new Map([
   ["\u2018", "'"],
-  // LEFT SINGLE
+  // LEFT SINGLE QUOTATION MARK
   ["\u2019", "'"],
-  // RIGHT SINGLE
+  // RIGHT SINGLE QUOTATION MARK
   ["\u201C", '"'],
-  // LEFT DOUBLE
-  ["\u201D", '"']
-  // RIGHT DOUBLE
-];
-function normalizeQuotes(str) {
-  let result = str;
-  for (const [curly, straight] of CURLY_QUOTES) {
-    result = result.replaceAll(curly, straight);
+  // LEFT DOUBLE QUOTATION MARK
+  ["\u201D", '"'],
+  // RIGHT DOUBLE QUOTATION MARK
+  ["\xA0", " "],
+  // NO-BREAK SPACE
+  ["\u1680", " "],
+  // OGHAM SPACE MARK
+  ["\u2002", " "],
+  // EN QUAD
+  ["\u2003", " "],
+  // EM QUAD
+  ["\u2004", " "],
+  // THREE-PER-EM SPACE
+  ["\u2005", " "],
+  // FOUR-PER-EM SPACE
+  ["\u2006", " "],
+  // SIX-PER-EM SPACE
+  ["\u2007", " "],
+  // FIGURE SPACE
+  ["\u2008", " "],
+  // PUNCTUATION SPACE
+  ["\u2009", " "],
+  // THIN SPACE
+  ["\u200A", " "],
+  // HAIR SPACE
+  ["\u202F", " "],
+  // NARROW NO-BREAK SPACE
+  ["\u205F", " "],
+  // MEDIUM MATHEMATICAL SPACE
+  ["\u3000", " "]
+  // IDEOGRAPHIC SPACE（全角空格）
+]);
+var INVISIBLE_CHARS = /* @__PURE__ */ new Set(["\u200B", "\u200C", "\u200D", "\uFEFF"]);
+var SPECIAL_CHARS_RE = /[\u00A0\u1680\u2002-\u200A\u200B-\u200D\u2018\u2019\u201C\u201D\u202F\u205F\u3000\uFEFF]/;
+function normalizeForMatch(str) {
+  let result = "";
+  for (const ch of str) {
+    if (INVISIBLE_CHARS.has(ch)) continue;
+    result += EQUIVALENT_CHARS.get(ch) ?? ch;
   }
   return result;
 }
@@ -2932,13 +2962,28 @@ function findActualString(fileContent, searchString) {
   if (fileContent.includes(searchString)) {
     return searchString;
   }
-  const normalizedSearch = normalizeQuotes(searchString);
-  const normalizedFile = normalizeQuotes(fileContent);
+  if (!SPECIAL_CHARS_RE.test(fileContent) && !SPECIAL_CHARS_RE.test(searchString)) {
+    return null;
+  }
+  let normalizedFile = "";
+  const sourceIndex = [];
+  for (let i = 0; i < fileContent.length; i++) {
+    const ch = fileContent[i];
+    if (INVISIBLE_CHARS.has(ch)) continue;
+    normalizedFile += EQUIVALENT_CHARS.get(ch) ?? ch;
+    sourceIndex.push(i);
+  }
+  const normalizedSearch = normalizeForMatch(searchString);
+  if (!normalizedSearch) {
+    return null;
+  }
   const index = normalizedFile.indexOf(normalizedSearch);
-  if (index !== -1) {
-    return fileContent.substring(index, index + searchString.length);
+  if (index === -1) {
+    return null;
   }
-  return null;
+  const start = sourceIndex[index];
+  const end = sourceIndex[index + normalizedSearch.length - 1] + 1;
+  return fileContent.substring(start, end);
 }
 async function isBinaryFile(filepath) {
   const ext = path.extname(filepath).toLowerCase();
@@ -2975,21 +3020,25 @@ async function isBinaryFile(filepath) {
   if (binaryExts.includes(ext)) {
     return true;
   }
+  let handle;
   try {
-    const content = await readFile5(filepath, { encoding: null });
-    if (content.length === 0) return false;
-    const bufferSize = Math.min(4096, content.length);
-    const bytes = content.subarray(0, bufferSize);
+    handle = await open(filepath, "r");
+    const buffer = Buffer.allocUnsafe(4096);
+    const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+    if (bytesRead === 0) return false;
     let nonPrintableCount = 0;
-    for (let i = 0; i < bytes.length; i++) {
-      if (bytes[i] === 0) return true;
-      if (bytes[i] < 9 || bytes[i] > 13 && bytes[i] < 32) {
-        nonPrintableCount++;
+    for (let i = 0; i < bytesRead; i += 1) {
+      if (buffer[i] === 0) return true;
+      if (buffer[i] < 9 || buffer[i] > 13 && buffer[i] < 32) {
+        nonPrintableCount += 1;
       }
     }
-    return nonPrintableCount / bytes.length > 0.3;
+    return nonPrintableCount / bytesRead > 0.3;
   } catch {
     return false;
+  } finally {
+    await handle?.close().catch(() => {
+    });
   }
 }
 function createReadTool(workspaceDir = DEFAULT_WORKSPACE_DIR) {
@@ -3022,7 +3071,6 @@ function createReadTool(workspaceDir = DEFAULT_WORKSPACE_DIR) {
       const offsetParam = typeof args.offset === "number" ? args.offset : void 0;
       const limitParam = typeof args.limit === "number" ? args.limit : void 0;
       const resolvedFilePath = resolveWorkspacePath(filePath, workspaceDir);
-      console.log(`[read] ${resolvedFilePath}`);
       if (offsetParam !== void 0 && offsetParam < 1) {
         throw new Error("offset must be greater than or equal to 1");
       }
@@ -3034,36 +3082,53 @@ function createReadTool(workspaceDir = DEFAULT_WORKSPACE_DIR) {
         throw new Error(`File not found: ${resolvedFilePath}`);
       }
       if (stats.isDirectory()) {
-        const dirents = await readdir(resolvedFilePath, { withFileTypes: true });
+        const limit2 = limitParam ?? DEFAULT_READ_LIMIT;
+        const offset2 = offsetParam ?? 1;
+        const start2 = offset2 - 1;
+        const end = start2 + limit2;
+        const candidates = [];
+        let totalEntries = 0;
+        const directory = await opendir(resolvedFilePath);
+        try {
+          for await (const dirent of directory) {
+            totalEntries += 1;
+            candidates.push({
+              name: dirent.name,
+              isDirectory: dirent.isDirectory(),
+              isSymbolicLink: dirent.isSymbolicLink()
+            });
+            candidates.sort((left, right) => left.name.localeCompare(right.name));
+            if (candidates.length > end) candidates.pop();
+          }
+        } finally {
+          await directory.close().catch(() => {
+          });
+        }
+        const visibleCandidates = candidates.slice(start2, end);
         const entries = [];
-        for (const dirent of dirents) {
-          if (dirent.isDirectory()) {
-            entries.push(dirent.name + path.sep);
-          } else if (dirent.isSymbolicLink()) {
+        for (const candidate of visibleCandidates) {
+          if (candidate.isDirectory) {
+            entries.push(candidate.name + path.sep);
+          } else if (candidate.isSymbolicLink) {
             try {
-              const targetStats = await stat2(path.join(resolvedFilePath, dirent.name));
-              entries.push(targetStats.isDirectory() ? dirent.name + path.sep : dirent.name);
+              const targetStats = await stat2(path.join(resolvedFilePath, candidate.name));
+              entries.push(targetStats.isDirectory() ? candidate.name + path.sep : candidate.name);
             } catch {
-              entries.push(dirent.name);
+              entries.push(candidate.name);
             }
           } else {
-            entries.push(dirent.name);
+            entries.push(candidate.name);
           }
         }
-        entries.sort((a, b) => a.localeCompare(b));
-        const limit2 = limitParam ?? DEFAULT_READ_LIMIT;
-        const offset2 = offsetParam ?? 1;
-        const start2 = offset2 - 1;
-        const sliced = entries.slice(start2, start2 + limit2);
-        const truncated2 = start2 + sliced.length < entries.length;
+        const truncated2 = totalEntries > end;
         return {
           type: "directory",
           path: resolvedFilePath,
-          totalEntries: entries.length,
+          totalEntries,
           offset: offset2,
           limit: limit2,
           truncated: truncated2,
-          entries: sliced
+          entries
         };
       }
       const isBinary = await isBinaryFile(resolvedFilePath);
@@ -3142,7 +3207,6 @@ function createWriteTool(workspaceDir = DEFAULT_WORKSPACE_DIR) {
       const filePath = normalizeNamedPathArg(args, "filePath", "filepath", "path");
       const content = args.content;
       const resolvedFilePath = resolveWorkspacePath(filePath, workspaceDir);
-      console.log(`[write] ${resolvedFilePath}`);
       let encoding = "utf8";
       const exists = await stat2(resolvedFilePath).then(() => true).catch(() => false);
       let contentOld = "";
@@ -3556,7 +3620,6 @@ function createEditTool(workspaceDir = DEFAULT_WORKSPACE_DIR) {
       const newString = args.newString;
       const replaceAll = args.replaceAll;
       const resolvedFilePath = resolveWorkspacePath(filePath, workspaceDir);
-      console.log(`[edit] ${resolvedFilePath}`);
       if (oldString === newString) {
         throw new Error("No changes to apply: oldString and newString are identical.");
       }
@@ -3629,10 +3692,122 @@ function createEditTool(workspaceDir = DEFAULT_WORKSPACE_DIR) {
   });
 }
 var editTool = createEditTool();
+var LS_MAX_DEPTH = 2;
+var LS_ROOT_LIMIT = 100;
+var LS_CHILD_LIMIT = 12;
+function compileIgnorePattern(pattern) {
+  let normalized = pattern.trim().replaceAll("\\", "/").replace(/^\.\//, "");
+  if (!normalized) return null;
+  if (normalized.endsWith("/**")) {
+    normalized = normalized.slice(0, -3).replace(/\/$/, "");
+    if (!normalized) return null;
+    return new RegExp(`^(?:${globPatternToRegexSource(normalized)})(?:/.*)?$`);
+  }
+  if (!/[?*[]/.test(normalized)) {
+    return new RegExp(`^(?:${globPatternToRegexSource(normalized)})(?:/.*)?$`);
+  }
+  return new RegExp(`^${globPatternToRegexSource(normalized)}$`);
+}
+function globPatternToRegexSource(pattern) {
+  let source = "";
+  for (let index = 0; index < pattern.length; index += 1) {
+    const char = pattern[index];
+    if (char === "*") {
+      if (pattern[index + 1] === "*") {
+        source += ".*";
+        index += 1;
+      } else {
+        source += "[^/]*";
+      }
+    } else if (char === "?") {
+      source += "[^/]";
+    } else {
+      source += char.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    }
+  }
+  return source;
+}
+function shouldIgnoreDirectoryEntry(relativePath, patterns) {
+  return patterns.some((pattern) => pattern.test(relativePath));
+}
+async function buildLimitedDirectoryTree(rootPath, ignorePatterns, maxDepth = LS_MAX_DEPTH, rootLimit = LS_ROOT_LIMIT, childLimit = LS_CHILD_LIMIT) {
+  const compiledPatterns = ignorePatterns.map(compileIgnorePattern).filter((pattern) => pattern !== null);
+  let fileCount = 0;
+  let truncated = false;
+  const visit = async (absolutePath, relativePath, depth) => {
+    const limit = depth === 0 ? rootLimit : childLimit;
+    const entries = [];
+    let droppedCount = 0;
+    const directory = await opendir(absolutePath).catch(() => null);
+    if (directory === null) return entries;
+    const compareEntries = (left, right) => {
+      if (left.isDirectory !== right.isDirectory) return left.isDirectory ? -1 : 1;
+      return left.name.localeCompare(right.name);
+    };
+    try {
+      for await (const dirent of directory) {
+        const childRelativePath = relativePath ? `${relativePath}/${dirent.name}` : dirent.name;
+        if (shouldIgnoreDirectoryEntry(childRelativePath, compiledPatterns)) continue;
+        const entry = {
+          name: dirent.name,
+          relativePath: childRelativePath,
+          isDirectory: dirent.isDirectory(),
+          children: [],
+          droppedCount: 0
+        };
+        const insertAt = entries.findIndex((existing) => compareEntries(entry, existing) < 0);
+        if (insertAt === -1) entries.push(entry);
+        else entries.splice(insertAt, 0, entry);
+        if (entries.length > limit) {
+          entries.pop();
+          droppedCount += 1;
+        }
+      }
+    } finally {
+      await directory.close().catch(() => {
+      });
+    }
+    if (droppedCount > 0) {
+      truncated = true;
+      if (entries.length > 0) entries[entries.length - 1].droppedCount = droppedCount;
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory) {
+        fileCount += 1;
+        continue;
+      }
+      if (depth >= maxDepth) continue;
+      entry.children = await visit(path.join(rootPath, entry.relativePath), entry.relativePath, depth + 1);
+    }
+    return entries;
+  };
+  const root = {
+    name: ".",
+    relativePath: "",
+    isDirectory: true,
+    children: await visit(rootPath, "", 0),
+    droppedCount: 0
+  };
+  return { root, fileCount, truncated };
+}
+function renderLimitedDirectoryTree(root, rootPath) {
+  const lines = [`${rootPath}${path.sep}`];
+  const render = (entry, depth) => {
+    const indent = "  ".repeat(depth);
+    lines.push(`${indent}${entry.name}${entry.isDirectory ? "/" : ""}`);
+    if (entry.droppedCount > 0) {
+      lines.push(`${"  ".repeat(depth + 1)}\u2026 ${entry.droppedCount} more`);
+    }
+    for (const child of entry.children) render(child, depth + 1);
+  };
+  for (const entry of root.children) render(entry, 0);
+  return `${lines.join("\n")}
+`;
+}
 function createLsTool(workspaceDir = DEFAULT_WORKSPACE_DIR) {
   return createTool({
     name: "ls",
-    description: "List files in a directory with tree structure output. Automatically ignores common build/cache directories.",
+    description: "List a bounded directory tree. It shows up to two levels, ignores common build/cache directories, and truncates large directories per level.",
     render: "ls",
     parallelizable: true,
     parameters: {
@@ -3653,61 +3828,21 @@ function createLsTool(workspaceDir = DEFAULT_WORKSPACE_DIR) {
     },
     execute: async (args = {}) => {
       const dirPath = normalizeNamedPathArg(args, "dirPath", "dirpath", "path", "filePath", "filepath");
-      const ignore = args.ignore ?? [];
+      const rawIgnore = args.ignore;
+      const ignore = Array.isArray(rawIgnore) ? rawIgnore.filter((item) => typeof item === "string") : [];
       const resolvedDirPath = resolveWorkspacePath(dirPath, workspaceDir);
-      console.log(`[ls] ${resolvedDirPath}`);
-      const ignoreGlobs = [...IGNORE_PATTERNS, ...ignore.map((p) => `${p}/**`)];
-      const matches = await glob("**/*", {
-        cwd: resolvedDirPath,
-        absolute: false,
-        dot: true,
-        ignore: ignoreGlobs,
-        nodir: true
-      });
-      const files = [];
-      for (const file of matches) {
-        files.push(file);
-        if (files.length >= LS_LIMIT) break;
-      }
-      const dirs = /* @__PURE__ */ new Set();
-      const filesByDir = /* @__PURE__ */ new Map();
-      for (const file of files) {
-        const dir = path.dirname(file);
-        const parts = dir === "." ? [] : dir.split(path.sep);
-        for (let i = 0; i <= parts.length; i++) {
-          const dirPath2 = i === 0 ? "." : parts.slice(0, i).join(path.sep);
-          dirs.add(dirPath2);
-        }
-        if (!filesByDir.has(dir)) {
-          filesByDir.set(dir, []);
-        }
-        filesByDir.get(dir).push(path.basename(file));
-      }
-      function renderDir(dirPath2, depth) {
-        const indent = "  ".repeat(depth);
-        let output = "";
-        if (depth > 0) {
-          output += `${indent}${path.basename(dirPath2)}/
-`;
-        }
-        const children = Array.from(dirs).filter((d) => path.dirname(d) === dirPath2 && d !== dirPath2).sort();
-        for (const child of children) {
-          output += renderDir(child, depth + 1);
-        }
-        const dirFiles = filesByDir.get(dirPath2) || [];
-        for (const file of dirFiles.sort()) {
-          output += `${"  ".repeat(depth + 1)}${file}
-`;
-        }
-        return output;
-      }
-      const treeOutput = `${resolvedDirPath}${path.sep}
-${renderDir(".", 0)}`;
+      const stats = await stat2(resolvedDirPath).catch(() => null);
+      if (!stats) throw new Error(`Directory not found: ${resolvedDirPath}`);
+      if (!stats.isDirectory()) throw new Error(`Path is not a directory: ${resolvedDirPath}`);
+      const result = await buildLimitedDirectoryTree(
+        resolvedDirPath,
+        [...IGNORE_PATTERNS, ...ignore.map((pattern) => pattern.endsWith("/**") ? pattern : `${pattern}/**`)]
+      );
       return {
         path: resolvedDirPath,
-        count: files.length,
-        truncated: files.length >= LS_LIMIT,
-        tree: treeOutput
+        count: result.fileCount,
+        truncated: result.truncated,
+        tree: renderLimitedDirectoryTree(result.root, resolvedDirPath)
       };
     }
   });
@@ -3738,30 +3873,30 @@ function createGlobTool(workspaceDir = DEFAULT_WORKSPACE_DIR) {
       const pattern = args.pattern;
       const searchPath = tryNamedPathArg(args, "searchPath", "searchpath", "path", "filePath", "filepath");
       const resolvedSearchPath = resolveWorkspaceSearchPath(searchPath, workspaceDir);
-      console.log(`[glob] ${pattern} in ${resolvedSearchPath}`);
       const files = [];
-      const matches = await glob(pattern, {
+      let truncated = false;
+      for await (const file of globIterate(pattern, {
         cwd: resolvedSearchPath,
         absolute: true,
         windowsPathsNoEscape: true,
-        nodir: true
-      });
-      for (const file of matches) {
-        if (files.length >= SEARCH_LIMIT) break;
+        nodir: true,
+        ignore: IGNORE_PATTERNS
+      })) {
+        if (files.length >= SEARCH_LIMIT) {
+          truncated = true;
+          break;
+        }
         try {
           const stats = await stat2(file);
-          files.push({
-            path: file,
-            mtime: stats.mtimeMs
-          });
+          files.push({ path: file, mtime: stats.mtimeMs });
         } catch {
         }
       }
-      files.sort((a, b) => b.mtime - a.mtime);
+      files.sort((a, b) => b.mtime - a.mtime || a.path.localeCompare(b.path));
       return {
         count: files.length,
-        truncated: files.length >= SEARCH_LIMIT,
-        files: files.map((f) => f.path)
+        truncated,
+        files: files.map((file) => file.path)
       };
     }
   });
@@ -3819,7 +3954,6 @@ function createGrepTool(workspaceDir = DEFAULT_WORKSPACE_DIR) {
       const searchPath = tryNamedPathArg(args, "searchPath", "searchpath", "path", "filePath", "filepath");
       const include = args.include;
       const resolvedSearchPath = resolveWorkspaceSearchPath(searchPath, workspaceDir);
-      console.log(`[grep] ${pattern} in ${resolvedSearchPath}`);
       const rgPath = await getRipgrepPath();
       const rgArgs = ["-nH", "--hidden", "--no-messages", "--field-match-separator=|", "--regexp", pattern];
       if (include) {
@@ -3827,18 +3961,54 @@ function createGrepTool(workspaceDir = DEFAULT_WORKSPACE_DIR) {
       }
       rgArgs.push(resolvedSearchPath);
       try {
-        const stdout = await new Promise((resolve3, reject) => {
-          const chunks = [];
-          const child = spawn(rgPath, rgArgs, {
-            windowsHide: true
-          });
-          child.stdout.on("data", (chunk) => chunks.push(chunk));
-          child.stderr.on("data", (chunk) => {
-          });
-          const onSearchAbort = () => child.kill();
+        const { matches, truncated } = await new Promise((resolve3, reject) => {
+          const child = spawn(rgPath, rgArgs, { windowsHide: true });
+          const collected = [];
+          let pending = "";
+          let truncated2 = false;
+          let killRequested = false;
+          const stopSearch = () => {
+            if (killRequested) return;
+            killRequested = true;
+            child.kill();
+          };
+          const processLine = (line) => {
+            if (!line || truncated2) return;
+            const parts = line.split("|");
+            if (parts.length < 3) return;
+            const [filePath, lineNumStr, ...lineTextParts] = parts;
+            const lineNum = parseInt(lineNumStr, 10);
+            if (!filePath || !Number.isFinite(lineNum)) return;
+            const lineText = lineTextParts.join("|");
+            if (collected.length >= SEARCH_LIMIT) {
+              truncated2 = true;
+              stopSearch();
+              return;
+            }
+            collected.push({
+              path: filePath,
+              lineNum,
+              lineText: lineText.length > MAX_LINE_LENGTH ? `${lineText.substring(0, MAX_LINE_LENGTH)}...` : lineText
+            });
+          };
+          const onSearchAbort = () => {
+            stopSearch();
+          };
           if (context?.signal) {
             context.signal.addEventListener("abort", onSearchAbort, { once: true });
           }
+          child.stdout.setEncoding("utf8");
+          child.stdout.on("data", (chunk) => {
+            pending += chunk;
+            let newlineIndex = pending.indexOf(String.fromCharCode(10));
+            while (newlineIndex !== -1) {
+              processLine(pending.slice(0, newlineIndex).replace(new RegExp(String.fromCharCode(13) + "$"), ""));
+              pending = pending.slice(newlineIndex + 1);
+              if (killRequested) return;
+              newlineIndex = pending.indexOf(String.fromCharCode(10));
+            }
+          });
+          child.stderr.resume();
           child.on("error", (err) => {
             context?.signal?.removeEventListener("abort", onSearchAbort);
             reject(err);
@@ -3846,41 +4016,29 @@ function createGrepTool(workspaceDir = DEFAULT_WORKSPACE_DIR) {
           child.on("close", (code) => {
             context?.signal?.removeEventListener("abort", onSearchAbort);
             if (context?.signal?.aborted) {
-              return reject(new Error("Search was aborted"));
+              reject(new Error("Search was aborted"));
+              return;
+            }
+            if (!killRequested) {
+              processLine(pending);
             }
-            if (code !== 0 && code !== 1) {
-              return reject(new Error(`rg exited with code ${code}`));
+            if (!killRequested && code !== 0 && code !== 1) {
+              reject(new Error(`rg exited with code ${code}`));
+              return;
             }
-            resolve3(Buffer.concat(chunks).toString("utf-8"));
+            resolve3({ matches: collected, truncated: truncated2 });
           });
         });
-        const lines = stdout.trim().split(/\r?\n/);
-        const matches = [];
-        for (const line of lines) {
-          if (!line) continue;
-          const parts = line.split("|");
-          if (parts.length < 3) continue;
-          const [filePath, lineNumStr, ...lineTextParts] = parts;
-          const lineNum = parseInt(lineNumStr, 10);
-          const lineText = lineTextParts.join("|");
-          matches.push({
-            path: filePath,
-            lineNum,
-            lineText: lineText.length > MAX_LINE_LENGTH ? lineText.substring(0, MAX_LINE_LENGTH) + "..." : lineText
-          });
-        }
         matches.sort((a, b) => a.path === b.path ? a.lineNum - b.lineNum : a.path < b.path ? -1 : 1);
-        const truncated = matches.length > SEARCH_LIMIT;
-        const finalMatches = truncated ? matches.slice(0, SEARCH_LIMIT) : matches;
         return {
           pattern,
           matches: matches.length,
           truncated,
-          results: finalMatches
+          results: matches
         };
       } catch (error) {
         if (error.message?.includes("Search was aborted") || context?.signal?.aborted) {
-          throw new Error("Search was aborted");
+          throw new Error("Search was aborted", { cause: error });
         }
         throw error;
       }
@@ -4214,7 +4372,7 @@ var ExampleFeature = class {
     }
     return "continue" /* Continue */;
   }
-  async handleStepFinish(ctx) {
+  async handleStepFinish(_ctx) {
     return "continue" /* Continue */;
   }
 };
@@ -5008,6 +5166,7 @@ var LspFeature = class {
   broken = /* @__PURE__ */ new Set();
   constructor(config = {}) {
     this.config = {
+      // eslint-disable-next-line no-restricted-syntax -- 防御性默认值，onInitiate 会用 ctx.config.workspaceDir 覆盖
       workdir: config.workdir || process.cwd(),
       binDir: config.binDir || path4.join(os.homedir(), ".agentdev", "lsp-bin"),
       disableDownload: config.disableDownload ?? false,
@@ -5309,7 +5468,7 @@ var LspFeature = class {
 
 // src/features/output-guard/index.ts
 import { fileURLToPath as fileURLToPath12 } from "url";
-import { dirname as dirname8, join as join7 } from "path";
+import { dirname as dirname8, join as join4 } from "path";
 import { mkdir as mkdir3, writeFile as writeFile2 } from "fs/promises";
 
 // src/features/output-guard/truncate.ts
@@ -5525,6 +5684,7 @@ var OutputGuardFeature = class {
     this.config = {
       hardLimit: config.hardLimit ?? DEFAULT_HARD_LIMIT,
       fieldLimit: config.fieldLimit ?? DEFAULT_FIELD_LIMIT,
+      // eslint-disable-next-line no-restricted-syntax -- 防御性默认值，仅用于临时文件落盘目录；宿主应显式传 workdir
       workdir: config.workdir ?? process.cwd(),
       toolOverrides: config.toolOverrides ?? {}
     };
@@ -5616,13 +5776,13 @@ var OutputGuardFeature = class {
     let filePath;
     let diskContent = fullOutput;
     try {
-      const tempDir = join7(this.config.workdir, ".agentdev", "temp");
+      const tempDir = join4(this.config.workdir, ".agentdev", "temp");
       const now = /* @__PURE__ */ new Date();
       const ts = now.getFullYear().toString() + String(now.getMonth() + 1).padStart(2, "0") + String(now.getDate()).padStart(2, "0") + "-" + String(now.getHours()).padStart(2, "0") + String(now.getMinutes()).padStart(2, "0") + String(now.getSeconds()).padStart(2, "0");
       const suffix = Math.random().toString(36).slice(2, 8);
       const safeToolName = toolName.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 30);
       const fileName = `tool-output-${safeToolName}-${ts}-${suffix}.log`;
-      filePath = join7(tempDir, fileName);
+      filePath = join4(tempDir, fileName);
       try {
         const parsed = JSON.parse(fullOutput);
         diskContent = JSON.stringify(parsed, null, 2);
@@ -5661,9 +5821,9 @@ Use the read tool with offset/limit to access specific portions.
 };
 
 // src/core/config.ts
-import { readFile as readFile7, readdir as readdir2 } from "fs/promises";
+import { readFile as readFile7, readdir } from "fs/promises";
 import { readFileSync as readFileSync3, existsSync as existsSync3 } from "fs";
-import { resolve as resolve2, join as join8 } from "path";
+import { resolve as resolve2, join as join5 } from "path";
 import { cwd } from "process";
 var OPENAI_THINKING_EFFORTS = [
   "none",
@@ -5686,7 +5846,7 @@ function getProjectRoot() {
 }
 async function loadConfig(name = "default") {
   const projectRoot = getProjectRoot();
-  const configDir = join8(projectRoot, "config");
+  const configDir = join5(projectRoot, "config");
   const configPath = resolve2(configDir, `${name}.json`);
   if (!existsSync3(configPath)) {
     throw new Error(
@@ -5701,7 +5861,7 @@ async function loadConfig(name = "default") {
 }
 function loadConfigSync(name = "default") {
   const projectRoot = getProjectRoot();
-  const configDir = join8(projectRoot, "config");
+  const configDir = join5(projectRoot, "config");
   const configPath = resolve2(configDir, `${name}.json`);
   if (!existsSync3(configPath)) {
     throw new Error(
@@ -5716,9 +5876,9 @@ function loadConfigSync(name = "default") {
 }
 async function listConfigs() {
   const projectRoot = getProjectRoot();
-  const configDir = join8(projectRoot, "config");
+  const configDir = join5(projectRoot, "config");
   try {
-    const files = await readdir2(configDir);
+    const files = await readdir(configDir);
     return files.filter((f) => f.endsWith(".json")).map((f) => f.replace(".json", ""));
   } catch {
     return [];
@@ -5820,7 +5980,7 @@ var RENDER_TEMPLATES = {
   },
   "file-write": {
     call: '<div class="bash-command">Write <span class="file-path">{{path}}</span></div>',
-    result: (data) => `<div style="color:var(--success-color)">\u2713 File written successfully</div>`
+    result: (_data) => `<div style="color:var(--success-color)">\u2713 File written successfully</div>`
   },
   "file-list": {
     call: '<div class="bash-command">List <span class="file-path">{{path}}</span></div>',
@@ -5926,7 +6086,6 @@ var RENDER_TEMPLATES = {
     call: '<div class="bash-command">List trash</div>',
     result: (data) => {
       const total = data.total || 0;
-      const files = data.files || [];
       if (total === 0) {
         return `<div style="color:var(--text-secondary)">Trash is empty</div>`;
       }
@@ -6974,7 +7133,7 @@ function declareContinuity(Base, descriptor) {
 
 // src/core/workthread/store.ts
 import { copyFile as copyFile2, mkdir as mkdir4, readFile as readFile8, rename, unlink as unlink2, writeFile as writeFile3 } from "fs/promises";
-import { join as join9 } from "path";
+import { join as join6 } from "path";
 import { randomUUID as randomUUID2 } from "crypto";
 var WorkThreadNotFoundError = class extends Error {
   code = "workthread_not_found";
@@ -7030,12 +7189,12 @@ var WorkThreadStore = class {
       throw new Error("WorkThreadStore requires a rootDir");
     }
     this.rootDir = rootDir;
-    this.threadsDir = join9(rootDir, "threads");
-    this.indexPath = join9(rootDir, "index.json");
+    this.threadsDir = join6(rootDir, "threads");
+    this.indexPath = join6(rootDir, "index.json");
   }
   // ── 路径 ──────────────────────────────────────────────────────────
   threadFilePath(threadId) {
-    return join9(this.threadsDir, `${sanitizeWorkThreadFragment(threadId)}.json`);
+    return join6(this.threadsDir, `${sanitizeWorkThreadFragment(threadId)}.json`);
   }
   // ── 原子写（对齐 FileSessionStore 模式，兼容 Windows EPERM/EXDEV）─
   async atomicWriteJson(filePath, data) {
@@ -7203,6 +7362,54 @@ var WorkThreadStore = class {
       if (this._threadLocks.get(threadId) === next) this._threadLocks.delete(threadId);
     }
   }
+  /**
+   * 删除线程记录文件与 index 条目（破坏性生命周期操作的存储原语）。
+   *
+   * 幂等：记录不存在时返回 { removed: false, alreadyAbsent: true }——
+   * 已删除对象视为删除成功，供宿主的级联删除重试收敛。
+   * 走与 create / update 相同的 per-thread 串行锁；index 条目移除走
+   * _indexLock 串行链（与 updateIndexEntry 同链，并发创建 / 更新其它
+   * 线程时双方的 index 快照不会互相覆盖丢失对方的条目）。
+   */
+  async remove(threadId) {
+    if (!threadId || typeof threadId !== "string") {
+      throw new WorkThreadNotFoundError(String(threadId || ""));
+    }
+    const prev = this._threadLocks.get(threadId) || Promise.resolve();
+    let release;
+    const next = new Promise((r) => release = r);
+    this._threadLocks.set(threadId, next);
+    await prev.catch(() => {
+    });
+    try {
+      const record = await this.get(threadId);
+      if (!record) return { removed: false, alreadyAbsent: true };
+      await unlink2(this.threadFilePath(threadId)).catch(() => {
+      });
+      const indexPrev = this._indexLock;
+      let indexRelease;
+      const indexNext = new Promise((r) => indexRelease = r);
+      this._indexLock = indexNext;
+      try {
+        await indexPrev.catch(() => {
+        });
+        const index = await this.readIndex();
+        if (index.threads.some((t) => t?.threadId === threadId)) {
+          index.threads = index.threads.filter(
+            (t) => t?.threadId !== threadId
+          );
+          index.revision = (Number(index.revision) || 0) + 1;
+          await this.writeIndex(index);
+        }
+      } finally {
+        indexRelease();
+      }
+      return { removed: true, alreadyAbsent: false };
+    } finally {
+      release();
+      if (this._threadLocks.get(threadId) === next) this._threadLocks.delete(threadId);
+    }
+  }
 };
 function buildChainEdges(record) {
   const chain = Array.isArray(record.sessionChain) ? record.sessionChain : [];
@@ -7226,7 +7433,6 @@ function buildChainEdges(record) {
 import { randomUUID as randomUUID3 } from "crypto";
 var WorkThreadCommandStatus = Object.freeze({
   PENDING: "pending",
-  IN_FLIGHT: "in_flight",
   DELIVERED: "delivered",
   FAILED: "failed",
   CANCELLED: "cancelled"
@@ -7261,7 +7467,8 @@ function createCommandRecord(opts) {
     createdAt: now,
     updatedAt: now,
     deliveredAt: null,
-    ...Array.isArray(opts.capabilityActivations) && opts.capabilityActivations.length > 0 ? { capabilityActivations: opts.capabilityActivations.filter((a) => typeof a === "string") } : {}
+    ...Array.isArray(opts.capabilityActivations) && opts.capabilityActivations.length > 0 ? { capabilityActivations: opts.capabilityActivations.filter((a) => typeof a === "string") } : {},
+    ...Array.isArray(opts.images) && opts.images.filter((i) => typeof i === "string" && i.length > 0).length > 0 ? { images: opts.images.filter((i) => typeof i === "string" && i.length > 0) } : {}
   };
 }
 function appendCommand(record, command) {
@@ -7269,7 +7476,7 @@ function appendCommand(record, command) {
   record.commands = commands;
   if (command.idempotencyKey) {
     const existing = commands.find(
-      (c) => c.idempotencyKey === command.idempotencyKey && (c.status === WorkThreadCommandStatus.PENDING || c.status === WorkThreadCommandStatus.IN_FLIGHT || c.status === WorkThreadCommandStatus.DELIVERED)
+      (c) => c.idempotencyKey === command.idempotencyKey && (c.status === WorkThreadCommandStatus.PENDING || c.status === WorkThreadCommandStatus.DELIVERED)
     );
     if (existing) {
       return { command: existing, duplicate: true };
@@ -7334,7 +7541,8 @@ var WorkThreadRuntimeBridge = class {
         text: command.text || "",
         source: "thread",
         sourceRef: command.commandId || "",
-        ...Array.isArray(command.capabilityActivations) && command.capabilityActivations.length > 0 ? { capabilityActivations: command.capabilityActivations } : {}
+        ...Array.isArray(command.capabilityActivations) && command.capabilityActivations.length > 0 ? { capabilityActivations: command.capabilityActivations } : {},
+        ...Array.isArray(command.images) && command.images.length > 0 ? { images: command.images } : {}
       });
     } catch (error) {
       if (isUserTurnDeliveryError(error)) {
@@ -7385,6 +7593,11 @@ function pushLifecycleEvent(record, event, maxEvents = 200) {
   }
   record.lastLifecycleEvent = event;
 }
+var DEFAULT_SUCCESSION_INSTRUCTION = [
+  "\u4E0A\u4E0B\u6587\u5DF2\u7CBE\u7B80\u63A5\u529B\u3002\u5148\u68C0\u67E5\u5F53\u524D\u5DE5\u4F5C\u6811\u3001\u5DF2\u6709\u53D8\u66F4\u3001\u6D4B\u8BD5\u7ED3\u679C\u548C\u4E0A\u4E00\u68D2\u6458\u8981\uFF0C",
+  "\u786E\u8BA4\u54EA\u4E9B\u6B65\u9AA4\u5DF2\u7ECF\u5B8C\u6210\uFF1B\u4E0D\u8981\u91CD\u590D\u53EF\u80FD\u5DF2\u6709\u526F\u4F5C\u7528\u7684\u64CD\u4F5C\uFF0C\u7136\u540E\u7EE7\u7EED\u5F53\u524D\u4EFB\u52A1\u3002",
+  "\u9700\u8981\u4EBA\u5DE5\u51B3\u7B56\u6216\u65E0\u6CD5\u5B89\u5168\u5224\u65AD\u65F6\uFF0C\u660E\u786E\u8BF4\u660E\u539F\u56E0\u3002"
+].join("");
 function threadIdentityError(message, code, status) {
   return Object.assign(new Error(message), { code, status });
 }
@@ -7392,10 +7605,12 @@ var WorkThread = class {
   store;
   _bridge;
   _identitySource;
-  constructor({ store, bridge, identitySource }) {
+  _continuationPolicy;
+  constructor({ store, bridge, identitySource, continuationPolicy }) {
     this.store = store;
     this._bridge = bridge || new WorkThreadRuntimeBridge();
     this._identitySource = identitySource && typeof identitySource === "function" ? identitySource : void 0;
+    this._continuationPolicy = continuationPolicy && typeof continuationPolicy.composeSuccessionInstruction === "function" ? continuationPolicy : { composeSuccessionInstruction: () => DEFAULT_SUCCESSION_INSTRUCTION };
   }
   // ── 查询 ─────────────────────────────────────────────────────────
   async listThreads(opts = {}) {
@@ -7509,8 +7724,16 @@ var WorkThread = class {
     return Date.now() - pending.startedAt < HANDOFF_STALE_MS;
   }
   /**
-   * 标记线程进入交接：写入 pendingSuccession（幂等，重复调用刷新时间戳）。
-   * 同步置 status=rotating（接续编排状态归锚点层）。
+   * 标记线程进入交接：原子写入 pendingSuccession + status=rotating，并在同
+   * 一笔事务内播种接续恢复指令（R3：createdAt 与挡板同拍，早于一切交接期
+   * 积压；幂等键绑移交易 (threadId, fromSessionId)，失败恢复重走不会重复）。
+   *
+   * 门禁（按序）：
+   *   - closed → thread_closed（硬终态）
+   *   - hold → thread_held（归档/行政冻结期不开新交接，K9）
+   *   - 已有 fresh 交接在办 → handoff_in_progress（并发竞争显式拒绝而非
+   *     幂等刷新续命，R8 跨入口 single-flight 锚点；stale 残卷可覆写重开）
+   *   - fromSessionId ≠ 当前 head → head_mismatch
    */
   async beginSessionHandoff(opts) {
     const threadId = validateId(opts.threadId, "threadId");
@@ -7523,6 +7746,18 @@ var WorkThread = class {
           status: 409
         });
       }
+      if (draft.hold === true) {
+        throw Object.assign(new Error(`WorkThread "${threadId}" is held (administrative freeze)`), {
+          code: "thread_held",
+          status: 409
+        });
+      }
+      if (draft.status === "rotating" && draft.pendingSuccession?.startedAt && Date.now() - draft.pendingSuccession.startedAt < HANDOFF_STALE_MS) {
+        throw Object.assign(
+          new Error(`WorkThread "${threadId}" already has a handoff in progress; concurrent succession requests are rejected`),
+          { code: "handoff_in_progress", status: 409 }
+        );
+      }
       if (draft.headSessionId !== normalizedFrom) {
         throw Object.assign(
           new Error(`Handoff source is not the current head of workthread "${threadId}"`),
@@ -7537,6 +7772,23 @@ var WorkThread = class {
         stage: "started",
         startedAt: now
       };
+      const instructionText = this._continuationPolicy.composeSuccessionInstruction({
+        threadId,
+        fromSessionId: normalizedFrom,
+        reason: normalizedReason
+      });
+      if (typeof instructionText === "string" && instructionText.trim()) {
+        const instruction = createCommandRecord({
+          threadId,
+          kind: WorkThreadCommandKind.SYSTEM_CONTINUATION,
+          text: instructionText,
+          source: "thread-succession",
+          idempotencyKey: `succession:${threadId}:${normalizedFrom}`
+        });
+        instruction.createdAt = now;
+        appendCommand(draft, instruction);
+        pruneCommands(draft);
+      }
       pushLifecycleEvent(draft, {
         type: "handoff_started",
         status: "rotating",
@@ -7563,15 +7815,21 @@ var WorkThread = class {
   /**
    * 标记交接失败为接续编排状态 rotation_failed，不折叠成通用执行失败。
    * pendingSuccession 保留在盘上，供后续 resume 检查被打断的确切 stage。
+   *
+   * K3 守卫（事务内）：失败记录的资格来自「在办移交」本身——
+   *   - closed 线程：硬终态，任何迟到失败不得覆写（返回原记录，零写入）；
+   *   - 无 pendingSuccession（移交已成功推进 / 从未开始）：迟到的失败者
+   *     没有立卷资格，no-op 返回。这两条共同保证：只有「挡板仍在」的在办
+   *     移交失败才会落 rotation_failed。
    */
   async failSessionHandoff(threadId, opts = {}) {
-    const thread = await this.store.get(threadId);
-    if (!thread) throw new WorkThreadNotFoundError(threadId);
-    const { record } = await this.store.update(threadId, (draft) => {
-      draft.status = "rotation_failed";
-      if (draft.pendingSuccession) {
-        draft.pendingSuccession.stage = cleanText(opts.stage) || draft.pendingSuccession.stage || "unknown";
+    const tid = validateId(threadId, "threadId");
+    const { record } = await this.store.update(tid, (draft) => {
+      if (draft.status === WORKTHREAD_TERMINAL_STATUS || !draft.pendingSuccession) {
+        return draft;
       }
+      draft.status = "rotation_failed";
+      draft.pendingSuccession.stage = cleanText(opts.stage) || draft.pendingSuccession.stage || "unknown";
       pushLifecycleEvent(draft, {
         type: "handoff_failed",
         status: "rotation_failed",
@@ -7591,9 +7849,18 @@ var WorkThread = class {
    */
   async appendCommand(opts) {
     const threadId = validateId(opts.threadId, "threadId");
-    const normalizedKind = opts.kind && Object.values(WorkThreadCommandKind).includes(opts.kind) ? opts.kind : WorkThreadCommandKind.USER_MESSAGE;
+    const normalizedKind = opts.kind === void 0 || opts.kind === "" ? WorkThreadCommandKind.USER_MESSAGE : opts.kind;
+    if (!Object.values(WorkThreadCommandKind).includes(normalizedKind)) {
+      throw Object.assign(
+        new Error(
+          `Unknown command kind "${normalizedKind}" (expected one of: ${Object.values(WorkThreadCommandKind).join(", ")})`
+        ),
+        { code: "invalid_request", status: 400 }
+      );
+    }
     const normalizedText = String(opts.text || "");
-    if (!normalizedText.trim()) {
+    const normalizedImages = Array.isArray(opts.images) ? opts.images.filter((entry) => typeof entry === "string" && entry.trim()) : [];
+    if (!normalizedText.trim() && normalizedImages.length === 0) {
       throw Object.assign(new Error("Command text must be non-empty"), {
         code: "invalid_request",
         status: 400
@@ -7611,10 +7878,17 @@ var WorkThread = class {
       text: normalizedText,
       source: cleanText(opts.source) || "ui",
       idempotencyKey: cleanText(opts.idempotencyKey),
-      ...Array.isArray(opts.capabilityActivations) ? { capabilityActivations: opts.capabilityActivations } : {}
+      ...Array.isArray(opts.capabilityActivations) ? { capabilityActivations: opts.capabilityActivations } : {},
+      ...normalizedImages.length > 0 ? { images: normalizedImages } : {}
     });
     let appendOutcome = { command, duplicate: false };
     const { record } = await this.store.update(threadId, (draft) => {
+      if (draft.status === WORKTHREAD_TERMINAL_STATUS) {
+        throw Object.assign(new Error(`WorkThread "${threadId}" is closed; terminal threads hold no new commands`), {
+          code: "thread_closed",
+          status: 409
+        });
+      }
       appendOutcome = appendCommand(draft, command);
       pruneCommands(draft);
       return draft;
@@ -7678,7 +7952,29 @@ var WorkThread = class {
     let deliveredCount = 0;
     let stopReason = null;
     for (const command of pending) {
-      const outcome = await this._bridge.deliver({ thread, command });
+      const fresh = await this.store.get(tid);
+      if (!fresh) throw new WorkThreadNotFoundError(tid);
+      if (this.isTerminal(fresh)) {
+        stopReason = "thread_closed";
+        break;
+      }
+      if (fresh.hold === true) {
+        stopReason = "thread_held";
+        break;
+      }
+      if (fresh.pendingSuccession && this.isHandoffActive(fresh)) {
+        stopReason = "handoff_in_progress";
+        break;
+      }
+      if (fresh.headSessionId !== thread.headSessionId) {
+        stopReason = "head_changed";
+        break;
+      }
+      const freshCommand = (fresh.commands || []).find((c) => c?.commandId === command.commandId) || null;
+      if (!freshCommand || freshCommand.status !== WorkThreadCommandStatus.PENDING) {
+        continue;
+      }
+      const outcome = await this._bridge.deliver({ thread: fresh, command: freshCommand });
       results.push({ commandId: command.commandId, ...outcome });
       if (outcome.accepted) {
         deliveredCount += 1;
@@ -7696,6 +7992,7 @@ var WorkThread = class {
     if (deliveredIds.size > 0 || failedResults.size > 0) {
       const { record } = await this.store.update(tid, (draft) => {
         for (const c of draft.commands || []) {
+          if (c.status !== WorkThreadCommandStatus.PENDING) continue;
           if (deliveredIds.has(c.commandId)) {
             c.status = WorkThreadCommandStatus.DELIVERED;
             c.deliveryRef = results.find((r) => r.commandId === c.commandId)?.deliveryRef || null;
@@ -7739,6 +8036,10 @@ var WorkThread = class {
   /**
    * 推进线程 head：headSessionId: fromSessionId → toSessionId。
    *
+   * fromSessionId 必填（K23）：它是调用方声明的 CAS 期望值——不传即
+   * 「接受任意当前 head」，幽灵任务防串台将被合法绕过。调用方若不知道
+   * 当前 head，应先读线程再用读到的值调用（CLI 的自动填充即此语义）。
+   *
    * 关键不变量（与 store 原子写共同保证）：任一时刻线程要么明确指向旧 head，
    * 要么明确指向新 head；推进与指令状态 / 清挡板在同一次落盘中变更。
    *
@@ -7756,7 +8057,7 @@ var WorkThread = class {
   async advanceHead(opts) {
     const threadId = validateId(opts.threadId, "threadId");
     const normalizedTo = validateId(opts.toSessionId, "toSessionId");
-    const normalizedFrom = opts.fromSessionId ? validateId(opts.fromSessionId, "fromSessionId") : null;
+    const normalizedFrom = validateId(opts.fromSessionId, "fromSessionId");
     const { record } = await this.store.update(
       threadId,
       async (draft) => {
@@ -7766,7 +8067,13 @@ var WorkThread = class {
             status: 409
           });
         }
-        if (normalizedFrom && draft.headSessionId !== normalizedFrom) {
+        if (draft.hold === true) {
+          throw Object.assign(
+            new Error(`WorkThread "${threadId}" is held (administrative freeze); head cannot advance`),
+            { code: "thread_held", status: 409 }
+          );
+        }
+        if (draft.headSessionId !== normalizedFrom) {
           throw Object.assign(
             new Error(
               `Head mismatch on workthread "${threadId}": expected ${normalizedFrom}, current ${draft.headSessionId}`
@@ -7854,7 +8161,7 @@ var WorkThread = class {
           type: "handoff_completed",
           status: "open",
           at: now,
-          fromSessionId: normalizedFrom || currentHead?.sessionId || null,
+          fromSessionId: normalizedFrom,
           toSessionId: normalizedTo,
           reason: cleanText(opts.endKind) || "manual"
         });
@@ -7902,7 +8209,7 @@ var WorkThread = class {
 
 // src/core/workthread/board.ts
 import { copyFile as copyFile3, mkdir as mkdir5, readFile as readFile9, rename as rename2, unlink as unlink3, writeFile as writeFile4 } from "fs/promises";
-import { join as join10 } from "path";
+import { join as join7 } from "path";
 var BOARD_TRANSITIONS = {
   idle: /* @__PURE__ */ new Set(["running", "waiting_input", "failed", "closed"]),
   running: /* @__PURE__ */ new Set(["idle", "waiting_input", "failed", "closed"]),
@@ -7929,11 +8236,11 @@ var WorkThreadBoard = class {
       throw new Error("WorkThreadBoard requires a rootDir");
     }
     this.core = core;
-    this.boardsDir = join10(rootDir, "boards");
+    this.boardsDir = join7(rootDir, "boards");
   }
   // ── 内部持久化（独立看板域，与锚点 store 分离）──────────────
   boardFilePath(workThreadId) {
-    return join10(this.boardsDir, `${sanitizeWorkThreadFragment(workThreadId)}.board.json`);
+    return join7(this.boardsDir, `${sanitizeWorkThreadFragment(workThreadId)}.board.json`);
   }
   async getBoardId(workThreadId) {
     return workThreadId;
@@ -8273,6 +8580,7 @@ export {
   HandoffSeedFeature,
   HooksRegistry,
   LspFeature,
+  MAX_RETAINED_TERMINAL_COMMANDS,
   OPENAI_THINKING_EFFORTS,
   OPENCODE_BASIC_CONTINUITY_PROTOCOL,
   OpencodeBasicFeature,
@@ -8300,6 +8608,7 @@ export {
   WorkThreadRevisionConflictError,
   WorkThreadRuntimeBridge,
   WorkThreadStore,
+  appendCommand,
   applyTemplate,
   assistant,
   buildSummaryPrompt,
@@ -8307,6 +8616,7 @@ export {
   buildTrimmedSeedMessages,
   classifyAPIError,
   classifyAndWrapError,
+  createCommandRecord,
   createLLMCharCount,
   createLLMComplete,
   createLLMRetry,
@@ -8322,6 +8632,8 @@ export {
   emitSessionEvent,
   extractConnectionErrorDetails,
   extractErrorCode,
+  findCommand,
+  generateCommandId,
   generateSummaryText,
   generateWorkThreadId,
   getClawRuntimeUrl,
@@ -8345,7 +8657,9 @@ export {
   normalizeExportPolicy,
   normalizeSummaryPolicy,
   parseRetryAfter,
+  pendingCommands,
   preflightAssembly,
+  pruneCommands,
   readContinuityDescriptor,
   readHookDeclarations,
   resolveDebugTransportMode,