ladder-mcp 1.1.2 → 1.1.5

package/CHANGELOG.md

@@ -4,6 +4,86 @@ All notable changes to Ladder_mcp are documented here. Format loosely follows
 [Keep a Changelog](https://keepachangelog.com/); this project uses
 [Semantic Versioning](https://semver.org/).
 
+## [1.1.5] - 2026-06-28
+
+Turn Kimi's TODO/plan into a watchable live checklist.
+
+### Added
+
+- Kimi's working TODO list is now surfaced as a `todo` progress event in both
+  transports. A shared `createTodoTracker` holds the current `{ text, status }`
+  list (replaced on each update) and renders a compact one-line summary
+  (`TODO 2/4 ✓✓·· · now: <current item>`) for the live progress line, plus the
+  full multi-line snapshot in the background task log.
+- **CLI**: `role:tool` `TodoList` results (the `Current todo list:` text
+  snapshot) are parsed and tracked. **ACP**: structured `tool_call_update`/`plan`
+  TODO payloads — JSON `{"todos":[{title,status}]}` or the text snapshot — are
+  parsed into the same tracker. The normal `tool_call`/`plan` action event is
+  still emitted alongside the `todo` event, so actions stay visible.
+- The progress coalescer gains a TODO-priority dwell window (`todoPriorityMs`,
+  default 5s): after a TODO update, chatty `message`/`thought` previews are
+  suppressed so the checklist line stays readable, while `tool_call`,
+  `tool_update`, and `plan` actions still surface immediately. Suppressed preview
+  tails are never lost — they flush on the next TODO, on window expiry, and on
+  stop/cancel.
+
+### Changed
+
+- The background task log now uses `formatTaskLogLine`, which indents the full
+  TODO snapshot under the compact summary; foreground/MCP progress stays on the
+  compact `formatProgressLine`.
+- Removed the CLI stall watchdog. Kimi CLI 0.20.1 works silently during long
+  thinking phases, so the watchdog produced false `stall` warnings. The ACP
+  transport keeps its watchdog (it streams granular per-action activity).
+
+### Notes
+
+- Additive change: the existing `tool_call`/`tool_update`/`message`/`thought`/
+  `plan` events and the task log are otherwise unchanged — `todo` is an added
+  layer. No new runtime dependency; `kimi-code-mcp/` untouched.
+
+## [1.1.4] - 2026-06-28
+
+Make the live-progress line worth watching.
+
+### Changed
+
+- Live progress now shows a readable content **preview** of the streamed
+  `message`/`thought` text (whitespace collapsed, code-point-safe truncation with
+  an ellipsis) instead of a bare `(N chars)` counter.
+- Progress emission is throttled to at most one update per ~1.2s, so the single
+  progress line stops flickering and each line stays readable. `tool_call`,
+  `tool_update`, and `plan` events remain immediate and flush any pending preview
+  first to preserve order.
+- The two per-transport coalescers (CLI and ACP) are unified into one shared
+  `createProgressCoalescer` in `src/progress.ts`; the duplicated `COALESCE_*`
+  constants are gone.
+
+### Notes
+
+- Kimi CLI 0.20.1 does not stream thinking to stderr during `-p` runs, so live
+  `thought` progress is not available on the CLI transport (documented in code).
+  The ACP transport already emits `thought`, which now gets the preview treatment.
+
+## [1.1.3] - 2026-06-28
+
+Bugfix: analysis-mode `kimi_code` was broken against Kimi CLI 0.20.1.
+
+### Fixed
+
+- `kimi_code` without `edit: true` (the default analysis mode) crashed against
+  Kimi CLI 0.20.1 with `Cannot combine --prompt with --plan`. `buildKimiArgs` no
+  longer passes `--plan` in `-p` prompt mode (the CLI rejects it, along with
+  `--auto`/`-y`).
+
+### Changed
+
+- Because Kimi 0.20.1 has no `-p`-compatible read-only flag, the `edit: false`
+  analysis-only contract is now enforced at the prompt level: `runKimi` prepends
+  a read-only guard (`applyReadOnlyGuard`) when `edit` is not `true`. This is
+  advisory (the model is instructed not to edit) rather than a hard CLI
+  guarantee; the `edit` parameter description documents the change.
+
 ## [1.1.2] - 2026-06-28
 
 Live-progress and cancellation reliability for `kimi_code`.

package/README.md

@@ -1,110 +1,110 @@
-# Ladder_mcp
-
-Windows-first [MCP](https://modelcontextprotocol.io/) bridge for the
-[Kimi Code](https://kimi.com) CLI (v24). It exposes Kimi Code as MCP tools so a
-client like Claude Code can run codebase analysis, native sessions, API
-queries, ACP chat, background tasks, and CLI admin/diagnostics — all on Windows
-without hardcoded POSIX assumptions.
-
-> Status: **v1.1.2** ([npm](https://www.npmjs.com/package/ladder-mcp)).
-> Supported platform is **Windows 11 only**.
-
-## Requirements
-
-- Windows 11
-- Node.js ≥ 18
-- Kimi Code CLI installed (`kimi.exe` on PATH or at `~/.kimi-code/bin/kimi.exe`),
-  authenticated (`~/.kimi-code/`)
-
-## Quick start (from npm)
-
-You don't need to clone or build — the package is published on npm and your MCP
-client launches it via `npx`, or you can install the package directly.
-
-**Claude Code (one command):**
-
-```bash
-claude mcp add kimi-code -- npx -y ladder-mcp
-```
-
-**Or add it manually to your MCP config:**
-
-```jsonc
-{
-  "mcpServers": {
-    "kimi-code": {
-      "command": "npx",
-      "args": ["-y", "ladder-mcp"]
-    }
-  }
-}
-```
-
-Then in Claude Code run `/mcp` (should show `kimi-code: connected`) and call
-`kimi_status` to confirm the environment is detected.
-
-> The server speaks MCP over **stdio**: it is launched and managed by the client,
-> not run by hand. Running `npx ladder-mcp` directly will appear to "hang" — that
-> is the server correctly waiting for a client. Exit with Ctrl+C.
-
-Prefer a global install? `npm install -g ladder-mcp`, then use `ladder-mcp` as the
-command instead of `npx -y ladder-mcp`.
-
-Or install locally into your project:
-
-```bash
-npm install ladder-mcp
-```
-
-Then point your MCP config at `./node_modules/.bin/ladder-mcp` (or use
-`npx -y ladder-mcp`, which resolves the locally installed copy when available).
-
-To let Kimi Code itself host this server, use the `kimi_setup`
-tool to produce/merge a `.kimi-code/mcp.json` entry.
-
-## Build from source (contributors)
-
-```bash
-npm install
-npm run build      # compiles src/ -> dist/ (tests excluded)
-```
-
-Quick checks:
-
-```bash
-npm test           # vitest (153 tests)
-npm run typecheck  # tsc --noEmit (incl. tests)
-npm run dev        # run the server from source via tsx
-```
-
-## Tools
-
-**Core (v1.1)** — `kimi_code`, `kimi_ask`, `kimi_sessions`, `kimi_tasks`,
-`kimi_status`, `kimi_setup`
-
-`kimi_code` supports both the native CLI transport (default) and the ACP
-JSON-RPC transport (`transport: 'acp'`); set `background=true` to track long
-work as a background task.
-
-**Experimental (off by default)** — `kimi_export_session`,
-`kimi_visualize_session`, `kimi_desktop_status`, `kimi_budget_probe`. Enable
-with the environment variable `LADDER_EXPERIMENTAL=1`.
-
-## Safety boundaries
-
-- `kimi_export_session` requires an explicit `output_path`, stays within the
-  working directory, and excludes the global diagnostic log by default.
-- Desktop Work tools are **experimental and read-only**: they do not read the
-  desktop token store, replay web auth, or submit desktop Work tasks.
-- The vendored `kimi-code-mcp/` is a **read-only reference** and is never edited
-  or written to by the tools.
-
-## Project layout
-
-- `src/` — the Ladder_mcp application (package `ladder-mcp`)
-- `kimi-code-mcp/` — upstream reference (read-only, MIT)
-- `_bmad-output/` — planning & implementation artifacts (BMAD workflow)
-
-## License
-
-[MIT](./LICENSE). Ports logic from the MIT-licensed `kimi-code-mcp` reference.
+# Ladder_mcp
+
+Windows-first [MCP](https://modelcontextprotocol.io/) bridge for the
+[Kimi Code](https://kimi.com) CLI (v24). It exposes Kimi Code as MCP tools so a
+client like Claude Code can run codebase analysis, native sessions, API
+queries, ACP chat, background tasks, and CLI admin/diagnostics — all on Windows
+without hardcoded POSIX assumptions.
+
+> Status: **v1.1.5** ([npm](https://www.npmjs.com/package/ladder-mcp)).
+> Supported platform is **Windows 11 only**.
+
+## Requirements
+
+- Windows 11
+- Node.js ≥ 18
+- Kimi Code CLI installed (`kimi.exe` on PATH or at `~/.kimi-code/bin/kimi.exe`),
+  authenticated (`~/.kimi-code/`)
+
+## Quick start (from npm)
+
+You don't need to clone or build — the package is published on npm and your MCP
+client launches it via `npx`, or you can install the package directly.
+
+**Claude Code (one command):**
+
+```bash
+claude mcp add kimi-code -- npx -y ladder-mcp
+```
+
+**Or add it manually to your MCP config:**
+
+```jsonc
+{
+  "mcpServers": {
+    "kimi-code": {
+      "command": "npx",
+      "args": ["-y", "ladder-mcp"]
+    }
+  }
+}
+```
+
+Then in Claude Code run `/mcp` (should show `kimi-code: connected`) and call
+`kimi_status` to confirm the environment is detected.
+
+> The server speaks MCP over **stdio**: it is launched and managed by the client,
+> not run by hand. Running `npx ladder-mcp` directly will appear to "hang" — that
+> is the server correctly waiting for a client. Exit with Ctrl+C.
+
+Prefer a global install? `npm install -g ladder-mcp`, then use `ladder-mcp` as the
+command instead of `npx -y ladder-mcp`.
+
+Or install locally into your project:
+
+```bash
+npm install ladder-mcp
+```
+
+Then point your MCP config at `./node_modules/.bin/ladder-mcp` (or use
+`npx -y ladder-mcp`, which resolves the locally installed copy when available).
+
+To let Kimi Code itself host this server, use the `kimi_setup`
+tool to produce/merge a `.kimi-code/mcp.json` entry.
+
+## Build from source (contributors)
+
+```bash
+npm install
+npm run build      # compiles src/ -> dist/ (tests excluded)
+```
+
+Quick checks:
+
+```bash
+npm test           # vitest (174 tests)
+npm run typecheck  # tsc --noEmit (incl. tests)
+npm run dev        # run the server from source via tsx
+```
+
+## Tools
+
+**Core (v1.1)** — `kimi_code`, `kimi_ask`, `kimi_sessions`, `kimi_tasks`,
+`kimi_status`, `kimi_setup`
+
+`kimi_code` supports both the native CLI transport (default) and the ACP
+JSON-RPC transport (`transport: 'acp'`); set `background=true` to track long
+work as a background task.
+
+**Experimental (off by default)** — `kimi_export_session`,
+`kimi_visualize_session`, `kimi_desktop_status`, `kimi_budget_probe`. Enable
+with the environment variable `LADDER_EXPERIMENTAL=1`.
+
+## Safety boundaries
+
+- `kimi_export_session` requires an explicit `output_path`, stays within the
+  working directory, and excludes the global diagnostic log by default.
+- Desktop Work tools are **experimental and read-only**: they do not read the
+  desktop token store, replay web auth, or submit desktop Work tasks.
+- The vendored `kimi-code-mcp/` is a **read-only reference** and is never edited
+  or written to by the tools.
+
+## Project layout
+
+- `src/` — the Ladder_mcp application (package `ladder-mcp`)
+- `kimi-code-mcp/` — upstream reference (read-only, MIT)
+- `_bmad-output/` — planning & implementation artifacts (BMAD workflow)
+
+## License
+
+[MIT](./LICENSE). Ports logic from the MIT-licensed `kimi-code-mcp` reference.

package/dist/index.js

@@ -14,7 +14,7 @@ import { exportKimiSession, getKimiCapabilities, listKimiProviders, runKimiDocto
 import { generateMcpConfig } from './kimi-mcp-config.js';
 import { buildBudgetProbeGuide, getDesktopStatus } from './desktop-work.js';
 import { taskStore } from './task-store.js';
-import { combineReporters, createMcpProgressReporter, formatProgressLine } from './progress.js';
+import { combineReporters, createMcpProgressReporter, formatTaskLogLine } from './progress.js';
 import { VERSION } from './version.js';
 const server = new McpServer({
     name: 'kimi-code',
@@ -61,7 +61,7 @@ server.tool('kimi_code', 'Agentic work in a repository: analyze and edit files.
     work_dir: z.string().describe('Absolute path to the codebase root directory.'),
     session_id: z.string().optional().describe('Explicit Kimi session id to resume.'),
     new_session: z.boolean().optional().describe('Start fresh instead of continuing the last session. Default: false.'),
-    edit: z.boolean().optional().describe('Allow file modifications. Default: false (analysis-only intent).'),
+    edit: z.boolean().optional().describe('Allow file modifications. Default: false (analysis-only intent). On Kimi 0.20.1 this is prompt-enforced (advisory): when false/omitted the prompt is prefixed with a read-only guard, but the CLI itself provides no hard read-only flag for -p mode.'),
     background: z.boolean().optional().describe('Track as a long-running background task. Every progress event (including each action) is appended to the task log, readable via kimi_tasks — the full accumulating transcript, unlike the single overwriting live-progress line of a foreground call.'),
     transport: z.enum(['cli', 'acp']).optional().describe("How the server drives Kimi. Both edit files and resume sessions; they differ in robustness and live-progress detail. 'cli' (default): one-shot process, most robust on Windows, but live progress is coarse — only streaming-output volume, no per-action lines. 'acp': persistent JSON-RPC session that emits granular live progress (tool calls, plan steps) and supports interactive permission prompts, but is heavier and more fragile. Prefer 'cli' for plain codegen/analysis; choose 'acp' when you need to watch each action live or handle mid-run prompts."),
     session_mode: z.enum(['new', 'load', 'resume']).optional().describe("ACP session mode when transport='acp'. Default: inferred from session_id/new_session."),
@@ -75,7 +75,7 @@ server.tool('kimi_code', 'Agentic work in a repository: analyze and edit files.
         return textResponse(`Error: ${workDirError}`, true);
     const includeThinkingValue = include_thinking ?? false;
     const effectiveTransport = transport ?? 'cli';
-    const appendReporter = (append) => (event) => append(formatProgressLine(event));
+    const appendReporter = (append) => (event) => append(formatTaskLogLine(event));
     if (effectiveTransport === 'cli') {
         if (background) {
             const task = taskStore.create('cli-code', async (_signal, append) => {

package/dist/kimi-runner.js

@@ -2,7 +2,7 @@ import { spawn } from 'node:child_process';
 import * as path from 'node:path';
 import { clampTimeout } from './transports/acp.js';
 import { buildKimiEnv, resolveKimiPaths } from './environment.js';
-import { createStallWatchdog, makeEvent } from './progress.js';
+import { createProgressCoalescer, createTodoTracker, parseCliTodoSnapshot } from './progress.js';
 const MAX_CAPTURE_CHARS = 16 * 1024 * 1024;
 const MAX_FAILURE_STREAM_CHARS = 2_000;
 // Append to a captured stream while enforcing a hard ceiling so a runaway CLI cannot
@@ -22,11 +22,21 @@ export function buildKimiArgs(config) {
     else if (config.continueLast) {
         args.push('-C');
     }
-    if (config.edit !== true) {
-        args.push('--plan');
-    }
+    // Kimi CLI 0.20.1 rejects combining --plan with -p/--prompt (non-interactive
+    // prompt mode), and the other restriction flags (--auto, -y) are also
+    // incompatible. For edit:false / omitted edit we therefore pass no restriction
+    // flag and rely on the prompt/system to avoid edits.
     return args;
 }
+const READ_ONLY_GUARD = '[READ-ONLY ANALYSIS MODE] Do not create, modify, or delete any files, directories, or repository state. Only read, analyze, explain, and report.';
+// Prepends a read-only guard to the prompt when edit mode is not explicitly
+// enabled. Kimi CLI 0.20.1 has no -p-compatible read-only flag, so this is the
+// only available enforcement mechanism for the analysis-only contract.
+export function applyReadOnlyGuard(prompt, edit) {
+    if (edit === true)
+        return prompt;
+    return `${READ_ONLY_GUARD}\n\n${prompt}`;
+}
 function contentToText(content) {
     if (typeof content === 'string')
         return content;
@@ -156,32 +166,6 @@ export function truncateAtBoundary(text, maxChars) {
     const cutPoint = Math.max(slice.lastIndexOf('\n## '), slice.lastIndexOf('\n\n'), Math.floor(maxChars * 0.8));
     return `${slice.slice(0, cutPoint).trimEnd()}\n\n---\nOutput truncated (${text.length.toLocaleString()} chars exceeded ${maxChars.toLocaleString()} char budget). Use kimi_resume with the same session for follow-up questions.`;
 }
-const COALESCE_MS = 750;
-const COALESCE_CHARS = 400;
-function createStreamCoalescer(reporter) {
-    let count = 0;
-    let timer;
-    const flush = () => {
-        if (timer) {
-            clearTimeout(timer);
-            timer = undefined;
-        }
-        if (count > 0) {
-            reporter(makeEvent('message', `streaming output… (${count} chars)`));
-            count = 0;
-        }
-    };
-    const add = (text) => {
-        count += text.length;
-        if (count >= COALESCE_CHARS) {
-            flush();
-        }
-        else if (!timer) {
-            timer = setTimeout(flush, COALESCE_MS);
-        }
-    };
-    return { add, flush, stop: flush };
-}
 function killProcessTree(pid) {
     if (!pid)
         return;
@@ -213,9 +197,10 @@ export function runKimi(config) {
             error: 'Kimi cancelled',
         });
     }
+    const guardedPrompt = applyReadOnlyGuard(config.prompt, config.edit);
     return new Promise((resolve) => {
         let settled = false;
-        const proc = spawn(paths.binaryPath, buildKimiArgs(config), {
+        const proc = spawn(paths.binaryPath, buildKimiArgs({ ...config, prompt: guardedPrompt }), {
             env: buildKimiEnv(),
             stdio: ['ignore', 'pipe', 'pipe'],
             windowsHide: true,
@@ -225,17 +210,15 @@ export function runKimi(config) {
         let stderr = '';
         let timedOut = false;
         let streamBuffer = '';
-        const coalescer = config.onProgress ? createStreamCoalescer(config.onProgress) : undefined;
-        const watchdog = config.onProgress ? createStallWatchdog(config.onProgress) : undefined;
+        const coalescer = config.onProgress ? createProgressCoalescer(config.onProgress) : undefined;
+        const todoTracker = config.onProgress ? createTodoTracker() : undefined;
         let onAbort;
         const finish = (result) => {
             if (settled)
                 return;
             settled = true;
             clearTimeout(timer);
-            coalescer?.flush();
             coalescer?.stop();
-            watchdog?.stop();
             config.signal?.removeEventListener('abort', onAbort);
             resolve(result);
         };
@@ -262,7 +245,6 @@ export function runKimi(config) {
             stdout = appendCapped(stdout, chunk.toString('utf-8'), MAX_CAPTURE_CHARS);
             if (!config.onProgress)
                 return;
-            watchdog?.ping();
             streamBuffer += chunk.toString('utf-8');
             const lines = streamBuffer.split(/\r?\n/);
             streamBuffer = lines.pop() ?? '';
@@ -275,28 +257,40 @@ export function runKimi(config) {
                     if (record.type === 'plan') {
                         const text = contentToText(record.content).trim();
                         if (text)
-                            config.onProgress(makeEvent('plan', text));
+                            coalescer?.add('plan', text);
                     }
                     else if (record.role === 'assistant') {
                         const text = contentToText(record.content);
                         if (text.trim())
-                            coalescer?.add(text);
+                            coalescer?.add('message', text);
                         const toolCalls = record.tool_calls;
                         if (Array.isArray(toolCalls)) {
                             for (const toolCall of toolCalls) {
                                 const toolText = formatCliToolCall(toolCall);
                                 if (toolText)
-                                    config.onProgress(makeEvent('tool_call', toolText));
+                                    coalescer?.add('tool_call', toolText);
                             }
                         }
                     }
+                    else if (record.role === 'tool') {
+                        const text = contentToText(record.content);
+                        const todos = parseCliTodoSnapshot(text);
+                        if (todos && todoTracker?.update(todos)) {
+                            coalescer?.add('todo', todoTracker.getSummary(), { todoFullList: todoTracker.getFullList() });
+                        }
+                    }
                 }
                 catch {
                     // Ignore non-JSON status lines.
                 }
             }
         });
-        proc.stderr?.on('data', (chunk) => { stderr = appendCapped(stderr, chunk.toString('utf-8'), MAX_CAPTURE_CHARS); });
+        proc.stderr?.on('data', (chunk) => {
+            // Kimi CLI 0.20.1 does not stream thinking to stderr incrementally during a
+            // -p run; stderr is empty until process exit. We therefore do not emit live
+            // `thought` progress events here and keep the existing end-of-run capture.
+            stderr = appendCapped(stderr, chunk.toString('utf-8'), MAX_CAPTURE_CHARS);
+        });
         proc.on('error', (err) => {
             finish({ ok: false, text: '', error: err instanceof Error ? err.message : String(err) });
         });

package/dist/progress.js

@@ -7,20 +7,262 @@ const KIND_GLYPH = {
     tool_update: '⚙',
     plan: '◇',
     stall: '⚠',
+    todo: '☑',
 };
 function clockFromIso(iso) {
     // HH:MM:SS in local time; falls back to the raw value if it is not a valid date.
     const date = new Date(iso);
     return Number.isNaN(date.getTime()) ? iso : date.toTimeString().slice(0, 8);
 }
-export function makeEvent(kind, text) {
-    return { kind, text, at: new Date().toISOString() };
+export function makeEvent(kind, text, metadata) {
+    return { kind, text, at: new Date().toISOString(), metadata };
 }
 // One compact line per event for the background task log, e.g.
 // `[12:01:07] ⚙ tool: edit src/index.ts`.
 export function formatProgressLine(event) {
     return `[${clockFromIso(event.at)}] ${KIND_GLYPH[event.kind]} ${event.kind}: ${event.text}`;
 }
+// Task-log variant: for TODO events, append the full multi-line list so the
+// accumulating background log contains complete snapshots, while live progress
+// surfaces only the compact one-line summary.
+export function formatTaskLogLine(event) {
+    const base = formatProgressLine(event);
+    const fullList = event.metadata?.todoFullList;
+    if (event.kind === 'todo' && fullList) {
+        return `${base}\n${fullList.split('\n').map((line) => `    ${line}`).join('\n')}`;
+    }
+    return base;
+}
+const TODO_STATUS_MARKERS = {
+    done: '✓',
+    in_progress: '·',
+    pending: '·',
+};
+export function formatTodoSummary(items) {
+    if (items.length === 0)
+        return 'TODO 0/0';
+    const done = items.filter((i) => i.status === 'done').length;
+    const markers = items.map((i) => TODO_STATUS_MARKERS[i.status]).join('');
+    const current = items.find((i) => i.status === 'in_progress');
+    const now = current ? ` · now: ${current.text}` : '';
+    return `TODO ${done}/${items.length} ${markers}${now}`;
+}
+export function formatTodoFullList(items) {
+    if (items.length === 0)
+        return '(empty todo list)';
+    return items.map((i) => `[${i.status}] ${i.text}`).join('\n');
+}
+export function createTodoTracker() {
+    let items = [];
+    const sameItems = (a, b) => {
+        if (a.length !== b.length)
+            return false;
+        return a.every((item, idx) => item.text === b[idx].text && item.status === b[idx].status);
+    };
+    return {
+        update(next) {
+            if (sameItems(items, next))
+                return false;
+            items = next.map((i) => ({ text: i.text.trim(), status: i.status }));
+            return true;
+        },
+        getItems() {
+            return items;
+        },
+        getSummary() {
+            return formatTodoSummary(items);
+        },
+        getFullList() {
+            return formatTodoFullList(items);
+        },
+        clear() {
+            items = [];
+        },
+    };
+}
+const TODO_SNAPSHOT_MARKER = 'Current todo list:';
+const TODO_BOILERPLATE_MARKER = 'Ensure that you continue to use the todo list';
+// Parses the human-readable snapshot that Kimi's TodoList tool returns in CLI
+// `role:tool` results and in ACP `tool_call_update` content.
+export function parseCliTodoSnapshot(text) {
+    const markerIndex = text.indexOf(TODO_SNAPSHOT_MARKER);
+    if (markerIndex < 0)
+        return undefined;
+    const start = markerIndex + TODO_SNAPSHOT_MARKER.length;
+    const raw = text.slice(start);
+    // Stop before the trailing boilerplate if present.
+    const end = raw.indexOf(TODO_BOILERPLATE_MARKER);
+    const section = (end < 0 ? raw : raw.slice(0, end)).trim();
+    if (!section)
+        return undefined;
+    const items = [];
+    for (const line of section.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        const match = trimmed.match(/^\[(done|in_progress|pending)\]\s*(.+)$/) ?? trimmed.match(/^(done|in_progress|pending):\s*(.+)$/i);
+        if (!match) {
+            // First non-matching blank line is tolerated; a second non-matching line
+            // marks the end of the list.
+            if (items.length > 0)
+                break;
+            continue;
+        }
+        const status = match[1].toLowerCase();
+        const text = match[2].trim();
+        if (text)
+            items.push({ status, text });
+    }
+    return items.length > 0 ? items : undefined;
+}
+// Parses either a JSON `{"todos":[{"title":"...","status":"..."}]}` payload
+// (common in ACP `tool_call_update`) or a human-readable snapshot.
+export function parseAcpTodoPayload(text) {
+    const trimmed = text.trim();
+    if (trimmed.startsWith('{')) {
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                const record = parsed;
+                const todos = record.todos ?? record.items ?? record.plan;
+                if (Array.isArray(todos)) {
+                    const items = [];
+                    for (const entry of todos) {
+                        if (!entry || typeof entry !== 'object')
+                            continue;
+                        const e = entry;
+                        const text = typeof e.title === 'string' ? e.title : typeof e.content === 'string' ? e.content : typeof e.text === 'string' ? e.text : '';
+                        const rawStatus = typeof e.status === 'string' ? e.status.toLowerCase() : 'pending';
+                        const status = rawStatus === 'done' || rawStatus === 'completed' || rawStatus === 'complete' ? 'done' : rawStatus === 'in_progress' || rawStatus === 'in progress' || rawStatus === 'active' ? 'in_progress' : 'pending';
+                        if (text.trim())
+                            items.push({ text: text.trim(), status });
+                    }
+                    if (items.length > 0)
+                        return items;
+                }
+            }
+        }
+        catch {
+            // Fall through to snapshot parsing.
+        }
+    }
+    return parseCliTodoSnapshot(text);
+}
+export const DEFAULT_DWELL_MS = 1_200;
+export const DEFAULT_TODO_PRIORITY_MS = 5_000;
+export const PREVIEW_MAX_CHARS = 90;
+export const TAIL_MAX_CHARS = 120;
+function sliceByCodePoints(text, maxChars) {
+    return [...text].slice(-maxChars).join('');
+}
+function collapseWhitespace(text) {
+    return text.replace(/\s+/g, ' ').trim();
+}
+function formatPreview(tail, maxChars) {
+    const preview = collapseWhitespace(tail);
+    if (preview.length === 0)
+        return '';
+    const codePoints = [...preview];
+    if (codePoints.length <= maxChars)
+        return preview;
+    return `…${codePoints.slice(-maxChars).join('').trimStart()}`;
+}
+// Coalesces high-frequency `message`/`thought` streaming text into a single
+// watchable preview line, emitted at most once per `dwellMs`. Action events
+// (`tool_call`, `tool_update`, `plan`) are forwarded immediately, after flushing
+// any pending preview so ordering is preserved. `todo` events are also immediate
+// and start a short priority window during which `message`/`thought` previews are
+// suppressed so the checklist line stays readable.
+export function createProgressCoalescer(reporter, options) {
+    const dwellMs = options?.dwellMs ?? DEFAULT_DWELL_MS;
+    const previewMaxChars = options?.previewMaxChars ?? PREVIEW_MAX_CHARS;
+    const tailMaxChars = options?.tailMaxChars ?? TAIL_MAX_CHARS;
+    const todoPriorityMs = options?.todoPriorityMs ?? DEFAULT_TODO_PRIORITY_MS;
+    const tails = { message: '', thought: '' };
+    let timer;
+    let priorityTimer;
+    let priorityUntil = 0;
+    const emitTails = () => {
+        for (const kind of ['message', 'thought']) {
+            const tail = tails[kind];
+            if (!tail)
+                continue;
+            const text = formatPreview(tail, previewMaxChars);
+            tails[kind] = '';
+            if (text)
+                reporter(makeEvent(kind, text));
+        }
+    };
+    const flush = () => {
+        if (timer) {
+            clearTimeout(timer);
+            timer = undefined;
+        }
+        emitTails();
+    };
+    const clearPriority = () => {
+        priorityUntil = 0;
+        if (priorityTimer) {
+            clearTimeout(priorityTimer);
+            priorityTimer = undefined;
+        }
+    };
+    const schedule = () => {
+        if (timer)
+            return;
+        const now = Date.now();
+        if (now < priorityUntil) {
+            // Message/thought previews are deferred while a TODO line is on screen.
+            // Arm a single timer that will emit the accumulated tail once the window
+            // expires; additional streaming text during the window only updates tails.
+            if (!priorityTimer) {
+                priorityTimer = setTimeout(() => {
+                    priorityTimer = undefined;
+                    priorityUntil = 0;
+                    emitTails();
+                }, priorityUntil - now);
+                priorityTimer.unref?.();
+            }
+            return;
+        }
+        timer = setTimeout(() => {
+            timer = undefined;
+            emitTails();
+        }, dwellMs);
+        timer.unref?.();
+    };
+    const appendTail = (kind, text) => {
+        tails[kind] = sliceByCodePoints(tails[kind] + text, tailMaxChars);
+    };
+    const add = (kind, text, metadata) => {
+        if (kind === 'tool_call' || kind === 'tool_update' || kind === 'plan') {
+            // During a TODO priority window, action events still surface but chatty
+            // message/thought previews stay suppressed so the checklist remains visible.
+            if (Date.now() < priorityUntil) {
+                reporter(makeEvent(kind, text));
+                return;
+            }
+            flush();
+            reporter(makeEvent(kind, text));
+            return;
+        }
+        if (kind === 'todo') {
+            flush();
+            clearPriority();
+            priorityUntil = Date.now() + todoPriorityMs;
+            reporter(makeEvent(kind, text, metadata));
+            schedule();
+            return;
+        }
+        if (kind === 'message' || kind === 'thought') {
+            appendTail(kind, text);
+            schedule();
+        }
+    };
+    const stop = () => {
+        clearPriority();
+        flush();
+    };
+    return { add, flush, stop };
+}
 export function createStallWatchdog(reporter, stallMs = DEFAULT_STALL_MS) {
     let timer;
     let stopped = false;

package/dist/transports/acp.js

@@ -4,7 +4,7 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { buildKimiEnv, resolveKimiPaths } from '../environment.js';
 import { VERSION } from '../version.js';
-import { createStallWatchdog, makeEvent } from '../progress.js';
+import { createProgressCoalescer, createStallWatchdog, createTodoTracker, parseAcpTodoPayload } from '../progress.js';
 const MAX_ACP_FRAME_BYTES = 8 * 1024 * 1024;
 const MAX_ACP_HEADER_BYTES = 16 * 1024;
 const MAX_ACP_METADATA_BYTES = 100 * 1024;
@@ -551,43 +551,6 @@ function extractSessionId(value, fallback) {
     }
     return fallback;
 }
-const COALESCE_MS = 750;
-const COALESCE_CHARS = 400;
-// Streams of message/thought tokens are far too chatty to forward one event per
-// chunk. Accumulate character counts and emit a single summarized event at most
-// every COALESCE_MS or whenever the accumulated text exceeds COALESCE_CHARS.
-// tool_call / tool_call_update / plan events are forwarded immediately.
-function createCoalescingReporter(reporter) {
-    const counts = { message: 0, thought: 0 };
-    let timer;
-    const flush = () => {
-        if (timer) {
-            clearTimeout(timer);
-            timer = undefined;
-        }
-        for (const kind of ['message', 'thought']) {
-            if (counts[kind] > 0) {
-                reporter(makeEvent(kind, `${kind === 'message' ? 'streaming output' : 'thinking'}… (${counts[kind]} chars)`));
-                counts[kind] = 0;
-            }
-        }
-    };
-    const add = (kind, text) => {
-        if (kind !== 'message' && kind !== 'thought') {
-            flush();
-            reporter(makeEvent(kind, text));
-            return;
-        }
-        counts[kind] += text.length;
-        if (counts[kind] >= COALESCE_CHARS) {
-            flush();
-        }
-        else if (!timer) {
-            timer = setTimeout(flush, COALESCE_MS);
-        }
-    };
-    return { add, flush, stop: flush };
-}
 export async function runAcpPrompt(options) {
     if (options.signal?.aborted)
         return { ok: false, text: '', error: 'ACP prompt was aborted before start.' };
@@ -603,10 +566,12 @@ export async function runAcpPrompt(options) {
     }
     let coalescer;
     let watchdog;
+    let todoTracker;
     let onNotification;
     if (options.onProgress) {
-        coalescer = createCoalescingReporter(options.onProgress);
+        coalescer = createProgressCoalescer(options.onProgress);
         watchdog = createStallWatchdog(options.onProgress);
+        todoTracker = createTodoTracker();
         onNotification = (message) => {
             watchdog?.ping();
             const params = message.params;
@@ -623,6 +588,10 @@ export async function runAcpPrompt(options) {
                 case 'tool_call_update':
                 case 'plan': {
                     const text = extractAcpText(update?.content) || JSON.stringify(update);
+                    const todos = parseAcpTodoPayload(text);
+                    if (todos && todoTracker?.update(todos)) {
+                        coalescer?.add('todo', todoTracker.getSummary(), { todoFullList: todoTracker.getFullList() });
+                    }
                     const kind = updateType === 'tool_call' ? 'tool_call' : updateType === 'tool_call_update' ? 'tool_update' : 'plan';
                     coalescer?.add(kind, text);
                     break;
@@ -676,7 +645,6 @@ export async function runAcpPrompt(options) {
     finally {
         if (onNotification)
             client.off('notification', onNotification);
-        coalescer?.flush();
         coalescer?.stop();
         watchdog?.stop();
         options.signal?.removeEventListener('abort', abort);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ladder-mcp",
-  "version": "1.1.2",
+  "version": "1.1.5",
   "description": "Windows-first MCP bridge for Kimi Code CLI v24",
   "license": "MIT",
   "type": "module",