c0de-agent 1.13.0 → 1.14.0

package/dist/tools/builtin/grep.js

@@ -1,5 +1,6 @@
-import { readdir, readFile } from 'node:fs/promises';
-import { join, relative, resolve } from 'node:path';
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { safeResolve } from '../../shared/utils/path.js';
 /** Directories always skipped during search. */
 const IGNORE_DIRS = new Set(['node_modules', '.git', 'dist', '.next', 'build', '.turbo']);
 /** File extensions treated as text (skip binary files). */
@@ -63,7 +64,11 @@ async function walkForFiles(dir, base) {
             results.push(...sub);
         }
         else {
-            const ext = entry.name.slice(entry.name.lastIndexOf('.'));
+            // 无扩展名（lastIndexOf 返回 -1）时 ext 须为 ''：此前 slice(-1) 取到名字
+            // 最后一个字符，ext === '' 分支成死代码，Dockerfile/Makefile/README 等
+            // 无扩展名文本文件被静默跳过。
+            const dot = entry.name.lastIndexOf('.');
+            const ext = dot === -1 ? '' : entry.name.slice(dot);
             if (TEXT_EXTENSIONS.has(ext) || ext === '') {
                 results.push(join(dir, entry.name));
             }
@@ -84,14 +89,29 @@ export const grepTool = {
             pattern: { type: 'string', description: 'Regular expression pattern.' },
             path: { type: 'string', description: 'Base directory to search (default: cwd).' },
             caseSensitive: { type: 'boolean', description: 'Case-sensitive search (default: true).' },
-            maxResults: { type: 'number', description: 'Maximum number of matches to return.' },
+            maxResults: { type: 'integer', description: 'Maximum number of matches to return.' },
         },
         required: ['pattern'],
     },
     permission: 'auto',
     execute: async (input, ctx) => {
         const { pattern, path, caseSensitive = true, maxResults = 200 } = input;
-        const basePath = path ? resolve(ctx.cwd, path) : ctx.cwd;
+        // maxResults <= 0 会让「matches.length >= max」在首个匹配后立即成立，
+        // 静默返回 1 条且 truncated:true（语义应为最多 N 条）。
+        // Infinity（1e999）使比较恒 false、上限静默失效；小数语义无定义。
+        // 显式报错供模型自纠。
+        if (!Number.isInteger(maxResults) || maxResults < 1) {
+            return {
+                _tag: 'error',
+                error: `grep: maxResults must be an integer >= 1, got ${maxResults}`,
+            };
+        }
+        // 与 read/write/edit 同口径：path 必须落在 cwd 内——permission 是 auto，
+        // 若放行绝对路径/../，模型可在无确认下读取工作目录外文件内容（如 ~/.ssh）。
+        const basePath = path ? safeResolve(ctx.cwd, path) : ctx.cwd;
+        if (basePath === null) {
+            return { _tag: 'error', error: `Path "${path}" escapes the working directory` };
+        }
         let regex;
         try {
             regex = new RegExp(pattern, caseSensitive ? '' : 'i');
@@ -104,15 +124,32 @@ export const grepTool = {
             const files = await walkForFiles(basePath, basePath);
             const matches = [];
             const max = maxResults;
+            // 读取失败（权限不可读/悬空符号链接/删除竞态）的文件数：单文件失败只
+            // 跳过该文件，绝不中断整个搜索（与 walkForFiles 对 readdir 失败的
+            // 容错同口径），但计数并显式回报——静默跳过会让模型误判「仓库里没有」。
+            let unreadableFiles = 0;
             outer: for (const filePath of files) {
-                const stat = await readFile(filePath);
-                if (stat.length > MAX_FILE_SIZE)
+                // 先 stat 再读：大小上限的语义是「跳过 >1MB 文件」，此前先 readFile
+                // 再查长度——整个大文件已被读进内存才丢弃（仓库里一个 GB 级文件即可
+                // 让 grep 读取数 GB），且超限且不可读的文件会因先读而 EACCES 失败。
+                const info = await stat(filePath).catch(() => null);
+                if (info === null || info.size > MAX_FILE_SIZE)
+                    continue;
+                const content = await readFile(filePath, 'utf-8').catch(() => {
+                    unreadableFiles += 1;
+                    return null;
+                });
+                if (content === null)
                     continue;
-                const content = stat.toString('utf-8');
                 const lines = content.split('\n');
                 const relPath = relative(basePath, filePath);
+                // CRLF 文件每行经 split('\n') 仍携带尾 \r：^...$ / \w+$ 等锚定到行尾的
+                // 正则全部在 \r 上失败，命中行静默归零。按文件主导行尾归一化行尾再匹配
+                //（与 shake/hashline 同型；孤立 \r 即旧 Mac 行尾文件不触碰）。
+                const crlf = content.includes('\r\n');
                 for (let i = 0; i < lines.length; i++) {
-                    const line = lines[i] ?? '';
+                    const raw = lines[i] ?? '';
+                    const line = crlf && raw.endsWith('\r') ? raw.slice(0, -1) : raw;
                     const match = line.match(regex);
                     if (match) {
                         matches.push({
@@ -126,11 +163,16 @@ export const grepTool = {
                     }
                 }
             }
-            const output = matches.map((m) => `${m.file}:${m.line}: ${m.text}`).join('\n');
+            const skippedNote = unreadableFiles > 0 ? `\n[${unreadableFiles} unreadable file(s) skipped]` : '';
+            const output = matches.map((m) => `${m.file}:${m.line}: ${m.text}`).join('\n') + skippedNote;
             return {
                 _tag: 'success',
                 output,
-                metadata: { count: matches.length, truncated: matches.length >= max },
+                metadata: {
+                    count: matches.length,
+                    truncated: matches.length >= max,
+                    ...(unreadableFiles > 0 ? { unreadableFiles } : {}),
+                },
             };
         }
         catch (error) {

package/dist/tools/builtin/kanban.d.ts

@@ -25,8 +25,22 @@ type KanbanInput = {
     op: 'delete';
     id: string;
 };
+declare function formatBoardSummary(board: {
+    columns: {
+        id: string;
+        name: string;
+    }[];
+    cards: {
+        id: string;
+        title: string;
+        columnId: string;
+        priority: KanbanPriority;
+        description: string | null;
+    }[];
+}, errors?: string[]): string;
 /** kanban tool: project-scoped task board for human↔agent collaboration.
  *  Permission: auto (operates on the project's kanban board, no system side effects).
  *  State persists in DB via ctx.kanbanStore (dependency-reversal, like todoState). */
 export declare const kanbanTool: ToolDef;
 export type { KanbanInput };
+export { formatBoardSummary };

package/dist/tools/builtin/kanban.js

@@ -3,6 +3,7 @@
 // instead of in-memory session state. Agents can add, move, update, delete
 // tasks and view the full board — enabling human↔agent and agent↔agent
 // coordination via a shared kanban board.
+import { headChars } from '../../shared/utils/string.js';
 // =============================================================================
 // Summary formatter
 // =============================================================================
@@ -24,7 +25,8 @@ function formatBoardSummary(board, errors = []) {
             const sym = PRIORITY_SYMBOL[card.priority] ?? '';
             lines.push(`  ${sym} [${shortId}] ${card.title}`);
             if (card.description) {
-                const preview = card.description.length > 80 ? `${card.description.slice(0, 77)}…` : card.description;
+                // headChars 内收切点：截断不落在 emoji 代理对中间产出孤立码元。
+                const preview = card.description.length > 80 ? `${headChars(card.description, 77)}…` : card.description;
                 lines.push(`      ${preview}`);
             }
         }
@@ -212,3 +214,4 @@ The board is shared across all sessions and agents in the same project — use i
         };
     },
 };
+export { formatBoardSummary };

package/dist/tools/builtin/read.js

@@ -21,14 +21,27 @@ export const readTool = {
         type: 'object',
         properties: {
             path: { type: 'string', description: 'File path (relative to cwd or absolute).' },
-            offset: { type: 'number', description: 'Starting line number (1-indexed). Default: 1.' },
-            limit: { type: 'number', description: 'Maximum number of lines to read.' },
+            offset: { type: 'integer', description: 'Starting line number (1-indexed). Default: 1.' },
+            limit: { type: 'integer', description: 'Maximum number of lines to read.' },
         },
         required: ['path'],
     },
     permission: 'auto',
     execute: async (input, ctx) => {
         const { path, offset, limit } = input;
+        // offset 为 1-indexed 行号。offset < 1 或 limit < 0 会经 (offset ?? 1) - 1
+        // 产生负 slice 起点/终点，静默返回错位内容（如 offset=0 → 最后一行）。
+        // JSON 还可表示 Infinity（1e999）与小数：slice 对非整数静默截断/错位
+        // （offset=Infinity → 空串、offset=2.5 → 错行）。一律显式报错让模型自纠。
+        if (offset !== undefined && (!Number.isInteger(offset) || offset < 1)) {
+            return {
+                _tag: 'error',
+                error: `read: offset must be an integer >= 1 (1-indexed), got ${offset}`,
+            };
+        }
+        if (limit !== undefined && (!Number.isInteger(limit) || limit < 0)) {
+            return { _tag: 'error', error: `read: limit must be an integer >= 0, got ${limit}` };
+        }
         // 内部 URL scheme（spec §3.10）：skill://, agent://, pr:// 等。
         // 命中时走 resolver 拿到文本内容，再统一应用 offset/limit；目录列举对 URL 无意义。
         if (isURLPath(path)) {

package/dist/tools/builtin/resolvers.d.ts

@@ -1,7 +1,14 @@
 import type { URLRegistry, URLResolver } from '../../shared/types/tool.js';
-/** file:// 解析器：`file://rel/path` 相对 cwd；`file:///abs/path` 用绝对路径。 */
+/**
+ * file:// 解析器：`file://rel/path` 相对 cwd；`file:///abs/path` 用绝对路径。
+ * 与 read/grep/glob/bash 同口径：解析结果必须落在 cwd 内（safeResolve 沙箱）——
+ * read 工具 permission=auto，若放行任意绝对路径/../，模型可无确认读取
+ * 工作目录外文件（如 ~/.ssh）。
+ */
 declare function createFileResolver(): URLResolver;
-/** skill:// 解析器：技能文件候选路径（项目优先于全局）。 */
+/** skill:// 解析器：技能文件候选路径（项目优先于全局）。
+ *  name 必须是单个路径段：此前未校验，'../config' 可读出 .c0de/config.md，
+ *  绝对路径经 resolvePath 前缀重置可读出磁盘任意 .md 文件。 */
 declare function createSkillResolver(opts?: {
     homeDir?: string;
 }): URLResolver;

package/dist/tools/builtin/resolvers.js

@@ -2,14 +2,15 @@
 //
 // registry 框架（createURLRegistry / registerURLResolver / resolveURL 分发）见
 // ../resolver.ts。这里实现具体 scheme 的内容来源：
-//   - file://  → 本地文件（相对 ctx.cwd 或绝对路径）
-//   - skill:// → 技能文件，项目 .c0de/skills/<name>(.md|/SKILL.md) 优先于
-//                全局 ~/.c0de/skills/<name>(.md|/SKILL.md)
+//   - file://  → 本地文件（相对 ctx.cwd 或 cwd 内绝对路径，safeResolve 沙箱约束）
+//   - skill:// → 技能文件（name 单路径段），项目 .c0de/skills/<name>(.md|/SKILL.md)
+//                优先于全局 ~/.c0de/skills/<name>(.md|/SKILL.md)
 //
 // agent:// pr:// issue:// 依赖未实现的子 agent 输出与 GitHub 访问，暂不内置。
 import { readFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { resolve as resolvePath } from 'node:path';
+import { safeResolve } from '../../shared/utils/path.js';
 import { createURLRegistry, registerURLResolver } from '../resolver.js';
 /** 从 `scheme://rest` 中取出 rest（scheme 已校验过，直接切首个 `://`）。 */
 function stripScheme(url) {
@@ -20,14 +21,22 @@ function stripScheme(url) {
 async function readOrFail(path) {
     return readFile(path, 'utf-8');
 }
-/** file:// 解析器：`file://rel/path` 相对 cwd；`file:///abs/path` 用绝对路径。 */
+/**
+ * file:// 解析器：`file://rel/path` 相对 cwd；`file:///abs/path` 用绝对路径。
+ * 与 read/grep/glob/bash 同口径：解析结果必须落在 cwd 内（safeResolve 沙箱）——
+ * read 工具 permission=auto，若放行任意绝对路径/../，模型可无确认读取
+ * 工作目录外文件（如 ~/.ssh）。
+ */
 function createFileResolver() {
     return {
         scheme: 'file',
         resolve: async (url, ctx) => {
             const rest = stripScheme(url);
             // file:///abs → rest 形如 /abs（已含前导斜杠）；file://rel → rest 形如 rel。
-            const path = resolvePath(ctx.cwd, rest);
+            const path = safeResolve(ctx.cwd, rest);
+            if (path === null) {
+                throw new Error(`file:// path "${rest}" escapes the working directory`);
+            }
             return readOrFail(path);
         },
     };
@@ -46,7 +55,9 @@ async function firstExistingFile(candidates) {
     }
     return null;
 }
-/** skill:// 解析器：技能文件候选路径（项目优先于全局）。 */
+/** skill:// 解析器：技能文件候选路径（项目优先于全局）。
+ *  name 必须是单个路径段：此前未校验，'../config' 可读出 .c0de/config.md，
+ *  绝对路径经 resolvePath 前缀重置可读出磁盘任意 .md 文件。 */
 function createSkillResolver(opts) {
     const home = opts?.homeDir ?? homedir();
     return {
@@ -55,6 +66,9 @@ function createSkillResolver(opts) {
             const name = stripScheme(url);
             if (!name)
                 throw new Error('skill URL requires a name, e.g. skill://brainstorming');
+            if (name === '.' || name === '..' || name.includes('/') || name.includes('\\')) {
+                throw new Error(`Invalid skill name "${name}": must be a single path segment (no /, ..)`);
+            }
             const candidates = [
                 resolvePath(ctx.cwd, '.c0de', 'skills', `${name}.md`),
                 resolvePath(ctx.cwd, '.c0de', 'skills', name, 'SKILL.md'),

package/dist/tools/builtin/task.js

@@ -29,58 +29,140 @@ export const taskTool = {
                         role: { type: 'string', description: 'Specialist role for this sub-task.' },
                         assignment: { type: 'string' },
                     },
+                    // 缺 assignment 的条目此前静默派出 prompt=undefined 的子 agent
+                    // （headChars 抛 TypeError / 烧一轮内容为 "undefined" 的 LLM 调用）——
+                    // 逐条目显式必填，错误信息可指导模型修正。
+                    required: ['assignment'],
                 },
                 description: 'Parallel sub-tasks (batch mode).',
             },
         },
-        required: ['prompt'],
+        // 单任务（prompt）与批量（context+tasks）二选一。不能与顶层
+        // required:['prompt'] 并存：anyOf 与兄弟关键字是合取关系，顶层 required
+        // 会让批量形态恒校验失败。
         anyOf: [{ required: ['prompt'] }, { required: ['context', 'tasks'] }],
     },
     permission: 'auto',
     execute: async (input, ctx) => {
-        if (!ctx.runSubAgent) {
+        // 单任务入口（ctx.runSubAgent）与批量入口（ctx.runSubAgents）二选一即可工作：
+        // 批量入口存在时批量模式走宿主的并发池，否则回退逐个派发。
+        const runOne = ctx.runSubAgent;
+        const runBatch = ctx.runSubAgents;
+        if (!runOne && !runBatch) {
             return {
                 _tag: 'error',
                 error: 'task tool unavailable: no sub-agent runner is wired into this context',
             };
         }
         const inp = input;
+        // 运行时形状校验（schema 兜底之外的执行层防线——execute 可绕过 executor
+        // 校验被直接调用）。此前 tasks 条目缺 assignment / 空 tasks 数组会静默
+        // 落回单任务模式，把 prompt=undefined 派给子 agent（headChars 处 TypeError
+        // 或烧一轮内容为 "undefined" 的 LLM 调用），模型只拿到晦涩报错。
+        const tasksInput = 'tasks' in inp ? inp.tasks : undefined;
+        if (tasksInput !== undefined && !Array.isArray(tasksInput)) {
+            return {
+                _tag: 'error',
+                error: 'task: tasks must be an array of { assignment, description?, role? }',
+            };
+        }
+        const batchTasks = Array.isArray(tasksInput) ? tasksInput : [];
+        for (let i = 0; i < batchTasks.length; i++) {
+            const item = batchTasks[i];
+            if (item === null ||
+                typeof item !== 'object' ||
+                Array.isArray(item) ||
+                typeof item.assignment !== 'string' ||
+                item.assignment.trim().length === 0) {
+                return {
+                    _tag: 'error',
+                    error: `task: tasks[${i}] is missing a non-empty string "assignment" (the sub-agent prompt). Expected batch item shape: { assignment, description?, role? }`,
+                };
+            }
+        }
         // 批量模式
-        if ('tasks' in inp && Array.isArray(inp.tasks) && inp.tasks.length > 0) {
-            const agentType = inp.subagent_type ?? 'general';
+        if ('tasks' in inp && batchTasks.length > 0) {
+            const agentType = typeof inp.subagent_type === 'string' && inp.subagent_type.length > 0
+                ? inp.subagent_type
+                : 'general';
+            const requests = batchTasks.map((item) => ({
+                agentType,
+                prompt: item.assignment,
+                ...(typeof item.description === 'string' && item.description.length > 0
+                    ? { description: item.description }
+                    : {}),
+                ...(typeof item.role === 'string' && item.role.length > 0 ? { role: item.role } : {}),
+                ...(typeof inp.context === 'string' && inp.context.length > 0
+                    ? { context: inp.context }
+                    : {}),
+            }));
+            // 并发派发：工具描述承诺 "Launch multiple agents concurrently"，宿主批量入口
+            // 按 config.agents.subagentConcurrency 建并发池。此前无论宿主是否提供批量能力
+            // 都逐个 await——N 个子 agent 的墙钟时间线性叠加，并发配置形同虚设。
+            // 宿主未注入批量入口时回退逐个派发（结果顺序不变，仅串行）。
             const results = [];
-            for (const item of inp.tasks) {
-                const req = {
-                    agentType,
-                    prompt: item.assignment,
-                    ...(item.description ? { description: item.description } : {}),
-                    ...(item.role ? { role: item.role } : {}),
-                    ...(inp.context ? { context: inp.context } : {}),
-                };
-                const res = await ctx.runSubAgent(req);
+            if (runBatch) {
+                results.push(...(await runBatch(requests)));
+            }
+            else if (runOne) {
+                for (const req of requests)
+                    results.push(await runOne(req));
+            }
+            const label = (i) => inp.tasks[i]?.description ?? inp.tasks[i]?.role ?? 'task';
+            const completed = [];
+            const failures = [];
+            results.forEach((res, i) => {
                 if (res._tag === 'error') {
-                    return { _tag: 'error', error: `Sub-agent failed: ${res.error}` };
+                    failures.push(`[${label(i)}] ${res.error}`);
+                    return;
                 }
-                const label = item.description ?? item.role ?? 'task';
                 if (res._tag === 'running') {
-                    results.push(`[${label}] background started (jobId: ${res.jobId})`);
-                }
-                else {
-                    results.push(`[${label}] ${res.output}`);
+                    completed.push(`[${label(i)}] background started (jobId: ${res.jobId})`);
+                    return;
                 }
+                completed.push(`[${label(i)}] ${res.output}`);
+            });
+            if (failures.length > 0) {
+                // 失败不吞掉已完成任务的结果：模型据此只重派失败的子任务
+                return {
+                    _tag: 'error',
+                    error: `Sub-agent failed: ${failures.join('; ')}` +
+                        (completed.length > 0 ? `\n\nCompleted:\n${completed.join('\n\n')}` : ''),
+                };
             }
-            return { _tag: 'success', output: results.join('\n\n') };
+            return { _tag: 'success', output: completed.join('\n\n') };
         }
         // 单任务模式
         const single = inp;
+        // 空 tasks 数组等形态会落进单任务分支：prompt 非非空字符串显式报错，
+        // 绝不把 undefined 派给子 agent。
+        if (typeof single.prompt !== 'string' || single.prompt.trim().length === 0) {
+            return {
+                _tag: 'error',
+                error: 'task: prompt must be a non-empty string (single mode) — for batch mode provide context + tasks[] where every item has a non-empty "assignment"',
+            };
+        }
+        const agentType = typeof single.subagent_type === 'string' && single.subagent_type.length > 0
+            ? single.subagent_type
+            : 'general';
         const req = {
-            agentType: single.subagent_type ?? 'general',
+            agentType,
             prompt: single.prompt,
-            ...(single.description ? { description: single.description } : {}),
-            ...(single.model ? { model: single.model } : {}),
-            ...(single.background ? { background: true } : {}),
+            ...(typeof single.description === 'string' && single.description.length > 0
+                ? { description: single.description }
+                : {}),
+            ...(typeof single.model === 'string' && single.model.length > 0
+                ? { model: single.model }
+                : {}),
+            ...(single.background === true ? { background: true } : {}),
         };
-        const result = await ctx.runSubAgent(req);
+        if (!runOne) {
+            return {
+                _tag: 'error',
+                error: 'task tool unavailable: single-task mode requires a sub-agent runner (ctx.runSubAgent)',
+            };
+        }
+        const result = await runOne(req);
         if (result._tag === 'error') {
             return { _tag: 'error', error: `Sub-agent failed: ${result.error}` };
         }

package/dist/tools/builtin/todo.js

@@ -288,17 +288,33 @@ const STATUS_TO_MARKER = {
     completed: 'x',
     abandoned: '-',
 };
+/** 渲染转义：反斜杠先行、换行编码为字面 `\n`、回车编码为字面 `\r`——
+ *  任务内容/阶段名恒渲染为单行，内容里的换行无法在解析侧伪装成续行结构
+ *  （- [x] / # 行首注入），裸 \r 也不会被 split(/\r?\n/) 拆成行边界
+ *  （此前内容含 \r 时渲染后拆行，内容被截断为行首片段）。
+ *  与 unescapeMarkdownContent 严格互逆。 */
+function escapeMarkdownContent(value) {
+    return value.replace(/\\/g, '\\\\').replace(/\r/g, '\\r').replace(/\n/g, '\\n');
+}
+/** 渲染转义的逆操作（单趟：`\n` → 换行，`\r` → 回车，`\\` → 反斜杠，长匹配
+ *  优先保证字面 "\\n"/"\\r" 还原为反斜杠+n/r 而非真换行/回车）。 */
+function unescapeMarkdownContent(value) {
+    return value.replace(/\\n|\\r|\\\\/g, (m) => (m === '\\n' ? '\n' : m === '\\r' ? '\r' : '\\'));
+}
 /** Render todo phases as a Markdown checklist suitable for editing/copying. */
 export function phasesToMarkdown(phases) {
+    // 空列表渲染为空串（而非 "# Todos" 占位）——markdownToPhases("# Todos\n")
+    // 会解析出含一个空 "Todos" 阶段的列表，round-trip 契约
+    // （markdownToPhases(phasesToMarkdown(x)) === x）对 x=[] 被静默破坏。
     if (phases.length === 0)
-        return '# Todos\n';
+        return '';
     const out = [];
     for (const [i, phase] of phases.entries()) {
         if (i > 0)
             out.push('');
-        out.push(`# ${phase.name}`);
+        out.push(`# ${escapeMarkdownContent(phase.name)}`);
         for (const task of phase.tasks) {
-            out.push(`- [${STATUS_TO_MARKER[task.status]}] ${task.content}`);
+            out.push(`- [${STATUS_TO_MARKER[task.status]}] ${escapeMarkdownContent(task.content)}`);
         }
     }
     return `${out.join('\n')}\n`;
@@ -323,13 +339,24 @@ export function markdownToPhases(md) {
         const trimmed = raw.trim();
         if (!trimmed)
             continue;
-        const headingMatch = /^#{1,6}\s+(.+?)\s*$/.exec(trimmed);
+        // 空阶段名合法（模型可传 phase:'' 或用户手动清空标题）：heading 名称允许
+        // 为空——此前 (.+?) 要求非空，"# " 行报 unrecognized syntax、阶段被改名
+        // "Todos" 且其任务被挪进伪阶段（round-trip 静默改名 + 任务错位）。
+        const headingMatch = /^#{1,6}\s*(.*?)\s*$/.exec(trimmed);
         if (headingMatch) {
-            currentPhase = { name: (headingMatch[1] ?? '').trim(), tasks: [] };
+            // 名称从原始行取（保留前导/尾随空白，渲染方不 trim）；换行/反斜杠
+            // 经渲染转义可逆还原。此前从 trimmed 分组取名称，尾随空白静默丢失。
+            // 渲染格式恒为 `# <name>`：只吃掉 `#` 后的**一个**分隔空白——`\s*` 会把
+            // 名字自身的前导空白一起吞掉（`#   Lead` 解析回 `Lead`），与尾随空白
+            // 同型的 round-trip 静默改写。
+            const name = unescapeMarkdownContent(raw.replace(/^\s*#{1,6}[ \t]?/, ''));
+            currentPhase = { name, tasks: [] };
             phases.push(currentPhase);
             continue;
         }
-        const taskMatch = /^[-*+]\s*\[(.?)\]\s+(.+?)\s*$/.exec(trimmed);
+        // 空内容任务（"- [ ] "）合法：(.+?) 会把它报成 unrecognized syntax 并
+        // 丢弃任务——round-trip 丢数据。
+        const taskMatch = /^[-*+]\s*\[(.?)\]\s*(.*?)\s*$/.exec(trimmed);
         if (taskMatch) {
             if (!currentPhase) {
                 currentPhase = { name: 'Todos', tasks: [] };
@@ -341,12 +368,18 @@ export function markdownToPhases(md) {
                 errors.push(`Line ${lineNum + 1}: unknown status marker "[${marker}]" (use [ ], [x], [/], [-])`);
                 continue;
             }
-            currentPhase.tasks.push({ content: (taskMatch[2] ?? '').trim(), status });
+            // 内容从原始行取：`\s?` 只吃标记与内容之间的单个分隔空格——前导
+            // 空白与尾随空白是内容的一部分，必须保真（trim 会静默改写）。
+            const contentRaw = /^[-*+]\s*\[(.?)\]\s?(.*)$/.exec(raw)?.[2] ?? '';
+            currentPhase.tasks.push({ content: unescapeMarkdownContent(contentRaw), status });
             continue;
         }
         errors.push(`Line ${lineNum + 1}: unrecognized syntax "${trimmed}"`);
     }
-    normalizeInProgressTask(phases);
+    // 解析必须保真（markdownToPhases(phasesToMarkdown(x)) === x 的 round-trip
+    // 契约）：normalizeInProgressTask 是 op 状态不变量（at most one
+    // in_progress），此前在解析收尾调用会把无 in_progress 的列表「自动提升
+    // 首条 pending」、多条 in_progress「降级除首条外」——导入的数据被静默改写。
     return { phases, errors };
 }
 // =============================================================================
@@ -431,12 +464,54 @@ export function getLatestTodoPhasesFromMessages(messages) {
             const metadata = output.metadata;
             const phases = metadata?.phases;
             if (Array.isArray(phases)) {
-                return clonePhases(phases);
+                return sanitizeTodoPhases(phases);
             }
         }
     }
     return [];
 }
+/**
+ * 收敛消息里 phases 数组的形状（未受信数据：会话导入的 sanitize 只校验
+ * tool_result 分片形状，不递归校验 metadata.phases——{name:1, tasks:'x'}、
+ * 缺字段、null 条目等畸形数据原样入库）。此前直接 clonePhases：
+ * phase.tasks.map 在非数组上抛 TypeError，GET/POST /api/sessions/:id/todo
+ * 击穿 500，todo 面板对该会话永久不可用。畸形条目整体丢弃（宁少勿坏，
+ * 与导入 sanitize 同口径）。
+ */
+function sanitizeTodoPhases(phases) {
+    const out = [];
+    for (const phase of phases) {
+        if (phase === null || typeof phase !== 'object')
+            continue;
+        const name = phase.name;
+        const tasks = phase.tasks;
+        if (typeof name !== 'string' || !Array.isArray(tasks))
+            continue;
+        const cleanTasks = [];
+        let wellFormed = true;
+        for (const task of tasks) {
+            if (task === null || typeof task !== 'object') {
+                wellFormed = false;
+                break;
+            }
+            const content = task.content;
+            const status = task.status;
+            if (typeof content !== 'string' ||
+                (status !== 'pending' &&
+                    status !== 'in_progress' &&
+                    status !== 'completed' &&
+                    status !== 'abandoned')) {
+                wellFormed = false;
+                break;
+            }
+            cleanTasks.push({ content, status });
+        }
+        if (!wellFormed)
+            continue;
+        out.push({ name, tasks: cleanTasks });
+    }
+    return out;
+}
 // =============================================================================
 // Schema
 // =============================================================================

package/dist/tools/builtin/write.js

@@ -26,7 +26,13 @@ export const writeTool = {
         try {
             await mkdir(dirname(fullPath), { recursive: true });
             await writeFile(fullPath, content, 'utf-8');
-            return { _tag: 'success', output: `Wrote ${content.length} bytes to ${path}` };
+            // 字节数按 UTF-8 编码计：content.length 是 UTF-16 码元数，非 ASCII 内容
+            // （中文 3×、emoji 4×）会被低估数倍——工具反馈是模型/用户判断落盘
+            // 大小的唯一依据，谎报字节数误导后续操作。
+            return {
+                _tag: 'success',
+                output: `Wrote ${Buffer.byteLength(content, 'utf8')} bytes to ${path}`,
+            };
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);

package/dist/tools/builtin/yield.js

@@ -34,7 +34,15 @@ export const yieldTool = {
     permission: 'auto',
     execute: async (input, ctx) => {
         const { data } = input;
-        ctx.collectYield?.(data);
+        // collectYield 由宿主实现（runSubAgent）——宿主在收集时对 outputSchema 做
+        // 校验并抛错。把校验失败折成 error ToolResult 回给模型：模型看到失败原因后
+        // 可修正 data 重试，而非整个子 run 静默带上非法结果。
+        try {
+            ctx.collectYield?.(data);
+        }
+        catch (error) {
+            return { _tag: 'error', error: error instanceof Error ? error.message : String(error) };
+        }
         return { _tag: 'success', output: 'Result submitted.' };
     },
 };