thincoder 0.8.10 → 0.8.12

package/src/tools/checklist.mjs

@@ -0,0 +1,114 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs"
+import { join, dirname } from "node:path"
+import { DESC } from "./shared.mjs"
+
+const CHECKLIST = "checklist.md"
+const DONE = "checklist-done.md"
+
+function checklistPath(cwd) { return join(cwd, ".thincoder", CHECKLIST) }
+function donePath(cwd) { return join(cwd, ".thincoder", DONE) }
+
+/** Parse checklist file into array of { index, status, text } */
+function parse(filePath) {
+  if (!existsSync(filePath)) return []
+  const lines = readFileSync(filePath, "utf-8").split("\n")
+  const items = []
+  let idx = 0
+  for (const line of lines) {
+    const m = line.match(/^- \[(.)\] (.+)$/)
+    if (m) {
+      idx++
+      const raw = m[1]
+      const status = raw === "x" ? "done" : raw === "~" ? "in_progress" : "pending"
+      items.push({ index: idx, status, text: m[2].trim() })
+    }
+  }
+  return items
+}
+
+/** Write items back to file */
+function write(filePath, items) {
+  mkdirSync(dirname(filePath), { recursive: true })
+  const lines = []
+  for (const item of items) {
+    const mark = item.status === "done" ? "x" : item.status === "in_progress" ? "~" : " "
+    lines.push(`- [${mark}] ${item.text}`)
+  }
+  writeFileSync(filePath, lines.join("\n") + "\n")
+}
+
+/** Parse pending items only (for context injection) */
+export function pendingItems(cwd) {
+  return parse(checklistPath(cwd)).filter(i => i.status !== "done")
+}
+
+export const checklistTool = {
+  name: "checklist",
+  description: DESC("checklist"),
+  parameters: {
+    type: "object",
+    properties: {
+      action: {
+        type: "string",
+        enum: ["add", "mark", "list"],
+        description: "add a new item / mark item status / list all items"
+      },
+      item: {
+        type: "string",
+        description: "Item text (required for add)"
+      },
+      index: {
+        type: "number",
+        description: "1-based item index (required for mark)"
+      },
+      status: {
+        type: "string",
+        enum: ["pending", "in_progress", "done"],
+        description: "New status (required for mark)"
+      },
+    },
+    required: ["action"],
+  },
+  readonly: false,
+  execute(args, ctx) {
+    switch (args.action) {
+      case "add": {
+        if (!args.item || typeof args.item !== "string") return "Error: 'item' is required for add"
+        const items = parse(checklistPath(ctx.cwd))
+        items.push({ index: items.length + 1, status: "pending", text: args.item })
+        write(checklistPath(ctx.cwd), items)
+        return `Added: [ ] ${args.item}`
+      }
+      case "mark": {
+        if (args.index == null) return "Error: 'index' is required for mark"
+        const status = args.status
+        if (!status || !["pending", "in_progress", "done"].includes(status)) return "Error: 'status' is required (pending|in_progress|done)"
+        const cp = checklistPath(ctx.cwd)
+        const items = parse(cp)
+        if (args.index < 1 || args.index > items.length) return `Error: index ${args.index} out of range (1-${items.length})`
+        const item = items[args.index - 1]
+        const old = item.status
+        if (old === status) return `Already ${status}: ${item.text}`
+        item.status = status
+        if (status === "done") {
+          // Move to done file
+          const dp = donePath(ctx.cwd)
+          const doneItems = parse(dp)
+          doneItems.push(item)
+          write(dp, doneItems)
+          items.splice(args.index - 1, 1)
+        }
+        write(cp, items)
+        return `Marked #${args.index} ${old} → ${status}: ${item.text}`
+      }
+      case "list": {
+        const items = parse(checklistPath(ctx.cwd))
+        if (items.length === 0) return "(checklist is empty)"
+        const marks = { pending: " ", in_progress: "~", done: "x" }
+        return items.map(i => `- [${marks[i.status]}] ${i.text}`).join("\n")
+      }
+      default:
+        return `Error: unknown action '${args.action}'`
+    }
+  },
+}

package/src/tools/file.mjs

@@ -7,6 +7,8 @@ import {
   resolveInCwd,
   resolveExternal,
 } from "./shared.mjs";
+import { specForModel } from "../config.mjs";
+import { createHash } from "node:crypto";
 import { mkdir } from "node:fs/promises";
 import { readFile } from "node:fs/promises";
 import { stat } from "node:fs/promises";
@@ -27,6 +29,7 @@ export const readTool = {
       offset: { type: "number", description: "1-based line number to start from" },
       limit: { type: "number", description: `Max lines to return (default ${MAX_READ_LINES})` },
       allowExternal: { type: "boolean", description: "Allow reading files outside the working directory. Only set true when the user explicitly provided an external path — never use this to explore beyond cwd on your own." },
+      hashes: { type: "boolean", description: "Include SHA256 line hashes for hash-based editing (default false). Use when you plan to edit the file with hashline_edit." },
     },
     required: ["path"],
   },
@@ -41,7 +44,14 @@ export const readTool = {
     const offset = Math.max(1, args.offset ?? 1)
     const limit = Math.min(args.limit ?? MAX_READ_LINES, MAX_READ_LINES)
     const slice = lines.slice(offset - 1, offset - 1 + limit)
-    const numbered = slice.map((l, i) => `${offset + i}\t${l}`).join("\n")
+    const numbered = slice.map((l, i) => {
+      const ln = offset + i
+      if (args.hashes) {
+        const h = createHash("sha256").update(l).digest("hex").slice(0, 12)
+        return `${ln}\t[${h}] ${l}`
+      }
+      return `${ln}\t${l}`
+    }).join("\n")
     const suffix = offset - 1 + limit < lines.length ? `\n... (${lines.length} lines total, use offset to continue)` : ""
     return truncate(numbered + suffix)
   },
@@ -65,6 +75,15 @@ export const readImageTool = {
   multimodal: true, // returns JSON { text, images } — agent loop converts to multimodal user message
   /** Returns JSON: { text, images }, for the agent layer to convert into multimodal user messages */
   async execute(args, ctx) {
+    // Vision capability gate: injecting an image into a text-only model's history poisons the whole
+    // conversation (every subsequent request 400s on the image part). Refuse before reading the file.
+    const model = ctx.agent?.provider?.model
+    if (model && !specForModel(model).multimodal) {
+      throw new Error(
+        `Model "${model}" does not support image input — read_image is unavailable with this provider. ` +
+        `Verify visual output programmatically (file size, dimensions, pixel checks via code) or ask the user to switch to a vision-capable provider.`
+      )
+    }
     const abs = resolveInCwd(ctx, args.path)
     const ext = abs.slice(abs.lastIndexOf(".") + 1).toLowerCase()
     const mime = IMAGE_EXTENSIONS[ext]
@@ -209,3 +228,65 @@ export const insertAfterTool = {
   },
 }
 
+// ---------------------------------------------------------------- hashline_edit
+
+/**
+ * Compute a 12-char hex SHA256 hash for a line (exact content, no trimming).
+ * Used by both read (hashes=true) and hashline_edit for hash-based matching.
+ */
+export function hashLine(content) {
+  return createHash("sha256").update(content).digest("hex").slice(0, 12)
+}
+
+export const hashlineEditTool = {
+  name: "hashline_edit",
+  description: DESC("hashline_edit"),
+  parameters: {
+    type: "object",
+    properties: {
+      path: { type: "string", description: "File path" },
+      old_hashes: { type: "array", items: { type: "string" }, description: "SHA256 hashes (12 chars) of the lines to replace. Read the file with hashes=true first to obtain these hashes. Single line: pass 1 hash; multiple lines: pass the exact sequence of hashes." },
+      new_content: { type: "string", description: "Replacement text (can span multiple lines)" },
+    },
+    required: ["path", "old_hashes", "new_content"],
+  },
+  readonly: false,
+  async execute(args, ctx) {
+    const abs = resolveInCwd(ctx, args.path)
+    if (!args.old_hashes?.length) throw new Error("old_hashes must not be empty — read the file with hashes=true to get line hashes")
+    const content = await readFile(abs, "utf8")
+    const lines = content.split("\n")
+    const fileHashes = lines.map((l) => hashLine(l))
+    const target = args.old_hashes
+
+    // Sliding-window match: find the exact sequence of hashes
+    let pos = -1
+    for (let i = 0; i <= fileHashes.length - target.length; i++) {
+      let match = true
+      for (let j = 0; j < target.length; j++) {
+        if (fileHashes[i + j] !== target[j]) { match = false; break }
+      }
+      if (match) { pos = i; break }
+    }
+
+    if (pos === -1) {
+      // Help the model recover: show the current file hashes for context
+      const maxShow = Math.min(fileHashes.length, 50)
+      const hashDump = fileHashes.slice(0, maxShow).map((h, i) => `${h}  L${i + 1}: ${lines[i].slice(0, 80)}`).join("\n")
+      const preview = target.join(" ")
+      throw new Error(
+        `Hash sequence not found in ${args.path}: ${preview}\n` +
+        `The file may have been modified since you last read it. Current hashes (first ${maxShow} lines):\n${hashDump}`
+      )
+    }
+
+    // Replace: remove old lines, insert new lines at the same position
+    const newLines = args.new_content.split("\n")
+    lines.splice(pos, target.length, ...newLines)
+    const updated = lines.join("\n")
+    await writeFile(abs, updated, "utf8")
+    const diff = gitDiffOne(ctx.cwd, abs)
+    return `Edited ${args.path}: replaced ${target.length} line(s) at L${pos + 1} with ${newLines.length} line(s)${diff ? "\n" + diff : ""}${await autoSyntaxCheck(abs)}`
+  },
+}
+

package/src/tools/hashline_edit.md

@@ -0,0 +1,12 @@
+Edit a file using content-hash addressing instead of string matching. More reliable than edit when whitespace or encoding varies — hashes are computed from exact line bytes on disk.
+
+Parameters:
+- path (required): File path
+- old_hashes (required): Array of SHA256 hashes (12-char hex) identifying lines to replace. Read the file with hashes=true first to obtain these hashes. For a single line, pass [hash]; for a contiguous block, pass [hash1, hash2, ...] in order.
+- new_content (required): Replacement text (multi-line ok, \n separated)
+
+Notes:
+- The hash of each line is computed as SHA256(line_content).slice(0, 12) — the same algorithm used by read(hashes=true)
+- Hashes are position-independent: they identify lines by content, not by line number (which changes after edits)
+- If the hash sequence isn't found, the error will include the current file's hashes so you can retry with corrected values
+- Prefer this over edit when: 1) the file may have mixed whitespace/encoding, 2) you want to edit a block of lines with a single call

package/src/tools/index.mjs

@@ -1,22 +1,26 @@
 // tools/index.mjs — backend-compatible re-export
 export { toOpenAISchema } from "./shared.mjs";
 
-import { readTool, writeTool, editTool, insertAfterTool, readImageTool } from "./file.mjs";
+import { readTool, writeTool, editTool, insertAfterTool, readImageTool, hashlineEditTool } from "./file.mjs";
 import { applyPatchTool, syntaxCheckTool, deleteTool } from "./patch.mjs";
 import { bashTool, globTool, grepTool, lsTool } from "./system.mjs";
 import { websearchTool, fetchTool } from "./web.mjs";
 import { gitDiffTool, gitStatusTool, gitLogTool, questionTool, checkpointTool } from "./git.mjs";
+import { checklistTool } from "./checklist.mjs";
+import { linterTool } from "./linter.mjs";
 
 export const builtinTools = [
-  readTool, writeTool, editTool, insertAfterTool, applyPatchTool,
+  readTool, writeTool, editTool, insertAfterTool, hashlineEditTool, applyPatchTool,
   syntaxCheckTool, readImageTool, bashTool, globTool, grepTool,
   websearchTool, lsTool, fetchTool, deleteTool,
   gitDiffTool, gitStatusTool, gitLogTool, questionTool, checkpointTool,
+  checklistTool, linterTool,
 ];
 
 export {
-  readTool, writeTool, editTool, insertAfterTool, applyPatchTool,
+  readTool, writeTool, editTool, insertAfterTool, hashlineEditTool, applyPatchTool,
   syntaxCheckTool, readImageTool, bashTool, globTool, grepTool,
   websearchTool, lsTool, fetchTool, deleteTool,
   gitDiffTool, gitStatusTool, gitLogTool, questionTool, checkpointTool,
+  checklistTool, linterTool,
 };

package/src/tools/linter.md

@@ -0,0 +1,13 @@
+Run the appropriate linter/checker for a file. Auto-detects based on file extension and project config.
+
+Parameters:
+- path (optional): File to check (default: most recently modified file)
+
+Supported languages:
+- .js/.mjs/.cjs/.jsx: eslint (if config present) → node --check (built-in, always available)
+- .ts/.tsx/.mts/.cts: eslint → tsc --noEmit (if tsconfig.json present) → node --check
+- .py: ruff (if installed)
+- .rs: cargo check (if Cargo.toml present)
+- .go: go vet
+
+Does NOT install anything — only uses tools already available in the project.

package/src/tools/linter.mjs

@@ -0,0 +1,146 @@
+import { DESC, resolveInCwd } from "./shared.mjs"
+
+export const linterTool = {
+  name: "linter",
+  description: DESC("linter"),
+  parameters: {
+    type: "object",
+    properties: {
+      path: { type: "string", description: "File path (default: most recently modified file)" },
+    },
+  },
+  readonly: true,
+  async execute(args, ctx) {
+    const { execFileSync } = await import("node:child_process")
+    const { existsSync } = await import("node:fs")
+    const { join, relative } = await import("node:path")
+    const abs = args.path ? resolveInCwd(ctx, args.path) : (ctx.agent?._touchedFiles?.at(-1) || null)
+    if (!abs) return "linter: no file specified and no recently modified file to check"
+
+    const ext = abs.split(".").pop()?.toLowerCase()
+    const checkers = LANG_CHECKERS[ext]
+    if (!checkers) return `linter: no linter configured for .${ext} files. Supported: ${Object.keys(LANG_CHECKERS).map(e => `.${e}`).join(", ")}`
+
+    for (const checker of checkers) {
+      const result = await checker(abs, { cwd: ctx.cwd, existsSync, execFileSync, join, relative })
+      if (result !== null) return result
+    }
+    return `linter: no linter available for ${args.path || abs}. Install one?`
+  },
+}
+
+// ─── Checker definitions ──────────────────────
+
+async function eslintCheck(file, { cwd, existsSync, execFileSync, join, relative }) {
+  // Walk up to find eslint config
+  let dir = file.split(/[\\/]/).slice(0, -1).join("/") || "."
+  while (true) {
+    for (const cfg of [".eslintrc.js", ".eslintrc.cjs", ".eslintrc.json", ".eslintrc.yaml", ".eslintrc.yml", "eslint.config.js", "eslint.config.mjs"]) {
+      if (existsSync(join(cwd, dir, cfg))) {
+        try {
+          const cfgDir = join(cwd, dir)
+          const relPath = relative(cfgDir, file)
+          execFileSync("npx", ["eslint", "--no-color", "--format", "compact", relPath], {
+            cwd: cfgDir, encoding: "utf8", timeout: 30000, stdio: ["ignore", "pipe", "pipe"],
+          })
+          return "✓ eslint: no issues"
+        } catch (e) {
+          const stdout = (e.stdout || "").trim()
+          if (stdout) return stdout
+          return `✗ eslint: ${(e.stderr || e.message).slice(0, 500)}`
+        }
+      }
+    }
+    const parent = dir.split("/").slice(0, -1).join("/")
+    if (!parent || parent === dir) break
+    dir = parent
+  }
+  return null
+}
+
+async function tscCheck(file, { cwd, existsSync, execFileSync, join }) {
+  if (!existsSync(join(cwd, "tsconfig.json"))) return null
+  if (!/\.(ts|tsx|mts|cts)$/.test(file)) return null
+  try {
+    execFileSync("npx", ["tsc", "--noEmit", "--pretty", "false"], {
+      cwd, encoding: "utf8", timeout: 60000, stdio: ["ignore", "pipe", "pipe"],
+    })
+    return "✓ tsc: no type errors"
+  } catch (e) {
+    const stdout = (e.stdout || "").trim()
+    if (stdout) return stdout
+    return `✗ tsc: ${(e.stderr || e.message).slice(0, 500)}`
+  }
+}
+
+async function nodeCheck(file, { execFileSync, cwd }) {
+  if (!/\.(m?js|cjs)$/.test(file)) return null
+  try {
+    execFileSync(process.execPath, ["--check", file], {
+      cwd, encoding: "utf8", timeout: 10000, stdio: ["ignore", "pipe", "pipe"],
+    })
+    return "✓ node --check: Syntax OK"
+  } catch (e) {
+    return `✗ node --check: ${(e.stderr || e.message).slice(0, 500)}`
+  }
+}
+
+async function ruffCheck(file, { cwd, execFileSync }) {
+  if (!/\.py$/.test(file)) return null
+  try {
+    execFileSync("ruff", ["check", "--output-format", "concise", file], {
+      cwd, encoding: "utf8", timeout: 30000, stdio: ["ignore", "pipe", "pipe"],
+    })
+    return "✓ ruff: no issues"
+  } catch (e) {
+    if (e.code === "ENOENT") return "linter: ruff not installed. Run: pip install ruff"
+    const stdout = (e.stdout || "").trim()
+    if (stdout) return stdout
+    return `✗ ruff: ${(e.stderr || e.message).slice(0, 500)}`
+  }
+}
+
+async function cargoCheck(file, { cwd, existsSync, execFileSync, join }) {
+  if (!/\.rs$/.test(file)) return null
+  if (!existsSync(join(cwd, "Cargo.toml"))) return null
+  const fname = file.split(/[\\/]/).pop()
+  try {
+    const out = execFileSync("cargo", ["check", "--message-format", "short"], {
+      cwd, encoding: "utf8", timeout: 120000, stdio: ["ignore", "pipe", "pipe"],
+    })
+    const errors = out.split("\n").filter(l => l.includes(fname))
+    return errors.length > 0 ? errors.join("\n") : "✓ cargo check: no errors"
+  } catch (e) {
+    const combined = ((e.stdout || "") + "\n" + (e.stderr || "")).trim()
+    const errors = combined.split("\n").filter(l => l.includes(fname) || l.startsWith("error"))
+    return errors.length > 0 ? errors.join("\n") : `✗ cargo check failed:\n${combined.slice(0, 1000)}`
+  }
+}
+
+async function goVet(file, { cwd, execFileSync }) {
+  if (!/\.go$/.test(file)) return null
+  try {
+    execFileSync("go", ["vet", file], {
+      cwd, encoding: "utf8", timeout: 60000, stdio: ["ignore", "pipe", "pipe"],
+    })
+    return "✓ go vet: no issues"
+  } catch (e) {
+    return `✗ go vet: ${(e.stderr || e.message).slice(0, 500)}`
+  }
+}
+
+// ─── Language → checkers (first available wins) ──
+
+const LANG_CHECKERS = {
+  js:  [eslintCheck, nodeCheck],
+  mjs: [eslintCheck, nodeCheck],
+  cjs: [eslintCheck, nodeCheck],
+  jsx: [eslintCheck, nodeCheck],
+  ts:  [eslintCheck, tscCheck],
+  tsx: [eslintCheck, tscCheck],
+  mts: [eslintCheck, tscCheck],
+  cts: [eslintCheck, tscCheck],
+  py:  [ruffCheck],
+  rs:  [cargoCheck],
+  go:  [goVet],
+}

package/src/tools/read.md

@@ -1,10 +1,11 @@
 Read a text file. Returns numbered lines. Use offset/limit to page large files.
-
 Parameters:
-- path (required): File path, relative to cwd or absolute
+- path (required): File path, relative to cwd or absolute (alias: filePath)
 - offset: 1-based line number to start reading from
 - limit: Max lines to return (default 2000)
+- hashes: Include SHA256 content hashes per line (for hashline_edit). Set true before using hashline_edit.
 
 Notes:
 - Always prefer this over `cat` or shell-based reading — it caps output and avoids large dumps
 - Use offset for pagination when the file is large
+- When you plan to edit the file, set hashes=true to get line hashes for hashline_edit — hash-based editing avoids whitespace/encoding matching failures

package/src/tools/repomap.mjs

@@ -3,7 +3,8 @@
  * Real-time import/export parsing, generates compact text for LLMs to understand code structure.
  * No index stored — reads and parses files on each call, ~50ms.
  */
-import { readFileSync, existsSync } from "node:fs"
+import { existsSync } from "node:fs"
+import { readFile } from "node:fs/promises"
 import { join } from "node:path"
 
 /** Extract JS/TS file import paths (normalize by stripping .ts/.js/.mjs suffixes) */
@@ -113,17 +114,19 @@ function normalizeExt(p) {
  * Internal: scan all files, build forward dependency graph + reverse reference graph.
  * Returns { deps, importers, fileCount } shared by buildOutline / buildSummary.
  */
-function _buildDepGraph(db, cwd) {
+async function _buildDepGraph(db, cwd) {
   const allFiles = db.prepare(`SELECT DISTINCT path FROM code_chunks ORDER BY path`).all().map((r) => r.path)
   if (allFiles.length === 0) return null
 
   const deps = new Map()      // path → { imports: Set, exports: Set, size: number, dir: string }
   const importers = new Map() // importee → Set<importer>
 
-  for (const rel of allFiles) {
+  for (let i = 0; i < allFiles.length; i++) {
+    const rel = allFiles[i]
     const abs = join(cwd, ...rel.split("/"))
     if (!existsSync(abs)) continue
-    const text = readFileSync(abs, "utf8")
+    let text
+    try { text = await readFile(abs, "utf8") } catch { continue }
     const lines = text.split("\n")
     const ext = rel.slice(rel.lastIndexOf(".")).toLowerCase()
 
@@ -160,6 +163,8 @@ function _buildDepGraph(db, cwd) {
       if (!importers.has(r)) importers.set(r, new Set())
       importers.get(r).add(rel)
     }
+    // Yield the event loop every 20 files to prevent TUI freeze
+    if (i % 20 === 19) await new Promise(r => setImmediate(r))
   }
 
   return { deps, importers, fileCount: allFiles.length }
@@ -173,8 +178,8 @@ function _buildDepGraph(db, cwd) {
  *  3. Entry points (files with no importers — startup/top-level entry points)
  * Output is naturally bounded (~1000-2000 chars), no more OUTLINE_INJECT_MAX hard truncation.
  */
-export function buildSummary(db, cwd) {
-  const graph = _buildDepGraph(db, cwd)
+export async function buildSummary(db, cwd) {
+  const graph = await _buildDepGraph(db, cwd)
   if (!graph) return "(no indexed source files; run codeSync or /reindex first)"
   const { deps, importers, fileCount } = graph
 
@@ -248,8 +253,8 @@ export function buildSummary(db, cwd) {
 }
 
 /** Get known file list from code_chunks (reuse index), parse by path to generate outline text */
-export function buildOutline(db, cwd, focusPath) {
-  const graph = _buildDepGraph(db, cwd)
+export async function buildOutline(db, cwd, focusPath) {
+  const graph = await _buildDepGraph(db, cwd)
   if (!graph) return "(no indexed source files; run codeSync or /reindex first)"
   const { deps, importers } = graph
 
@@ -298,7 +303,7 @@ export function repoOutlineTool(db, cwd) {
     },
     readonly: true,
     async execute(args) {
-      const outline = buildOutline(db, cwd, args.path ?? null)
+      const outline = await buildOutline(db, cwd, args.path ?? null)
       return outline
     },
   }

package/src/tui/agent-turn.mjs

@@ -30,6 +30,7 @@ export async function runAgentTurn(ctx, text) {
   state.currentTool = null
   state.processingStarted = Date.now()
   state.controller = new AbortController()
+  state.interruptPrompt = null
   // Refresh status bar every second during processing (elapsed timer)
   const ticker = setInterval(() => {
     if (state.processing) render()
@@ -179,10 +180,13 @@ export async function runAgentTurn(ctx, text) {
       state.tokens.completion += usage.completion_tokens ?? 0
       state.tokens.cacheHit += usage.prompt_cache_hit_tokens ?? 0
       state.tokens.cacheMiss += usage.prompt_cache_miss_tokens ?? 0
+      state.tokens.reasoningTokens += usage.completion_tokens_details?.reasoning_tokens ?? 0
     },
     // Throttle wait (active gate / 429 backoff): show in status bar so user knows it's not frozen
     onWait: ({ phase, seconds }) => {
-      state.status = phase === "gate" ? `TPM throttle wait ~${seconds}s` : `Rate-limited 429, retry in ${seconds}s`
+      if (phase === "gate") state.status = `TPM throttle wait ~${seconds}s`
+      else if (phase === "overloaded") state.status = `Server overloaded, retrying in ${seconds}s`
+      else state.status = `Rate-limited 429, retry in ${seconds}s`
       render()
     },
     onTaskUpdate: (items) => {
@@ -193,12 +197,15 @@ export async function runAgentTurn(ctx, text) {
       pushLine(`  [task] ${done}/${items.length}${current ? ` ▶ ${current.title}` : ""}`, C.dim)
       render()
     },
+    onAdvisor: (note) => {
+      pushLine(`  [advisor] ${note.replace(/\n/g, "\n  ")}`, C.advisor)
+    },
     // Incremental save: flush to disk every 5 tool turns — mid-crash loss window shrinks from an entire round to a few turns
     onTurnEnd: (() => {
       let n = 0
       return () => {
         if (++n % 5 !== 0) return
-        try { saveSession(agent, state.lines) } catch {}
+        try { saveSession(agent, state.lines) } catch (e) { console.error(`[session] incremental save failed: ${e.message}`) }
       }
     })(),
   }

package/src/tui/ansi.mjs

@@ -33,4 +33,5 @@ export const C = {
   error: ansi.fg(1),
   dim: ansi.gray,
   warn: ansi.fg(3),
+  advisor: `${ESC}[92m`,  // bright green — visible on dark backgrounds
 }

package/src/tui/cmd-advisor.mjs

@@ -0,0 +1,68 @@
+/** /advisor command: toggle advisor on/off, select model.
+ *  ctx: { agent, openPicker, pushLine } */
+import { C } from "./ansi.mjs"
+
+export async function handleAdvisorCommand(ctx) {
+  const { agent, openPicker, pushLine } = ctx
+  const cfg = agent.config.advisor ??= {}
+  const enabled = cfg.enabled === true
+  const curProvider = cfg.provider || agent.activeProvider
+  const curModel = cfg.model || agent.provider.model
+
+  const entries = [
+    { type: "item", text: `Advisor: ${enabled ? "ON" : "OFF"}`, action: "toggle" },
+    { type: "item", text: `Model: ${curProvider}/${curModel}`, action: "model" },
+  ]
+
+  openPicker({
+    title: "Advisor",
+    entries,
+    onSelect: async (e) => {
+      if (e.action === "toggle") {
+        cfg.enabled = !cfg.enabled
+        agent._pendingReminders = agent._pendingReminders ?? []
+        if (cfg.enabled) {
+          agent._pendingReminders.push("[系统提醒: Advisor 审查已开启。每轮操作后，你的输出将被审查，观察结果可能作为系统提醒注入。请批判性参考——这是观察，不是命令。]")
+        } else {
+          agent._pendingReminders.push("[系统提醒: Advisor 审查已关闭。后续轮次不再自动审查。]")
+        }
+      } else if (e.action === "model") {
+        await openAdvisorModelPicker(ctx).catch(err => pushLine(`[error] ${err.message}`, C.error))
+      }
+    },
+  })
+}
+
+async function openAdvisorModelPicker(ctx) {
+  const { agent, openPicker, pushLine } = ctx
+  const providers = agent.providers || []
+
+  // Build flat list: each provider's name + a "use current model" entry
+  const entries = []
+  let idx = 0
+  for (const p of providers) {
+    const mark = p.name === agent.activeProvider ? "* " : "  "
+    entries.push({ type: "item", text: `${mark}${p.name} — ${p.baseURL}`, action: "set_provider", provider: p.name, model: p.model })
+    idx++
+  }
+
+  openPicker({
+    title: "Advisor Model",
+    entries,
+    onSelect: async (e) => {
+      if (e.action === "set_provider") {
+        const cfg = agent.config.advisor ??= {}
+        if (e.provider === agent.activeProvider && e.model === agent.provider.model) {
+          // Same as main — clear override (use main pool)
+          delete cfg.provider
+          delete cfg.model
+          pushLine(`Advisor: 使用主模型 (${agent.activeProvider}/${agent.provider.model})`)
+        } else {
+          cfg.provider = e.provider
+          cfg.model = e.model
+          pushLine(`Advisor: ${e.provider}/${e.model}`)
+        }
+      }
+    },
+  })
+}