@pencil-agent/nano-pencil 1.13.8 → 1.13.9

package/dist/build-meta.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.13.8",
-  "commitHash": "66ecf7f",
+  "version": "1.13.9",
+  "commitHash": "593bf56",
   "branch": "main",
-  "builtAt": "2026-04-26T15:41:55.811Z"
+  "builtAt": "2026-04-26T17:04:12.832Z"
 }

package/dist/builtin-extensions.js

@@ -24,6 +24,7 @@ const BUNDLED_SAL_EXTENSION = join(__dirname, "extensions", "defaults", "sal", "
 const BUNDLED_GRUB_EXTENSION = join(__dirname, "extensions", "defaults", "grub", "index.js");
 const BUNDLED_SUBAGENT_EXTENSION = join(__dirname, "extensions", "defaults", "subagent", "index.js");
 const BUNDLED_TEAM_EXTENSION = join(__dirname, "extensions", "defaults", "team", "index.js");
+const BUNDLED_IDLE_THINK_EXTENSION = join(__dirname, "extensions", "defaults", "idle-think", "index.js");
 const BUNDLED_BTW_EXTENSION = join(__dirname, "extensions", "defaults", "btw", "index.js");
 const BUNDLED_DEBUG_EXTENSION = join(__dirname, "extensions", "defaults", "debug", "index.js");
 const BUNDLED_MCP_EXTENSION = join(__dirname, "extensions", "defaults", "mcp", "index.js");
@@ -211,6 +212,15 @@ export function getBuiltinExtensionPaths() {
         if (existsSync(teamTs))
             paths.push(teamTs);
     }
+    // === IdleThink extension (background code exploration during idle) ===
+    if (existsSync(BUNDLED_IDLE_THINK_EXTENSION)) {
+        paths.push(BUNDLED_IDLE_THINK_EXTENSION);
+    }
+    else {
+        const idleThinkTs = join(__dirname, "extensions", "defaults", "idle-think", "index.ts");
+        if (existsSync(idleThinkTs))
+            paths.push(idleThinkTs);
+    }
     // === BTW extension (quick side question without interrupting) ===
     if (existsSync(BUNDLED_BTW_EXTENSION)) {
         paths.push(BUNDLED_BTW_EXTENSION);

package/dist/core/config/settings-manager.d.ts

@@ -105,6 +105,13 @@ export interface Settings {
     presence?: {
         enabled?: boolean;
     };
+    /** IdleThink extension settings - background code exploration during idle */
+    idleThink?: {
+        enabled?: boolean;
+        idleMinutes?: number;
+        dailyBudget?: number;
+        maxDurationMinutes?: number;
+    };
     /** Auto-update setting: 'always' = auto-update on startup, 'prompt' = ask user (default), 'never' = never check */
     autoUpdate?: "always" | "prompt" | "never";
     /** Last skipped version for update prompts */

package/dist/core/sub-agent/index.d.ts

@@ -8,4 +8,4 @@ export { SubAgentRuntime, subAgentRuntime } from "./sub-agent-runtime.js";
 export { InProcessSubAgentBackend } from "./sub-agent-backend.js";
 export { SubprocessSubAgentBackend } from "./subprocess-backend.js";
 export type { SubprocessBackendOptions } from "./subprocess-backend.js";
-export type { SubAgentSpec, SubAgentResult, SubAgentHandle, SubAgentBackend, } from "./sub-agent-types.js";
+export type { SubAgentSpec, SubAgentEvent, SubAgentResult, SubAgentHandle, SubAgentBackend, } from "./sub-agent-types.js";

package/dist/core/sub-agent/sub-agent-backend.js

@@ -32,6 +32,12 @@ export class InProcessSubAgentBackend {
             model: spec.model,
         };
         const { session } = await createAgentSession(options);
+        const unsubscribe = session.subscribe((event) => {
+            const subAgentEvent = toSubAgentEvent(id, event);
+            if (subAgentEvent) {
+                spec.onEvent?.(subAgentEvent);
+            }
+        });
         const timeoutMs = spec.timeoutMs;
         let status = "running";
         let result;
@@ -44,21 +50,10 @@ export class InProcessSubAgentBackend {
                 }
             }, timeoutMs);
         }
-        // Extract text from assistant message content
-        const extractTextFromContent = (content) => {
-            if (typeof content === "string")
-                return content;
-            if (Array.isArray(content)) {
-                return content
-                    .filter((part) => typeof part === "object" && part !== null && "type" in part && part.type === "text" && typeof part.text === "string")
-                    .map((part) => part.text)
-                    .join("\n");
-            }
-            return "";
-        };
         // Start the prompt
         const promptPromise = (async () => {
             try {
+                spec.onEvent?.({ type: "agent_start", subAgentId: id, timestamp: Date.now() });
                 await session.prompt(prompt, {
                     images: spec.images,
                 });
@@ -107,6 +102,14 @@ export class InProcessSubAgentBackend {
                 }
                 // Clean up signal handler
                 spec.signal.removeEventListener("abort", signalHandler);
+                unsubscribe();
+                spec.onEvent?.({
+                    type: "agent_end",
+                    subAgentId: id,
+                    timestamp: Date.now(),
+                    success: result?.success ?? false,
+                    error: result?.error,
+                });
             }
         })();
         return {
@@ -132,6 +135,69 @@ export class InProcessSubAgentBackend {
         };
     }
 }
+function toSubAgentEvent(subAgentId, event) {
+    const timestamp = Date.now();
+    switch (event.type) {
+        case "message_update":
+            return {
+                type: "message_update",
+                subAgentId,
+                timestamp,
+                text: extractMessageText(event.message),
+                deltaType: event.assistantMessageEvent.type,
+            };
+        case "message_end":
+            return {
+                type: "message_end",
+                subAgentId,
+                timestamp,
+                text: extractMessageText(event.message),
+            };
+        case "tool_execution_start":
+            return {
+                type: "tool_start",
+                subAgentId,
+                timestamp,
+                toolName: event.toolName,
+                args: event.args,
+            };
+        case "tool_execution_update":
+            return {
+                type: "tool_update",
+                subAgentId,
+                timestamp,
+                toolName: event.toolName,
+                partialResult: event.partialResult,
+            };
+        case "tool_execution_end":
+            return {
+                type: "tool_end",
+                subAgentId,
+                timestamp,
+                toolName: event.toolName,
+                isError: event.isError,
+            };
+        default:
+            return undefined;
+    }
+}
+function extractTextFromContent(content) {
+    if (typeof content === "string")
+        return content;
+    if (Array.isArray(content)) {
+        return content
+            .filter((part) => typeof part === "object" && part !== null && "type" in part && part.type === "text" && typeof part.text === "string")
+            .map((part) => part.text)
+            .join("\n");
+    }
+    return "";
+}
+function extractMessageText(message) {
+    if (typeof message !== "object" || message === null || !("content" in message)) {
+        return "";
+    }
+    return extractTextFromContent(message.content);
+}
 async function buildPromptWithContextFiles(spec) {
     if (!spec.contextFiles?.length) {
         return spec.prompt;

package/dist/core/sub-agent/sub-agent-types.d.ts

@@ -1,5 +1,5 @@
 /**
- * [WHO]: SubAgent types - SubAgentSpec, SubAgentHandle, SubAgentBackend, SubAgentResult
+ * [WHO]: SubAgent types - SubAgentSpec, SubAgentEvent, SubAgentHandle, SubAgentBackend, SubAgentResult
  * [FROM]: Depends on @pencil-agent/agent-core, @pencil-agent/ai, core/tools
  * [TO]: Consumed by ./sub-agent-runtime, ./sub-agent-backend, ./index.ts, extensions/defaults/subagent/*, extensions/defaults/team/*
  * [HERE]: core/sub-agent/sub-agent-types.ts - SubAgent type definitions
@@ -7,6 +7,47 @@
  */
 import type { ImageContent, Model } from "@pencil-agent/ai";
 import type { Tool } from "../tools/index.js";
+/** Realtime lifecycle event emitted by a running SubAgent. */
+export type SubAgentEvent = {
+    type: "agent_start";
+    subAgentId: string;
+    timestamp: number;
+} | {
+    type: "message_update";
+    subAgentId: string;
+    timestamp: number;
+    text: string;
+    deltaType?: string;
+} | {
+    type: "message_end";
+    subAgentId: string;
+    timestamp: number;
+    text: string;
+} | {
+    type: "tool_start";
+    subAgentId: string;
+    timestamp: number;
+    toolName: string;
+    args: unknown;
+} | {
+    type: "tool_update";
+    subAgentId: string;
+    timestamp: number;
+    toolName: string;
+    partialResult: unknown;
+} | {
+    type: "tool_end";
+    subAgentId: string;
+    timestamp: number;
+    toolName: string;
+    isError: boolean;
+} | {
+    type: "agent_end";
+    subAgentId: string;
+    timestamp: number;
+    success: boolean;
+    error?: string;
+};
 /**
  * Specification for spawning a SubAgent.
  */
@@ -29,6 +70,8 @@ export interface SubAgentSpec {
     contextFiles?: string[];
     /** Optional callback invoked after the run result is available */
     exitHook?: (result: SubAgentResult) => Promise<void> | void;
+    /** Optional realtime observer for TUI/status integrations */
+    onEvent?: (event: SubAgentEvent) => void;
 }
 /**
  * Result from a completed SubAgent run.

package/dist/core/sub-agent/sub-agent-types.js

@@ -1,5 +1,5 @@
 /**
- * [WHO]: SubAgent types - SubAgentSpec, SubAgentHandle, SubAgentBackend, SubAgentResult
+ * [WHO]: SubAgent types - SubAgentSpec, SubAgentEvent, SubAgentHandle, SubAgentBackend, SubAgentResult
  * [FROM]: Depends on @pencil-agent/agent-core, @pencil-agent/ai, core/tools
  * [TO]: Consumed by ./sub-agent-runtime, ./sub-agent-backend, ./index.ts, extensions/defaults/subagent/*, extensions/defaults/team/*
  * [HERE]: core/sub-agent/sub-agent-types.ts - SubAgent type definitions

package/dist/extensions/defaults/CLAUDE.md

@@ -17,10 +17,11 @@ security-audit/engine/interceptor.ts: Request/response interception, Interceptor
 security-audit/engine/logger.ts: Security event logging, JSON file audit trail
 security-audit/engine/detector.ts: Vulnerability detection, pattern matching for dangerous commands
 soul/index.ts: AI personality evolution extension, persistent personality across sessions
-grub/index.ts: Grub extension entry - long-running autonomous harness, dual-phase system prompts (initializer/coding), /grub command (start/status/resume/stop) + grub renderer, session_start auto-adopt, git harness commit, pruneStale cleanup
-grub/grub-controller.ts: GrubController - state machine for /grub iterations, durable persistState on every transition, adoptResumedTask for cross-session resume, validateCompletion downgrades premature complete when feature-list still has pending entries
-grub/grub-parser.ts: Grub command parsing - parseGrubCommand/buildGrubHelp with resume subcommand, status --json, --max-iter/--max-fail flags
-grub/grub-types.ts: Grub types - GrubStatus/GrubDecisionStatus/GrubDecision/GrubPhase/GrubTaskState/GrubTaskSnapshot/ParsedGrubCommand + FeatureItem/FeatureList (version 1 schema) + PersistedGrubState envelope
+grub/index.ts: Grub extension entry - long-running autonomous harness, locale-aware dual-phase system prompts (initializer/coding), /grub command (start/status/resume/stop) + grub renderer, session_start auto-adopt, git harness commit, pruneStale cleanup
+grub/grub-controller.ts: GrubController - state machine for /grub iterations, locale-persisted prompt generation, durable persistState on every transition, adoptResumedTask for cross-session resume, validateCompletion downgrades premature complete when feature-list still has pending entries
+grub/grub-parser.ts: Grub command parsing - parseGrubCommand/buildGrubHelp with localized help, resume subcommand, status --json, --max-iter/--max-fail flags
+grub/grub-types.ts: Grub types - GrubStatus/GrubDecisionStatus/GrubDecision/GrubPhase/GrubLocale/GrubTaskState/GrubTaskSnapshot/ParsedGrubCommand + FeatureItem/FeatureList (version 1 schema) + PersistedGrubState envelope
+grub/grub-i18n.ts: Grub localization helper - detectGrubLocale(), grubText(), languageName(), English/Chinese TUI strings
 grub/grub-feature-list.ts: feature-list.json IO - readFeatureList/writeFeatureList atomic write, validateFeatureListDiff enforces passes/evidence-only mutations, createInitialFeatureList placeholder, migrateChecklistToFeatureList legacy converter, countPassing/allPassing/firstPending helpers
 grub/grub-persistence.ts: Cross-session persistence - persistState atomic JSON write to .grub/<id>/state.json, loadState shape-validated read, discoverActiveTasks scans .grub/ for running records, pruneStale removes terminal harnesses older than 30 days by default
 grub/README.md: Grub extension documentation - long-running harness contract, feature-list.json schema, completion guard, cross-session resume, legacy migration

package/dist/extensions/defaults/grub/grub-controller.d.ts

@@ -4,10 +4,12 @@
  * [TO]: Consumed by extension entry point (./index.ts)
  * [HERE]: extensions/defaults/grub/grub-controller.ts - state machine for /grub iterations with cross-session persistence and feature-list-gated completion
  */
+import { type GrubLocale } from "./grub-i18n.js";
 import type { GrubControllerState, GrubDecision, GrubTaskSnapshot, GrubTaskState } from "./grub-types.js";
 export interface GrubStartOptions {
     maxIterations?: number;
     maxConsecutiveFailures?: number;
+    locale?: GrubLocale;
 }
 export declare class GrubController {
     private activeTask?;

package/dist/extensions/defaults/grub/grub-controller.js

@@ -7,6 +7,7 @@
 import { randomBytes } from "node:crypto";
 import { join } from "node:path";
 import { allPassing, firstPending, readFeatureList } from "./grub-feature-list.js";
+import { languageName, grubText } from "./grub-i18n.js";
 import { persistState, stateFilePathFor } from "./grub-persistence.js";
 const DEFAULT_MAX_ITERATIONS = 25;
 const DEFAULT_MAX_CONSECUTIVE_FAILURES = 3;
@@ -39,6 +40,7 @@ export class GrubController {
         const task = {
             id,
             goal: trimmedGoal,
+            locale: options.locale ?? "en",
             status: "running",
             phase: "initializer",
             startedAt: now,
@@ -67,7 +69,7 @@ export class GrubController {
         if (this.activeTask && this.activeTask.id !== task.id) {
             throw new Error(`Cannot adopt task ${task.id}; ${this.activeTask.id} is already active.`);
         }
-        const resumed = { ...task, awaitingTurn: false, updatedAt: Date.now() };
+        const resumed = { ...task, locale: task.locale ?? "en", awaitingTurn: false, updatedAt: Date.now() };
         this.activeTask = resumed;
         this.safePersist(resumed);
         return resumed;
@@ -82,6 +84,7 @@ export class GrubController {
         const snapshot = {
             id: finalTask.id,
             goal: finalTask.goal,
+            locale: finalTask.locale,
             status,
             phase: finalTask.phase,
             startedAt: finalTask.startedAt,
@@ -109,36 +112,68 @@ export class GrubController {
             throw new Error("No active grub task.");
         }
         const task = this.activeTask;
+        const text = grubText(task.locale);
         const sections = [
             `${this.getPromptPrefix(task.id)}${task.currentIteration}]`,
             "",
-            "Autonomous grub goal:",
+            task.locale === "zh" ? "自主 Grub 目标：" : "Autonomous grub goal:",
             task.goal,
             "",
-            "You are inside a managed grub harness. Keep making concrete progress on the same goal.",
-            "Use tools, edit files, run checks, and verify results as needed.",
+            task.locale === "zh"
+                ? "你正在一个受控的 grub harness 中工作。请围绕同一个目标持续推进具体进展。"
+                : "You are inside a managed grub harness. Keep making concrete progress on the same goal.",
+            task.locale === "zh"
+                ? "按需使用工具、编辑文件、运行检查并验证结果。所有面向用户的总结、进度和说明都必须使用中文。"
+                : "Use tools, edit files, run checks, and verify results as needed.",
+            `User language: ${languageName(task.locale)}.`,
             "",
-            "Harness files (must stay up to date every iteration):",
-            `- Feature list (JSON): ${task.featureListPath}`,
-            `- Progress log: ${task.progressLogPath}`,
-            `- Session init script: ${task.initScriptPath}`,
+            task.locale === "zh" ? "Harness 文件（每轮都必须保持最新）：" : "Harness files (must stay up to date every iteration):",
+            `- ${text.featureList}: ${task.featureListPath}`,
+            `- ${text.progressLog}: ${task.progressLogPath}`,
+            `- ${text.initScript}: ${task.initScriptPath}`,
         ];
         if (task.phase === "initializer") {
-            sections.push("", "Initializer phase requirements:", "1. Replace the placeholder feature-list.json with 15-40 concrete, testable slices. Every entry MUST keep the schema {id, category, description, steps[], passes:false}.", "2. Ensure init.sh contains reliable startup checks and make it executable.", "3. Append a clear initialization summary in progress-log.md.", "4. Do not attempt broad implementation yet; prepare a strong harness first.", "5. End this turn with loop-state status=continue unless the goal is already complete/blocked.");
+            sections.push("", task.locale === "zh" ? "初始化阶段要求：" : "Initializer phase requirements:", task.locale === "zh"
+                ? "1. 将 feature-list.json 的占位内容替换为 15-40 个具体、可测试的切片。每项必须保持 {id, category, description, steps[], passes:false}。"
+                : "1. Replace the placeholder feature-list.json with 15-40 concrete, testable slices. Every entry MUST keep the schema {id, category, description, steps[], passes:false}.", task.locale === "zh"
+                ? "2. 确保 init.sh 包含可靠的启动检查，并设置为可执行。"
+                : "2. Ensure init.sh contains reliable startup checks and make it executable.", task.locale === "zh"
+                ? "3. 在 progress-log.md 中追加清晰的初始化总结。"
+                : "3. Append a clear initialization summary in progress-log.md.", task.locale === "zh"
+                ? "4. 先建立强 harness，不要开始大范围实现。"
+                : "4. Do not attempt broad implementation yet; prepare a strong harness first.", task.locale === "zh"
+                ? "5. 除非目标已经完成或阻塞，否则本轮以 loop-state status=continue 结束。"
+                : "5. End this turn with loop-state status=continue unless the goal is already complete/blocked.");
         }
         else {
-            sections.push("", "Execution phase requirements:", "1. Start by running the init script, then read feature-list.json and progress-log.md.", "2. Pick exactly one feature with passes:false and execute it end-to-end.", "3. Run relevant verification (tests, smoke checks, or runtime checks).", "4. Flip ONLY the passes/evidence fields for that feature; other fields are immutable.", "5. Append progress log and git-commit before finishing the turn.", "6. Keep each iteration incremental and production-safe.");
+            sections.push("", task.locale === "zh" ? "执行阶段要求：" : "Execution phase requirements:", task.locale === "zh"
+                ? "1. 先运行 init.sh，再读取 feature-list.json 和 progress-log.md。"
+                : "1. Start by running the init script, then read feature-list.json and progress-log.md.", task.locale === "zh"
+                ? "2. 只选择一个 passes:false 的 feature，并端到端完成它。"
+                : "2. Pick exactly one feature with passes:false and execute it end-to-end.", task.locale === "zh"
+                ? "3. 运行相关验证（测试、烟测或运行时检查）。"
+                : "3. Run relevant verification (tests, smoke checks, or runtime checks).", task.locale === "zh"
+                ? "4. 只能修改该 feature 的 passes/evidence 字段；其他字段不可变。"
+                : "4. Flip ONLY the passes/evidence fields for that feature; other fields are immutable.", task.locale === "zh"
+                ? "5. 本轮结束前追加进度日志并 git commit。"
+                : "5. Append progress log and git-commit before finishing the turn.", task.locale === "zh"
+                ? "6. 每轮都保持增量、安全、可回退。"
+                : "6. Keep each iteration incremental and production-safe.");
         }
         if (task.lastDecision?.summary) {
-            sections.push("", "Previous summary:", task.lastDecision.summary);
+            sections.push("", task.locale === "zh" ? "上次总结：" : "Previous summary:", task.lastDecision.summary);
         }
         if (task.lastDecision?.nextStep) {
-            sections.push("", "Previous planned next step:", task.lastDecision.nextStep);
+            sections.push("", task.locale === "zh" ? "上次计划的下一步：" : "Previous planned next step:", task.lastDecision.nextStep);
         }
         if (task.lastError) {
-            sections.push("", "Recovery note:", task.lastError);
+            sections.push("", task.locale === "zh" ? "恢复提示：" : "Recovery note:", task.lastError);
         }
-        sections.push("", "Do not stop just because one query finished. Only decide `complete` when every feature in feature-list.json has passes:true.", "If you need another autonomous pass, end with a valid <loop-state> block so the system can continue automatically.");
+        sections.push("", task.locale === "zh"
+            ? "不要因为一次查询结束就停止。只有 feature-list.json 中每个 feature 都 passes:true 时，才可以决定 `complete`。"
+            : "Do not stop just because one query finished. Only decide `complete` when every feature in feature-list.json has passes:true.", task.locale === "zh"
+            ? "如果还需要下一轮自主推进，请以有效的 <loop-state> 块结束，让系统自动继续。"
+            : "If you need another autonomous pass, end with a valid <loop-state> block so the system can continue automatically.");
         return sections.join("\n");
     }
     markDispatched() {
@@ -165,12 +200,14 @@ export class GrubController {
             const rewritten = {
                 status: "continue",
                 summary: decision.summary,
-                nextStep: "feature-list.json is missing or invalid; the initializer must produce it before claiming complete.",
+                nextStep: this.activeTask.locale === "zh"
+                    ? "feature-list.json 缺失或无效；初始化阶段必须先生成它，不能直接声明完成。"
+                    : "feature-list.json is missing or invalid; the initializer must produce it before claiming complete.",
             };
             return {
                 decision: rewritten,
                 downgraded: true,
-                reason: "feature-list.json missing or invalid",
+                reason: this.activeTask.locale === "zh" ? "feature-list.json 缺失或无效" : "feature-list.json missing or invalid",
             };
         }
         if (allPassing(list)) {
@@ -181,13 +218,19 @@ export class GrubController {
             status: "continue",
             summary: decision.summary,
             nextStep: pending
-                ? `Complete pending feature: ${pending.id} (${pending.description})`
-                : "Complete the remaining pending features before declaring done.",
+                ? this.activeTask.locale === "zh"
+                    ? `完成待处理 feature：${pending.id}（${pending.description}）`
+                    : `Complete pending feature: ${pending.id} (${pending.description})`
+                : this.activeTask.locale === "zh"
+                    ? "先完成剩余待处理 feature，再声明完成。"
+                    : "Complete the remaining pending features before declaring done.",
         };
         return {
             decision: rewritten,
             downgraded: true,
-            reason: `feature-list still has ${list.features.length - list.features.filter((f) => f.passes).length} pending entries`,
+            reason: this.activeTask.locale === "zh"
+                ? `feature-list 仍有 ${list.features.length - list.features.filter((f) => f.passes).length} 个待处理条目`
+                : `feature-list still has ${list.features.length - list.features.filter((f) => f.passes).length} pending entries`,
         };
     }
     finishTurn(decision) {
@@ -204,15 +247,23 @@ export class GrubController {
             task.phase = "execution";
         }
         if (decision.status === "complete") {
-            return { action: "stop", snapshot: this.stop("Grub goal completed.", "complete") };
+            return {
+                action: "stop",
+                snapshot: this.stop(task.locale === "zh" ? "Grub 目标已完成。" : "Grub goal completed.", "complete"),
+            };
         }
         if (decision.status === "blocked") {
-            return { action: "stop", snapshot: this.stop("Grub reported it is blocked.", "blocked") };
+            return {
+                action: "stop",
+                snapshot: this.stop(task.locale === "zh" ? "Grub 报告任务被阻塞。" : "Grub reported it is blocked.", "blocked"),
+            };
         }
         if (task.currentIteration >= task.maxIterations) {
             return {
                 action: "stop",
-                snapshot: this.stop(`Grub hit the iteration limit (${task.maxIterations}).`, "failed"),
+                snapshot: this.stop(task.locale === "zh"
+                    ? `Grub 达到轮次上限（${task.maxIterations}）。`
+                    : `Grub hit the iteration limit (${task.maxIterations}).`, "failed"),
             };
         }
         task.currentIteration += 1;
@@ -231,13 +282,17 @@ export class GrubController {
         if (task.consecutiveFailures >= task.maxConsecutiveFailures) {
             return {
                 action: "stop",
-                snapshot: this.stop(`Grub stopped after ${task.consecutiveFailures} consecutive failures. Last error: ${message}`, "failed"),
+                snapshot: this.stop(task.locale === "zh"
+                    ? `Grub 连续失败 ${task.consecutiveFailures} 次后停止。最近错误：${message}`
+                    : `Grub stopped after ${task.consecutiveFailures} consecutive failures. Last error: ${message}`, "failed"),
             };
         }
         if (task.currentIteration >= task.maxIterations) {
             return {
                 action: "stop",
-                snapshot: this.stop(`Grub hit the iteration limit (${task.maxIterations}).`, "failed"),
+                snapshot: this.stop(task.locale === "zh"
+                    ? `Grub 达到轮次上限（${task.maxIterations}）。`
+                    : `Grub hit the iteration limit (${task.maxIterations}).`, "failed"),
             };
         }
         task.currentIteration += 1;

package/dist/extensions/defaults/grub/grub-i18n.d.ts

@@ -0,0 +1,128 @@
+/**
+ * [WHO]: Provides detectGrubLocale(), grubText(), type GrubLocale for localized /grub prompts and TUI messages
+ * [FROM]: Depends on core/i18n locale type
+ * [TO]: Consumed by grub-controller.ts, grub-parser.ts, index.ts for user-language-aware Grub UX
+ * [HERE]: extensions/defaults/grub/grub-i18n.ts - small locale helper scoped to the Grub extension
+ */
+import type { Locale } from "../../../core/i18n/index.js";
+export type GrubLocale = Locale;
+export declare function detectGrubLocale(text: string, fallback?: Locale): GrubLocale;
+export declare function languageName(locale: GrubLocale): string;
+export declare function grubText(locale: GrubLocale): (typeof GRUB_TEXT)[GrubLocale];
+declare const GRUB_TEXT: {
+    readonly en: {
+        readonly prefix: "[Grub]";
+        readonly missingGoal: "Missing grub goal.";
+        readonly usage: readonly ["[Grub] Usage:", "  /grub <goal> [--max-iter N] [--max-fail N]   Start an autonomous digging task", "  /grub status [--json]                        Show the active or last finished task", "  /grub resume                                 Resume an adopted task from disk", "  /grub stop                                   Stop the active task", "", "[Grub] Harness artifacts under .grub/<task-id>/:", "  feature-list.json   structured features (agent may only flip passes/evidence)", "  progress-log.md     append-only progress notes", "  init.sh             per-iteration get-bearings + smoke script", "  state.json          durable GrubController state (for cross-session resume)", "", "[Grub] The agent keeps iterating until it reports complete, reports blocked,", "or hits a safety limit (iterations / consecutive failures). Declaring complete", "is rejected unless every feature in feature-list.json has passes:true."];
+        readonly activeTask: "Active task";
+        readonly lastTask: "Last task";
+        readonly status: "Status";
+        readonly phase: "Phase";
+        readonly goal: "Goal";
+        readonly started: "Started";
+        readonly updated: "Updated";
+        readonly currentIteration: "Current iteration";
+        readonly completedIterations: "Completed iterations";
+        readonly awaitingResult: "Awaiting result";
+        readonly yes: "yes";
+        readonly no: "no";
+        readonly consecutiveFailures: "Consecutive failures";
+        readonly maxIterations: "Max iterations";
+        readonly harnessDir: "Harness dir";
+        readonly featureList: "Feature list";
+        readonly progressLog: "Progress log";
+        readonly initScript: "Init script";
+        readonly stateFile: "State file";
+        readonly featuresPassing: (passing: number, total: number) => string;
+        readonly lastSummary: "Last summary";
+        readonly lastNextStep: "Last next step";
+        readonly lastError: "Last error";
+        readonly noActive: "No grub task is active.";
+        readonly noStarted: "No grub task has been started in this session.";
+        readonly decision: "Decision";
+        readonly summary: "Summary";
+        readonly nextStep: "Next step";
+        readonly resumeSummary: (id: string, iteration: number, phase: string) => string;
+        readonly resumeHint: "Use /grub status to inspect, /grub resume to continue dispatch, or /grub stop to abandon.";
+        readonly startingIteration: (iteration: number, id: string) => string;
+        readonly startedTask: (id: string) => string;
+        readonly initPhase: "Init phase: expand feature-list.json / init.sh / progress-log.md before broad implementation.";
+        readonly safetyLimits: (maxIterations: number, maxFailures: number) => string;
+        readonly resuming: (id: string) => string;
+        readonly stopped: (id: string) => string;
+        readonly noActiveRunning: "No active grub task is running.";
+        readonly noPersisted: "No adopted or persisted grub task to resume.";
+        readonly failedResume: (id: string, message: string) => string;
+        readonly failedAdopt: (message: string) => string;
+        readonly failedNoAssistant: "Grub run ended without an assistant message.";
+        readonly iterationFailedRetry: (iteration: number | undefined) => string;
+        readonly invalidLoopState: "Assistant response did not include a valid <loop-state> block.";
+        readonly invalidLoopRetry: (iteration: number | undefined) => string;
+        readonly prematureComplete: (reason: string) => string;
+        readonly harnessCreated: "- Harness created by /grub.";
+        readonly structuredFeatureNote: "- Structured feature list lives in feature-list.json; only passes/evidence may change.";
+        readonly initScriptNote: "- init.sh performs get-bearings + smoke before every iteration.";
+        readonly iterationsHeading: "## Iterations";
+        readonly appendIterationNote: "- (append one short entry per iteration with verification evidence)";
+        readonly progressLogTitle: (id: string) => string;
+        readonly initializationHeading: "## Initialization";
+    };
+    readonly zh: {
+        readonly prefix: "[Grub]";
+        readonly missingGoal: "缺少 grub 目标。";
+        readonly usage: readonly ["[Grub] 用法：", "  /grub <目标> [--max-iter N] [--max-fail N]   启动一个自主长任务", "  /grub status [--json]                        查看当前或最近结束的任务", "  /grub resume                                 继续磁盘中恢复的任务", "  /grub stop                                   停止当前任务", "", "[Grub] 任务产物位于 .grub/<task-id>/：", "  feature-list.json   结构化功能清单（agent 只能修改 passes/evidence）", "  progress-log.md     追加式进度记录", "  init.sh             每轮开始前的环境定位和烟测脚本", "  state.json          持久化控制器状态（用于跨会话恢复）", "", "[Grub] agent 会持续迭代，直到完成、阻塞、用户停止，或触发安全上限。", "只有 feature-list.json 中所有功能都 passes:true 时，才允许声明完成。"];
+        readonly activeTask: "当前任务";
+        readonly lastTask: "最近任务";
+        readonly status: "状态";
+        readonly phase: "阶段";
+        readonly goal: "目标";
+        readonly started: "开始时间";
+        readonly updated: "更新时间";
+        readonly currentIteration: "当前轮次";
+        readonly completedIterations: "已完成轮次";
+        readonly awaitingResult: "等待结果";
+        readonly yes: "是";
+        readonly no: "否";
+        readonly consecutiveFailures: "连续失败";
+        readonly maxIterations: "最大轮次";
+        readonly harnessDir: "Harness 目录";
+        readonly featureList: "功能清单";
+        readonly progressLog: "进度日志";
+        readonly initScript: "初始化脚本";
+        readonly stateFile: "状态文件";
+        readonly featuresPassing: (passing: number, total: number) => string;
+        readonly lastSummary: "上次总结";
+        readonly lastNextStep: "下一步";
+        readonly lastError: "最近错误";
+        readonly noActive: "当前没有 grub 任务。";
+        readonly noStarted: "本会话还没有启动 grub 任务。";
+        readonly decision: "决策";
+        readonly summary: "总结";
+        readonly nextStep: "下一步";
+        readonly resumeSummary: (id: string, iteration: number, phase: string) => string;
+        readonly resumeHint: "可用 /grub status 查看，/grub resume 继续派发，或 /grub stop 放弃。";
+        readonly startingIteration: (iteration: number, id: string) => string;
+        readonly startedTask: (id: string) => string;
+        readonly initPhase: "初始化阶段：先完善 feature-list.json / init.sh / progress-log.md，再开始大范围实现。";
+        readonly safetyLimits: (maxIterations: number, maxFailures: number) => string;
+        readonly resuming: (id: string) => string;
+        readonly stopped: (id: string) => string;
+        readonly noActiveRunning: "当前没有正在运行的 grub 任务。";
+        readonly noPersisted: "没有可恢复的 grub 任务。";
+        readonly failedResume: (id: string, message: string) => string;
+        readonly failedAdopt: (message: string) => string;
+        readonly failedNoAssistant: "Grub 本轮结束时没有 assistant 消息。";
+        readonly iterationFailedRetry: (iteration: number | undefined) => string;
+        readonly invalidLoopState: "Assistant 回复缺少有效的 <loop-state> 块。";
+        readonly invalidLoopRetry: (iteration: number | undefined) => string;
+        readonly prematureComplete: (reason: string) => string;
+        readonly harnessCreated: "- Harness 由 /grub 创建。";
+        readonly structuredFeatureNote: "- 结构化功能清单位于 feature-list.json；后续只能修改 passes/evidence。";
+        readonly initScriptNote: "- 每轮开始前由 init.sh 执行环境定位和烟测。";
+        readonly iterationsHeading: "## 迭代记录";
+        readonly appendIterationNote: "- （每轮追加一条简短记录，包含验证证据）";
+        readonly progressLogTitle: (id: string) => string;
+        readonly initializationHeading: "## 初始化";
+    };
+};
+export {};