catui-agent 1.0.0-beta.0

package/dist/extensions/builtin/grub/README.md

@@ -0,0 +1,112 @@
+# Grub Extension
+
+`/grub` runs one autonomous long-running task until the agent reports it
+complete, reports it is blocked, the user stops it, or a safety limit is
+reached. The harness design follows the pattern described in Anthropic's
+[Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents):
+a structured on-disk state lets coding agents pick up where they left off
+even across fresh context windows and full process restarts.
+
+## Commands
+
+- `/grub <goal> [--max-iter N] [--max-fail N]` — start one autonomous task
+- `/grub status [--json]` — show the active or last finished grub task
+- `/grub resume` — resume dispatch for an adopted/persisted task
+- `/grub stop` — stop the active grub task
+
+## Harness artifacts
+
+Each task owns a directory at `.grub/<task-id>/`:
+
+| File | Purpose | Who may write |
+|------|---------|---------------|
+| `feature-list.json` | Structured list of end-to-end features | Initializer writes the whole file once; coding agents may only flip `passes` and set `evidence` |
+| `progress-log.md` | Dated notes describing each iteration | Agent, append-only |
+| `init.sh` | Get-bearings + project smoke script run at the start of every iteration | Initializer; later agents may add project-specific smoke commands |
+| `state.json` | Durable `GrubTaskState` snapshot for cross-session resume | Controller, atomic writes |
+
+`feature-list.json` schema (version 1):
+
+```json
+{
+  "version": 1,
+  "goal": "<user goal>",
+  "features": [
+    {
+      "id": "kebab-slug",
+      "category": "functional|verification|polish",
+      "description": "observable behavior",
+      "steps": ["actionable", "verification", "steps"],
+      "passes": false,
+      "evidence": "optional git sha or short proof"
+    }
+  ]
+}
+```
+
+The controller validates every mutation: changing `description`, `steps`,
+`category`, `id`, list length, or reordering counts as a violation. Agents
+are told up front that the only permitted edits are toggling `passes` and
+setting `evidence`.
+
+## How it works
+
+- Each grub iteration is tagged with a `[GRUB:<id>:<n>]` prompt prefix so
+  the extension can recognise its own injected turns.
+- On start, grub creates the harness directory and writes the initial
+  artifacts without creating a git commit. The harness keeps durable state on
+  disk and leaves source changes visible in the working tree, avoiding noisy
+  `grub(...)` commits unless the user explicitly asks for them.
+- Two phase-specialized system prompts are injected via
+  `before_agent_start`:
+  - **Initializer prompt** (first successful turn): expand
+    `feature-list.json` into 15-40 concrete features, harden `init.sh`,
+    seed `progress-log.md`. No broad implementation yet.
+  - **Coding prompt** (remaining turns): run `init.sh`, pick exactly one
+    pending feature, implement + verify end-to-end, flip `passes` +
+    `evidence`, and append to `progress-log.md`.
+- At the end of every grub turn the assistant must emit a single
+  `<loop-state>{"status":"continue|complete|blocked", "summary":"...", "nextStep":"..."}</loop-state>`
+  block. The extension parses it and dispatches the next iteration or
+  stops with a terminal status.
+- **Initializer sanitize-not-fail**: while in the initializer phase, only
+  genuinely unfixable structural problems (feature count out of 15-40,
+  unreplaced placeholder, non-kebab ids, duplicate ids) fail the turn and
+  force a retry. Recoverable hygiene issues are auto-corrected instead of
+  killing the task: a wrong `goal` is restored to the authoritative task goal,
+  pre-marked `passes:true` are reset to `false`, and stray `evidence` is
+  dropped. The sanitized list is written back to disk and becomes the baseline,
+  so the phase always advances once the structure is valid.
+- **Phase-aware failure budget**: the initializer gets a more forgiving budget
+  (default 5) than execution (default 3, via `--max-fail`), because standing up
+  a valid harness is a distinct, retry-friendly activity from execution work.
+- **Mutation guard**: after the initializer creates the first real
+  `feature-list.json`, each subsequent turn is diffed against the persisted
+  baseline. Rewriting feature ids, descriptions, categories, steps, count, or
+  order is rejected and retried; only `passes` and `evidence` may change.
+- **Completion guard**: if the decision says `complete` but
+  `feature-list.json` still has `passes:false` entries, the controller
+  rewrites the decision to `continue` with a synthetic `nextStep`
+  pointing at the first pending feature. The harness will not allow
+  premature "done".
+- **Cross-session resume**: `GrubTaskState` is written atomically to
+  `state.json` on every transition. On the next session, `session_start`
+  calls `discoverActiveTasks()` and adopts the most recent running task
+  without auto-dispatching — the user types `/grub resume` to continue.
+- **Safety limits**: 25 iterations and 3 consecutive failures by default;
+  override with `--max-iter` / `--max-fail`.
+- **Stale harness cleanup**: on extension load, terminal harnesses older
+  than 30 days are pruned from `.grub/`.
+
+## Legacy migration
+
+Earlier versions wrote `feature-checklist.md` (markdown checkboxes). When a
+new iteration starts and `feature-list.json` is missing but the legacy file
+exists, its checkbox items are migrated into the JSON format (category
+defaults to `functional`; `steps` start empty so the initializer can refine
+later).
+
+## Related
+
+For the recurring scheduler that runs prompts or slash commands on an
+interval, see the sibling [`loop` extension](../loop/README.md).

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

@@ -0,0 +1,67 @@
+/**
+ * [WHO]: GrubController - drives autonomous iterative tasks with durable state and completion validation
+ * [FROM]: Depends on node:crypto, node:path, ./grub-types, ./grub-persistence, ./grub-feature-list, ./grub-prompts
+ * [TO]: Consumed by extension entry point (./index.ts)
+ * [HERE]: extensions/builtin/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;
+    maxInitializerFailures?: number;
+    locale?: GrubLocale;
+}
+export declare class GrubController {
+    private activeTask?;
+    private lastTerminalTask?;
+    getState(): GrubControllerState;
+    hasActiveTask(): boolean;
+    getActiveTask(): GrubTaskState | undefined;
+    start(goal: string, cwd: string, options?: GrubStartOptions): GrubTaskState;
+    /**
+     * Adopt a previously persisted task, e.g. after process restart. Does not
+     * auto-dispatch the next iteration; the caller decides whether to continue.
+     */
+    adoptResumedTask(task: GrubTaskState): GrubTaskState;
+    stop(reason: string, status?: GrubTaskSnapshot["status"]): GrubTaskSnapshot | undefined;
+    isGrubPrompt(prompt: string): boolean;
+    buildPrompt(): string;
+    markDispatched(): GrubTaskState;
+    /**
+     * Enforce the feature-list contract at the state-machine boundary. The
+     * initializer may replace the placeholder with the first complete list; after
+     * that, every turn may only change passes/evidence fields.
+     */
+    validateFeatureListAfterTurn(): {
+        ok: true;
+    } | {
+        ok: false;
+        message: string;
+    };
+    /**
+     * Validate a completion decision against the feature-list. If the decision
+     * says `complete` but the persisted feature-list still has pending entries,
+     * the decision is downgraded to `continue` with a synthetic nextStep.
+     * Returns the (possibly rewritten) decision.
+     */
+    validateCompletion(decision: GrubDecision): {
+        decision: GrubDecision;
+        downgraded: boolean;
+        reason?: string;
+    };
+    finishTurn(decision: GrubDecision): {
+        action: "continue" | "stop";
+        task?: GrubTaskState;
+        snapshot?: GrubTaskSnapshot;
+    };
+    recordFailure(message: string): {
+        action: "continue" | "stop";
+        task?: GrubTaskState;
+        snapshot?: GrubTaskSnapshot;
+    };
+    private generateTaskId;
+    private validateInitializerStructure;
+    private cloneFeatureList;
+    private safePersist;
+}

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

@@ -0,0 +1 @@
+var m=Object.defineProperty;var p=(f,e)=>m(f,"name",{value:e,configurable:!0});import{randomBytes as T}from"node:crypto";import{join as o}from"node:path";import{allPassing as v,firstPending as g,readFeatureList as l,sanitizeInitializerFeatureList as I,validateFeatureListDiff as b,writeFeatureList as A}from"./grub-feature-list.js";import{persistState as $,stateFilePathFor as w}from"./grub-persistence.js";import{buildGrubTaskPrompt as F,getPromptPrefix as L}from"./grub-prompts.js";const P=25,z=3,k=5,c=3,h=15,d=40;class G{static{p(this,"GrubController")}activeTask;lastTerminalTask;getState(){return{active:this.activeTask?{...this.activeTask}:void 0,lastTerminal:this.lastTerminalTask?{...this.lastTerminalTask}:void 0}}hasActiveTask(){return this.activeTask!==void 0}getActiveTask(){return this.activeTask?{...this.activeTask}:void 0}start(e,t,a={}){const i=e.trim();if(!i)throw new Error("Grub goal cannot be empty.");if(this.activeTask)throw new Error(`Grub ${this.activeTask.id} is already running. Stop it before starting a new one.`);const s=Date.now(),r=this.generateTaskId(),n=o(t,".grub",r),u={id:r,goal:i,locale:a.locale??"en",status:"running",phase:"initializer",startedAt:s,updatedAt:s,currentIteration:1,awaitingTurn:!1,consecutiveFailures:0,consecutiveBlockedAttempts:0,maxIterations:a.maxIterations??P,maxConsecutiveFailures:a.maxConsecutiveFailures??z,maxInitializerFailures:a.maxInitializerFailures??k,harnessDirectory:n,featureChecklistPath:o(n,"feature-checklist.md"),featureListPath:o(n,"feature-list.json"),stateFilePath:w(n),progressLogPath:o(n,"progress-log.md"),initScriptPath:o(n,"init.sh")};return this.activeTask=u,this.safePersist(u),u}adoptResumedTask(e){if(this.activeTask&&this.activeTask.id!==e.id)throw new Error(`Cannot adopt task ${e.id}; ${this.activeTask.id} is already active.`);const t={...e,locale:e.locale??"en",consecutiveBlockedAttempts:e.consecutiveBlockedAttempts??0,awaitingTurn:!1,updatedAt:Date.now()};return this.activeTask=t,this.safePersist(t),t}stop(e,t="stopped"){if(!this.activeTask)return this.lastTerminalTask;const a=this.activeTask,i=a.awaitingTurn,s={...a,status:t,updatedAt:Date.now(),awaitingTurn:!1};this.safePersist(s);const r={id:s.id,goal:s.goal,locale:s.locale,status:t,phase:s.phase,startedAt:s.startedAt,updatedAt:s.updatedAt,completedIterations:Math.max(0,s.currentIteration-(i?1:0)),consecutiveFailures:s.consecutiveFailures,consecutiveBlockedAttempts:s.consecutiveBlockedAttempts,harnessDirectory:s.harnessDirectory,featureChecklistPath:s.featureChecklistPath,featureListPath:s.featureListPath,stateFilePath:s.stateFilePath,progressLogPath:s.progressLogPath,initScriptPath:s.initScriptPath,lastDecision:s.lastDecision,lastError:e||s.lastError};return this.activeTask=void 0,this.lastTerminalTask=r,r}isGrubPrompt(e){return this.activeTask!==void 0&&e.startsWith(L(this.activeTask.id))}buildPrompt(){if(!this.activeTask)throw new Error("No active grub task.");return F(this.activeTask)}markDispatched(){if(!this.activeTask)throw new Error("No active grub task.");return this.activeTask.awaitingTurn=!0,this.activeTask.updatedAt=Date.now(),this.safePersist(this.activeTask),this.activeTask}validateFeatureListAfterTurn(){if(!this.activeTask)return{ok:!0};const e=this.activeTask,t=l(e.featureListPath);if(!t)return{ok:!1,message:e.locale==="zh"?"\u4EFB\u52A1\u6E05\u5355\u7F3A\u5931\u6216\u683C\u5F0F\u4E0D\u6B63\u786E\uFF0C\u9700\u8981\u5148\u4FEE\u597D\u6E05\u5355\u518D\u7EE7\u7EED\u3002":"The task checklist is missing or malformed. It needs to be fixed before continuing."};if(e.phase==="initializer"){const a=this.validateInitializerStructure(t);if(a)return{ok:!1,message:a};const{list:i,fixes:s}=I(t,e.goal);if(s.length>0)try{A(e.featureListPath,i)}catch{const r=l(e.featureListPath);return e.featureListBaseline=this.cloneFeatureList(r??t),this.safePersist(e),{ok:!0}}return e.featureListBaseline=this.cloneFeatureList(i),this.safePersist(e),{ok:!0}}if(!e.featureListBaseline)return e.featureListBaseline=this.cloneFeatureList(t),this.safePersist(e),{ok:!0};try{b(e.featureListBaseline,t)}catch(a){const i=a instanceof Error?a.message:String(a);return{ok:!1,message:e.locale==="zh"?`\u4EFB\u52A1\u6E05\u5355\u88AB\u6539\u52A8\u5F97\u4E0D\u5B89\u5168\uFF1A${i}`:`The task checklist changed in an unsafe way: ${i}`}}return e.featureListBaseline=this.cloneFeatureList(t),this.safePersist(e),{ok:!0}}validateCompletion(e){if(e.status!=="complete"||!this.activeTask)return{decision:e,downgraded:!1};const t=l(this.activeTask.featureListPath);if(!t)return{decision:{status:"continue",summary:e.summary,nextStep:this.activeTask.locale==="zh"?"\u4EFB\u52A1\u6E05\u5355\u7F3A\u5931\u6216\u65E0\u6548\uFF1B\u5FC5\u987B\u5148\u751F\u6210\u6E05\u5355\uFF0C\u4E0D\u80FD\u76F4\u63A5\u7ED3\u675F\u3002":"The task checklist is missing or invalid; it must be created before the task can finish."},downgraded:!0,reason:this.activeTask.locale==="zh"?"\u4EFB\u52A1\u6E05\u5355\u7F3A\u5931\u6216\u65E0\u6548":"the task checklist is missing or invalid"};if(v(t))return{decision:e,downgraded:!1};const a=g(t);return{decision:{status:"continue",summary:e.summary,nextStep:a?this.activeTask.locale==="zh"?`\u5B8C\u6210\u5F85\u5904\u7406 feature\uFF1A${a.id}\uFF08${a.description}\uFF09`:`Complete pending feature: ${a.id} (${a.description})`:this.activeTask.locale==="zh"?"\u5148\u5B8C\u6210\u5269\u4F59\u5F85\u5904\u7406 feature\uFF0C\u518D\u58F0\u660E\u5B8C\u6210\u3002":"Complete the remaining pending features before declaring done."},downgraded:!0,reason:this.activeTask.locale==="zh"?`\u6E05\u5355\u91CC\u8FD8\u6709 ${t.features.length-t.features.filter(s=>s.passes).length} \u9879\u672A\u5B8C\u6210`:`the checklist still has ${t.features.length-t.features.filter(s=>s.passes).length} unfinished items`}}finishTurn(e){if(!this.activeTask)return{action:"stop",snapshot:this.lastTerminalTask};const t=this.activeTask;if(t.awaitingTurn=!1,t.consecutiveFailures=0,t.lastError=void 0,t.lastDecision=e,t.updatedAt=Date.now(),e.status==="complete")return{action:"stop",snapshot:this.stop(t.locale==="zh"?"Grub \u76EE\u6807\u5DF2\u5B8C\u6210\u3002":"Grub goal completed.","complete")};if(e.status==="blocked")if(t.consecutiveBlockedAttempts+=1,t.consecutiveBlockedAttempts<c)e={status:"continue",summary:e.summary,nextStep:t.locale==="zh"?`\u963B\u585E\u62A5\u544A\u88AB\u62D2\u7EDD\uFF08\u7B2C ${t.consecutiveBlockedAttempts}/${c} \u6B21\uFF09\u3002\u540C\u4E00\u4E2A\u963B\u585E\u6761\u4EF6\u9700\u8981\u8FDE\u7EED\u51FA\u73B0 ${c} \u6B21\u624D\u80FD\u6807\u8BB0 blocked\u3002\u8BF7\u6362\u4E00\u79CD\u65B9\u5F0F\u5C1D\u8BD5\u63A8\u8FDB\u3002`:`Blocked report rejected (${t.consecutiveBlockedAttempts}/${c}). The same blocker must repeat for ${c} consecutive turns before you may report blocked. Try a different approach.`},t.lastDecision=e;else return{action:"stop",snapshot:this.stop(t.locale==="zh"?"Grub \u62A5\u544A\u4EFB\u52A1\u88AB\u963B\u585E\u3002":"Grub reported it is blocked.","blocked")};else t.consecutiveBlockedAttempts=0;return t.currentIteration>=t.maxIterations?{action:"stop",snapshot:this.stop(t.locale==="zh"?`Grub \u8FBE\u5230\u8F6E\u6B21\u4E0A\u9650\uFF08${t.maxIterations}\uFF09\u3002`:`Grub hit the iteration limit (${t.maxIterations}).`,"failed")}:(t.phase==="initializer"&&(t.phase="execution"),t.currentIteration+=1,this.safePersist(t),{action:"continue",task:{...t}})}recordFailure(e){if(!this.activeTask)return{action:"stop",snapshot:this.lastTerminalTask};const t=this.activeTask;t.awaitingTurn=!1,t.consecutiveFailures+=1,t.lastError=e,t.updatedAt=Date.now();const a=t.phase==="initializer"?t.maxInitializerFailures??k:t.maxConsecutiveFailures;return t.consecutiveFailures>=a?{action:"stop",snapshot:this.stop(t.locale==="zh"?`Grub \u8FDE\u7EED\u5931\u8D25 ${t.consecutiveFailures} \u6B21\u540E\u505C\u6B62\u3002\u6700\u8FD1\u9519\u8BEF\uFF1A${e}`:`Grub stopped after ${t.consecutiveFailures} consecutive failures. Last error: ${e}`,"failed")}:t.currentIteration>=t.maxIterations?{action:"stop",snapshot:this.stop(t.locale==="zh"?`Grub \u8FBE\u5230\u8F6E\u6B21\u4E0A\u9650\uFF08${t.maxIterations}\uFF09\u3002`:`Grub hit the iteration limit (${t.maxIterations}).`,"failed")}:(t.currentIteration+=1,this.safePersist(t),{action:"continue",task:{...t}})}generateTaskId(){return T(4).toString("hex").slice(0,8)}validateInitializerStructure(e){const a=this.activeTask?.locale??"en",i=a==="zh"?"\uFF08\u4EA7\u51FA\u4E00\u4EFD\u5E72\u51C0\u7684\u6E05\u5355\u540E\uFF0C\u7CFB\u7EDF\u4F1A\u81EA\u52A8\u4ECE\u521D\u59CB\u5316\u9636\u6BB5\u8FDB\u5165\u6267\u884C\u9636\u6BB5\uFF0C\u5C4A\u65F6\u624D\u9010\u4E2A\u6807\u8BB0 passes\u3002\uFF09":" (Once the list is structurally clean, the harness automatically moves from the initializer to the execution phase, where you mark passes one by one.)";if(e.features.length<h||e.features.length>d)return a==="zh"?`\u521D\u59CB\u5316\u9636\u6BB5\u5FC5\u987B\u751F\u6210 ${h}-${d} \u4E2A feature\u3002${i}`:`Initializer must produce ${h}-${d} features.${i}`;const s=new Set;for(const r of e.features){if(r.id==="placeholder-expand-features")return a==="zh"?`\u521D\u59CB\u5316\u9636\u6BB5\u5FC5\u987B\u66FF\u6362 placeholder feature\u3002${i}`:`Initializer must replace the placeholder feature.${i}`;if(!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(r.id))return a==="zh"?`feature id \u5FC5\u987B\u662F kebab-case\uFF1A${r.id}`:`feature id must be kebab-case: ${r.id}`;if(s.has(r.id))return a==="zh"?`feature id \u91CD\u590D\uFF1A${r.id}`:`duplicate feature id: ${r.id}`;s.add(r.id)}}cloneFeatureList(e){return{version:e.version,goal:e.goal,features:e.features.map(t=>({...t,steps:[...t.steps]}))}}safePersist(e){try{$(e)}catch(t){const a=t instanceof Error?t.message:String(t);console.error(`[Grub] Failed to persist task ${e.id} state: ${a}`)}}}export{G as GrubController};

package/dist/extensions/builtin/grub/grub-decision.d.ts

@@ -0,0 +1,8 @@
+/**
+ * [WHO]: Provides extractGrubDecision()
+ * [FROM]: Depends on ./grub-types for GrubDecision
+ * [TO]: Consumed by ./index.ts and tests for assistant loop-state parsing
+ * [HERE]: extensions/builtin/grub/grub-decision.ts - protocol parser for Grub assistant round summaries
+ */
+import type { GrubDecision } from "./grub-types.js";
+export declare function extractGrubDecision(text: string): GrubDecision | undefined;

package/dist/extensions/builtin/grub/grub-decision.js

@@ -0,0 +1 @@
+var a=Object.defineProperty;var r=(n,e)=>a(n,"name",{value:e,configurable:!0});const u=/<loop-state>([\s\S]*?)<\/loop-state>/gi;function f(n){const e=i(n);if(e)try{const t=JSON.parse(c(e));if(t.status!=="continue"&&t.status!=="complete"&&t.status!=="blocked")return;const s=typeof t.summary=="string"?t.summary.trim():"",o=typeof t.nextStep=="string"?t.nextStep.trim():void 0;return!s||t.status==="continue"&&!o?void 0:o?{status:t.status,summary:s,nextStep:o}:{status:t.status,summary:s}}catch{return}}r(f,"extractGrubDecision");function i(n){let e;for(const t of n.matchAll(u)){const s=t[1]?.trim();s&&(e=s)}return e}r(i,"extractLastLoopStatePayload");function c(n){const e=n.trim();return/^```(?:json)?\s*([\s\S]*?)\s*```$/i.exec(e)?.[1]?.trim()??e}r(c,"stripMarkdownFence");export{f as extractGrubDecision};

package/dist/extensions/builtin/grub/grub-feature-list.d.ts

@@ -0,0 +1,54 @@
+import { type FeatureItem, type FeatureList } from "./grub-types.js";
+export declare class FeatureListDiffError extends Error {
+    constructor(message: string);
+}
+export declare function isFeatureList(value: unknown): value is FeatureList;
+export declare function readFeatureList(path: string): FeatureList | null;
+export declare function writeFeatureList(path: string, list: FeatureList): void;
+/**
+ * Validates that a mutated feature list only differs from the baseline in
+ * per-item `passes` and `evidence` fields. Returns the validated list (or
+ * throws FeatureListDiffError). If the agent reordered, added, or removed
+ * entries, that counts as a violation.
+ */
+export declare function validateFeatureListDiff(before: FeatureList, after: FeatureList): FeatureList;
+export interface InitializerSanitizeResult {
+    list: FeatureList;
+    /** Human-readable tags describing what was auto-corrected, e.g. ["goal", "passes×6"]. */
+    fixes: string[];
+}
+/**
+ * Bring an initializer-produced feature list into a clean, executable baseline.
+ *
+ * The initializer's sole job is to stand up a harness; the `goal`, `passes`,
+ * and `evidence` fields are either authoritative-from-elsewhere or
+ * not-yet-earned. Rather than failing the whole turn over these recoverable
+ * hygiene issues (which would also block the initializer→execution phase
+ * transition), we auto-correct them: overwrite `goal` with the authoritative
+ * task goal, force every `passes` to false, and drop stray `evidence`. Returns
+ * the sanitized list plus a list of what was corrected so callers can surface
+ * a friendly note instead of a hard error.
+ */
+export declare function sanitizeInitializerFeatureList(list: FeatureList, authoritativeGoal: string): InitializerSanitizeResult;
+export declare function countPassing(list: FeatureList): number;
+export declare function allPassing(list: FeatureList): boolean;
+export declare function firstPending(list: FeatureList): FeatureItem | undefined;
+/**
+ * Produce an initial feature list skeleton for a new grub task. The
+ * initializer agent is expected to replace this placeholder with 15-40
+ * concrete feature entries in its first turn, preserving the schema.
+ */
+export declare function createInitialFeatureList(goal: string): FeatureList;
+/**
+ * Migrate a legacy feature-checklist.md (one checkbox per line) into the new
+ * feature-list.json format. Extremely lossy by design: we only copy line
+ * descriptions; category defaults to functional and steps is left empty so
+ * the initializer can refine later.
+ */
+export declare function migrateChecklistToFeatureList(checklistPath: string, goal: string): FeatureList | null;
+/**
+ * Convenience: return the feature list path that sits alongside a checklist
+ * markdown file. Pure path logic so callers don't have to repeat it.
+ */
+export declare function defaultFeatureListPath(harnessDirectory: string): string;
+export declare function ensureParentDirectory(path: string): void;

package/dist/extensions/builtin/grub/grub-feature-list.js

@@ -0,0 +1,2 @@
+var y=Object.defineProperty;var s=(t,e)=>y(t,"name",{value:e,configurable:!0});import{randomBytes as w}from"node:crypto";import{existsSync as l,mkdirSync as x,readFileSync as h,renameSync as v,writeFileSync as $}from"node:fs";import{dirname as F,join as S}from"node:path";import{FEATURE_LIST_VERSION as d}from"./grub-types.js";const I=new Set(["functional","verification","polish"]);class f extends Error{static{s(this,"FeatureListDiffError")}constructor(e){super(e),this.name="FeatureListDiffError"}}function L(t){if(!t||typeof t!="object")return!1;const e=t;return!(typeof e.id!="string"||!e.id||typeof e.description!="string"||!e.description||typeof e.category!="string"||!I.has(e.category)||!Array.isArray(e.steps)||!e.steps.every(n=>typeof n=="string")||typeof e.passes!="boolean"||e.evidence!==void 0&&typeof e.evidence!="string")}s(L,"isFeatureItem");function m(t){if(!t||typeof t!="object")return!1;const e=t;return e.version!==d||typeof e.goal!="string"||!Array.isArray(e.features)?!1:e.features.every(L)}s(m,"isFeatureList");function P(t){if(!l(t))return null;try{const e=h(t,"utf-8"),n=JSON.parse(e);return m(n)?n:null}catch{return null}}s(P,"readFeatureList");function j(t,e){if(!m(e))throw new f("Refusing to write invalid feature list shape.");const n=`${JSON.stringify(e,null,2)}
+`,a=`${t}.${w(6).toString("hex")}.tmp`;$(a,n,"utf-8"),v(a,t)}s(j,"writeFeatureList");function k(t,e){if(e.version!==t.version)throw new f(`version changed from ${t.version} to ${e.version}`);if(e.goal!==t.goal)throw new f("goal field is immutable");if(e.features.length!==t.features.length)throw new f(`feature count changed (${t.features.length} -> ${e.features.length}); agent may not add or remove features`);const n=new Map(t.features.map(i=>[i.id,i])),a=new Set;for(let i=0;i<e.features.length;i+=1){const r=e.features[i],c=t.features[i];if(a.has(r.id))throw new f(`duplicate feature id ${r.id}`);if(a.add(r.id),c?.id!==r.id)throw new f(`feature order changed at index ${i}`);const o=n.get(r.id);if(!o)throw new f(`unknown feature id ${r.id}`);if(r.description!==o.description)throw new f(`description for ${r.id} is immutable`);if(r.category!==o.category)throw new f(`category for ${r.id} is immutable`);if(r.steps.length!==o.steps.length)throw new f(`steps for ${r.id} must not change length`);for(let u=0;u<r.steps.length;u+=1)if(r.steps[u]!==o.steps[u])throw new f(`steps[${u}] for ${r.id} is immutable`);if(o.evidence!==void 0&&r.evidence===void 0)throw new f(`evidence for ${r.id} may not be removed once set`)}return e}s(k,"validateFeatureListDiff");function z(t,e){const n=[];t.goal!==e&&n.push("goal");let a=0,i=0;const r=t.features.map(c=>{const o={...c,steps:[...c.steps]};return o.passes&&(o.passes=!1,a+=1),o.evidence!==void 0&&(delete o.evidence,i+=1),o});return a>0&&n.push(`passes\xD7${a}`),i>0&&n.push(`evidence\xD7${i}`),{list:{version:t.version,goal:e,features:r},fixes:n}}s(z,"sanitizeInitializerFeatureList");function O(t){return t.features.reduce((e,n)=>e+(n.passes?1:0),0)}s(O,"countPassing");function T(t){return t.features.length>0&&t.features.every(e=>e.passes)}s(T,"allPassing");function N(t){return t.features.find(e=>!e.passes)}s(N,"firstPending");function _(t){return{version:d,goal:t,features:[{id:"placeholder-expand-features",category:"functional",description:"Initializer must replace this placeholder with 15-40 concrete, end-to-end testable features.",steps:["Read the goal carefully","Enumerate atomic user-observable behaviors","Rewrite this file with proper features[] entries"],passes:!1}]}}s(_,"createInitialFeatureList");function C(t,e){if(!l(t))return null;let n;try{n=h(t,"utf-8")}catch{return null}const a=[],i=/^\s*-\s*\[( |x|X)\]\s*(.+?)\s*$/,r=n.split(/\r?\n/);let c=0;for(const o of r){const u=i.exec(o);if(!u)continue;const[,p,g]=u;g&&(c+=1,a.push({id:`migrated-${c}`,category:"functional",description:g,steps:[],passes:p==="x"||p==="X"}))}return a.length===0?null:{version:d,goal:e,features:a}}s(C,"migrateChecklistToFeatureList");function J(t){return S(t,"feature-list.json")}s(J,"defaultFeatureListPath");function V(t){const e=F(t);l(e)||x(e,{recursive:!0})}s(V,"ensureParentDirectory");export{f as FeatureListDiffError,T as allPassing,O as countPassing,_ as createInitialFeatureList,J as defaultFeatureListPath,V as ensureParentDirectory,N as firstPending,m as isFeatureList,C as migrateChecklistToFeatureList,P as readFeatureList,z as sanitizeInitializerFeatureList,k as validateFeatureListDiff,j as writeFeatureList};

package/dist/extensions/builtin/grub/grub-format.d.ts

@@ -0,0 +1,13 @@
+/**
+ * [WHO]: Provides formatTaskState(), formatSnapshot(), describeDecision(), describeTerminalSnapshot(), describeTaskState()
+ * [FROM]: Depends on ./grub-feature-list, ./grub-i18n, ./grub-types for human-readable /grub TUI copy
+ * [TO]: Consumed by ./index.ts and tests for status/result rendering
+ * [HERE]: extensions/builtin/grub/grub-format.ts - user-facing formatting boundary for Grub status messages
+ */
+import { type GrubLocale } from "./grub-i18n.js";
+import type { GrubDecision, GrubTaskSnapshot, GrubTaskState } from "./grub-types.js";
+export declare function formatTaskState(task: GrubTaskState): string;
+export declare function formatSnapshot(snapshot: GrubTaskSnapshot): string;
+export declare function describeDecision(decision: GrubDecision, locale: GrubLocale): string;
+export declare function describeTerminalSnapshot(snapshot: GrubTaskSnapshot | undefined, locale: GrubLocale): string;
+export declare function describeTaskState(status: GrubTaskState["status"], phase: GrubTaskState["phase"], awaitingTurn: boolean, locale: GrubLocale): string;

package/dist/extensions/builtin/grub/grub-format.js

@@ -0,0 +1,4 @@
+var l=Object.defineProperty;var s=(e,t)=>l(e,"name",{value:t,configurable:!0});import{readFeatureList as c}from"./grub-feature-list.js";import{grubText as o}from"./grub-i18n.js";function g(e){const t=o(e.locale??"en"),r=c(e.featureListPath),i=[`${t.prefix} ${t.activeTask} ${e.id}`,`${t.task}: ${e.goal}`,`${t.state}: ${a(e.status,e.phase,e.awaitingTurn,e.locale)}`,`${t.round}: ${e.currentIteration}/${e.maxIterations}`];if(r){const n=r.features.length,u=r.features.filter($=>$.passes).length;i.push(t.featuresPassing(u,n))}else i.push(t.unknownProgress);return e.lastDecision?.summary&&i.push(`${t.lastUpdate}: ${e.lastDecision.summary}`),e.lastDecision?.nextStep&&i.push(`${t.next}: ${e.lastDecision.nextStep}`),e.lastError&&i.push(`${t.lastIssue}: ${e.lastError}`),i.push(`${t.savedIn}: ${e.harnessDirectory}`),i.push(`${t.taskFiles}: ${e.featureListPath}, ${e.progressLogPath}`),i.push(t.advancedJson),i.join(`
+`)}s(g,"formatTaskState");function f(e){const t=e.locale??"en",r=o(t),i=[`${r.prefix} ${r.lastTask} ${e.id}`,`${r.task}: ${e.goal}`,`${r.state}: ${a(e.status,e.phase,!1,t)}`,`${r.round}: ${e.completedIterations}`,`${r.updated}: ${p(e.updatedAt,t)}`];return e.lastDecision?.summary&&i.push(`${r.lastUpdate}: ${e.lastDecision.summary}`),e.lastDecision?.nextStep&&i.push(`${r.next}: ${e.lastDecision.nextStep}`),e.lastError&&i.push(`${r.lastIssue}: ${e.lastError}`),i.push(`${r.savedIn}: ${e.harnessDirectory}`),i.push(`${r.taskFiles}: ${e.featureListPath}, ${e.progressLogPath}`),i.join(`
+`)}s(f,"formatSnapshot");function h(e,t){const r=o(t),i=[`${r.prefix} ${r.lastUpdate}: ${e.summary}`];return e.nextStep&&i.push(`${r.nextStep}: ${e.nextStep}`),i.join(`
+`)}s(h,"describeDecision");function S(e,t){return e?f(e):`${o(t).prefix} ${o(t).noActive}`}s(S,"describeTerminalSnapshot");function a(e,t,r,i){const n=o(i);return e==="complete"?n.finished:e==="blocked"?n.blocked:e==="stopped"?n.stoppedState:e==="failed"?n.failed:r?n.waiting:t==="initializer"?n.preparing:n.working}s(a,"describeTaskState");function p(e,t){return new Date(e).toLocaleString(t==="zh"?"zh-CN":"en-US")}s(p,"formatDate");export{h as describeDecision,a as describeTaskState,S as describeTerminalSnapshot,f as formatSnapshot,g as formatTaskState};

package/dist/extensions/builtin/grub/grub-harness.d.ts

@@ -0,0 +1,9 @@
+/**
+ * [WHO]: Provides ensureHarnessArtifacts(), buildInitScript()
+ * [FROM]: Depends on node:fs, ./grub-feature-list, ./grub-i18n, ./grub-types for durable harness files
+ * [TO]: Consumed by ./index.ts when starting or resuming /grub tasks
+ * [HERE]: extensions/builtin/grub/grub-harness.ts - filesystem artifact boundary for .grub/<id>/
+ */
+import type { GrubTaskState } from "./grub-types.js";
+export declare function buildInitScript(task: GrubTaskState): string;
+export declare function ensureHarnessArtifacts(task: GrubTaskState): void;

package/dist/extensions/builtin/grub/grub-harness.js

@@ -0,0 +1,3 @@
+var n=Object.defineProperty;var i=(e,t)=>n(e,"name",{value:t,configurable:!0});import{chmodSync as s,existsSync as r,mkdirSync as c,writeFileSync as o}from"node:fs";import{createInitialFeatureList as l,migrateChecklistToFeatureList as a,writeFeatureList as u}from"./grub-feature-list.js";import{grubText as h}from"./grub-i18n.js";function g(e){const t=e.locale==="zh";return["#!/usr/bin/env bash","set -euo pipefail","",t?"# Grub harness \u542F\u52A8\u811A\u672C\uFF08get-bearings \u534F\u8BAE\uFF09\u3002\u8BF7\u5C06\u4E0B\u65B9\u70DF\u6D4B\u66FF\u6362\u4E3A\u9879\u76EE\u4E13\u5C5E\u547D\u4EE4\uFF0C":"# Grub harness startup (get-bearings protocol). Override the smoke block below",t?"# \u7528\u6765\u8BC1\u660E\u5E94\u7528\u4ECD\u80FD\u7AEF\u5230\u7AEF\u542F\u52A8\u3002":"# with project-specific commands that prove the app still boots end-to-end.","",'echo "=== grub bearings ==="',"pwd",'echo "--- recent commits ---"',"git log --oneline -n 20 2>/dev/null || true",'echo "--- working tree ---"',"git status --short 2>/dev/null || true",'echo "--- progress tail ---"',`tail -n 40 ${JSON.stringify(e.progressLogPath)} 2>/dev/null || true`,'echo "--- feature progress ---"',`node -e "try{const l=require(${JSON.stringify(e.featureListPath)});const p=l.features.filter(f=>f.passes).length;console.log(p+'/'+l.features.length+' passing');}catch(e){console.log('feature-list.json unavailable');}" 2>/dev/null || true`,'echo "--- project smoke (override below) ---"',t?"# TODO: \u9879\u76EE\u4E13\u5C5E\u70DF\u6D4B\u547D\u4EE4\uFF08tests\u3001curl\u3001tsc --noEmit \u7B49\uFF09":"# TODO: project-specific smoke command (tests, curl, tsc --noEmit, etc.)",""].join(`
+`)}i(g,"buildInitScript");function b(e){if(r(e.harnessDirectory)||c(e.harnessDirectory,{recursive:!0}),!r(e.featureListPath)){const t=r(e.featureChecklistPath)?a(e.featureChecklistPath,e.goal):null;u(e.featureListPath,t??l(e.goal))}if(!r(e.progressLogPath)){const t=h(e.locale);o(e.progressLogPath,[t.progressLogTitle(e.id),"",`${t.goal}: ${e.goal}`,"",t.initializationHeading,t.harnessCreated,t.structuredFeatureNote,t.initScriptNote,"",t.iterationsHeading,t.appendIterationNote,""].join(`
+`),"utf-8")}r(e.initScriptPath)||(o(e.initScriptPath,g(e),"utf-8"),s(e.initScriptPath,493))}i(b,"ensureHarnessArtifacts");export{g as buildInitScript,b as ensureHarnessArtifacts};

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

@@ -0,0 +1,166 @@
+/**
+ * [WHO]: Provides detectGrubLocale(), grubText(), type GrubLocale for localized /grub prompts and TUI messages
+ * [FROM]: Depends on core/platform/i18n locale type
+ * [TO]: Consumed by grub-controller.ts, grub-parser.ts, index.ts for user-language-aware Grub UX
+ * [HERE]: extensions/builtin/grub/grub-i18n.ts - small locale helper scoped to the Grub extension
+ */
+import type { Locale } from "../../../core/platform/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 a focused long-running task", "  /grub status [--json]                        Show progress", "  /grub resume                                 Continue a saved task", "  /grub stop                                   Stop the current task", "", "[Grub] Progress is saved under .grub/<task-id>/ so it can continue later.", "Use /grub status --json only when you need the full saved details.", "", "[Grub] The task keeps working until it finishes, gets blocked, is stopped,", "or reaches a safety limit. It cannot mark itself done while checklist items remain."];
+        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 review progress, /grub resume to continue, or /grub stop to abandon it.";
+        readonly startingIteration: (iteration: number, id: string) => string;
+        readonly startedTask: (id: string) => string;
+        readonly initPhase: "First step: create the task checklist and a repeatable smoke check before changing code.";
+        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: "There is no saved grub task to continue.";
+        readonly failedResume: (id: string, message: string) => string;
+        readonly failedAdopt: (message: string) => string;
+        readonly failedNoAssistant: "This round ended without a usable update.";
+        readonly iterationFailedRetry: (iteration: number | undefined) => string;
+        readonly invalidLoopState: "I could not read the round summary from the assistant response.";
+        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 task: "Task";
+        readonly progress: "Progress";
+        readonly round: "Round";
+        readonly state: "State";
+        readonly savedIn: "Saved in";
+        readonly taskFiles: "Task files";
+        readonly next: "Next";
+        readonly lastUpdate: "Last update";
+        readonly lastIssue: "Needs attention";
+        readonly preparing: "Preparing checklist and smoke check";
+        readonly working: "Working through the checklist";
+        readonly waiting: "waiting for this round to finish";
+        readonly ready: "ready for the next round";
+        readonly finished: "finished";
+        readonly blocked: "blocked";
+        readonly stoppedState: "stopped";
+        readonly failed: "stopped after repeated issues";
+        readonly unknownProgress: "Progress: checklist not ready yet";
+        readonly advancedJson: "Use /grub status --json for full saved details.";
+    };
+    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>/，之后可以继续。", "只有需要完整保存细节时，才使用 /grub status --json。", "", "[Grub] 任务会持续推进，直到完成、阻塞、被停止，或触发安全上限。", "只要清单里还有未完成项，它就不能把自己标记为完成。"];
+        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: "第一步：先建立任务清单和可重复的烟测，再修改代码。";
+        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: "这一轮没有得到可用更新。";
+        readonly iterationFailedRetry: (iteration: number | undefined) => string;
+        readonly invalidLoopState: "我无法从 assistant 回复中读到本轮总结。";
+        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: "## 初始化";
+        readonly task: "任务";
+        readonly progress: "进度";
+        readonly round: "轮次";
+        readonly state: "状态";
+        readonly savedIn: "保存位置";
+        readonly taskFiles: "任务文件";
+        readonly next: "下一步";
+        readonly lastUpdate: "最近更新";
+        readonly lastIssue: "需要注意";
+        readonly preparing: "正在准备清单和烟测";
+        readonly working: "正在按清单推进";
+        readonly waiting: "正在等待本轮完成";
+        readonly ready: "可继续下一轮";
+        readonly finished: "已完成";
+        readonly blocked: "已阻塞";
+        readonly stoppedState: "已停止";
+        readonly failed: "因连续问题已停止";
+        readonly unknownProgress: "进度：清单尚未准备好";
+        readonly advancedJson: "如需完整保存细节，可使用 /grub status --json。";
+    };
+};
+export {};

package/dist/extensions/builtin/grub/grub-i18n.js

@@ -0,0 +1 @@
+var a=Object.defineProperty;var t=(e,s)=>a(e,"name",{value:s,configurable:!0});function u(e,s="en"){return i(e)?"zh":s}t(u,"detectGrubLocale");function d(e){return e==="zh"?"\u4E2D\u6587":"English"}t(d,"languageName");function g(e){return n[e]}t(g,"grubText");function i(e){return/[\u3400-\u9fff]/.test(e)}t(i,"hasCjk");const n={en:{prefix:"[Grub]",missingGoal:"Missing grub goal.",usage:["[Grub] Usage:","  /grub <goal> [--max-iter N] [--max-fail N]   Start a focused long-running task","  /grub status [--json]                        Show progress","  /grub resume                                 Continue a saved task","  /grub stop                                   Stop the current task","","[Grub] Progress is saved under .grub/<task-id>/ so it can continue later.","Use /grub status --json only when you need the full saved details.","","[Grub] The task keeps working until it finishes, gets blocked, is stopped,","or reaches a safety limit. It cannot mark itself done while checklist items remain."],activeTask:"Active task",lastTask:"Last task",status:"Status",phase:"Phase",goal:"Goal",started:"Started",updated:"Updated",currentIteration:"Current iteration",completedIterations:"Completed iterations",awaitingResult:"Awaiting result",yes:"yes",no:"no",consecutiveFailures:"Consecutive failures",maxIterations:"Max iterations",harnessDir:"Harness dir",featureList:"Feature list",progressLog:"Progress log",initScript:"Init script",stateFile:"State file",featuresPassing:t((e,s)=>`Progress: ${e}/${s} checks done`,"featuresPassing"),lastSummary:"Last summary",lastNextStep:"Last next step",lastError:"Last error",noActive:"No grub task is active.",noStarted:"No grub task has been started in this session.",decision:"Decision",summary:"Summary",nextStep:"Next step",resumeSummary:t((e,s,r)=>`[Grub] Found saved task ${e}. Next run will continue from round ${s} (${r}).`,"resumeSummary"),resumeHint:"Use /grub status to review progress, /grub resume to continue, or /grub stop to abandon it.",startingIteration:t((e,s)=>`[Grub] Working on ${s}, round ${e}.`,"startingIteration"),startedTask:t(e=>`[Grub] Started task ${e}.`,"startedTask"),initPhase:"First step: create the task checklist and a repeatable smoke check before changing code.",safetyLimits:t((e,s)=>`Safety limits: up to ${e} rounds; stops after ${s} failed rounds in a row.`,"safetyLimits"),resuming:t(e=>`[Grub] Continuing task ${e}.`,"resuming"),stopped:t(e=>`[Grub] Stopped task ${e}.`,"stopped"),noActiveRunning:"No active grub task is running.",noPersisted:"There is no saved grub task to continue.",failedResume:t((e,s)=>`[Grub] Could not continue task ${e}: ${s}`,"failedResume"),failedAdopt:t(e=>`[Grub] Could not load the saved task: ${e}`,"failedAdopt"),failedNoAssistant:"This round ended without a usable update.",iterationFailedRetry:t(e=>`[Grub] That round did not finish cleanly. Retrying round ${e}.`,"iterationFailedRetry"),invalidLoopState:"I could not read the round summary from the assistant response.",invalidLoopRetry:t(e=>`[Grub] I could not read the round summary. Retrying round ${e}.`,"invalidLoopRetry"),prematureComplete:t(e=>`[Grub] Not done yet: ${e}. Continuing.`,"prematureComplete"),harnessCreated:"- Harness created by /grub.",structuredFeatureNote:"- Structured feature list lives in feature-list.json; only passes/evidence may change.",initScriptNote:"- init.sh performs get-bearings + smoke before every iteration.",iterationsHeading:"## Iterations",appendIterationNote:"- (append one short entry per iteration with verification evidence)",progressLogTitle:t(e=>`# Progress Log (${e})`,"progressLogTitle"),initializationHeading:"## Initialization",task:"Task",progress:"Progress",round:"Round",state:"State",savedIn:"Saved in",taskFiles:"Task files",next:"Next",lastUpdate:"Last update",lastIssue:"Needs attention",preparing:"Preparing checklist and smoke check",working:"Working through the checklist",waiting:"waiting for this round to finish",ready:"ready for the next round",finished:"finished",blocked:"blocked",stoppedState:"stopped",failed:"stopped after repeated issues",unknownProgress:"Progress: checklist not ready yet",advancedJson:"Use /grub status --json for full saved details."},zh:{prefix:"[Grub]",missingGoal:"\u7F3A\u5C11 grub \u76EE\u6807\u3002",usage:["[Grub] \u7528\u6CD5\uFF1A","  /grub <\u76EE\u6807> [--max-iter N] [--max-fail N]   \u542F\u52A8\u4E00\u4E2A\u805A\u7126\u7684\u957F\u4EFB\u52A1","  /grub status [--json]                        \u67E5\u770B\u8FDB\u5EA6","  /grub resume                                 \u7EE7\u7EED\u5DF2\u4FDD\u5B58\u7684\u4EFB\u52A1","  /grub stop                                   \u505C\u6B62\u5F53\u524D\u4EFB\u52A1","","[Grub] \u8FDB\u5EA6\u4F1A\u4FDD\u5B58\u5728 .grub/<task-id>/\uFF0C\u4E4B\u540E\u53EF\u4EE5\u7EE7\u7EED\u3002","\u53EA\u6709\u9700\u8981\u5B8C\u6574\u4FDD\u5B58\u7EC6\u8282\u65F6\uFF0C\u624D\u4F7F\u7528 /grub status --json\u3002","","[Grub] \u4EFB\u52A1\u4F1A\u6301\u7EED\u63A8\u8FDB\uFF0C\u76F4\u5230\u5B8C\u6210\u3001\u963B\u585E\u3001\u88AB\u505C\u6B62\uFF0C\u6216\u89E6\u53D1\u5B89\u5168\u4E0A\u9650\u3002","\u53EA\u8981\u6E05\u5355\u91CC\u8FD8\u6709\u672A\u5B8C\u6210\u9879\uFF0C\u5B83\u5C31\u4E0D\u80FD\u628A\u81EA\u5DF1\u6807\u8BB0\u4E3A\u5B8C\u6210\u3002"],activeTask:"\u5F53\u524D\u4EFB\u52A1",lastTask:"\u6700\u8FD1\u4EFB\u52A1",status:"\u72B6\u6001",phase:"\u9636\u6BB5",goal:"\u76EE\u6807",started:"\u5F00\u59CB\u65F6\u95F4",updated:"\u66F4\u65B0\u65F6\u95F4",currentIteration:"\u5F53\u524D\u8F6E\u6B21",completedIterations:"\u5DF2\u5B8C\u6210\u8F6E\u6B21",awaitingResult:"\u7B49\u5F85\u7ED3\u679C",yes:"\u662F",no:"\u5426",consecutiveFailures:"\u8FDE\u7EED\u5931\u8D25",maxIterations:"\u6700\u5927\u8F6E\u6B21",harnessDir:"Harness \u76EE\u5F55",featureList:"\u529F\u80FD\u6E05\u5355",progressLog:"\u8FDB\u5EA6\u65E5\u5FD7",initScript:"\u521D\u59CB\u5316\u811A\u672C",stateFile:"\u72B6\u6001\u6587\u4EF6",featuresPassing:t((e,s)=>`\u8FDB\u5EA6\uFF1A${e}/${s} \u9879\u5DF2\u5B8C\u6210`,"featuresPassing"),lastSummary:"\u4E0A\u6B21\u603B\u7ED3",lastNextStep:"\u4E0B\u4E00\u6B65",lastError:"\u6700\u8FD1\u9519\u8BEF",noActive:"\u5F53\u524D\u6CA1\u6709 grub \u4EFB\u52A1\u3002",noStarted:"\u672C\u4F1A\u8BDD\u8FD8\u6CA1\u6709\u542F\u52A8 grub \u4EFB\u52A1\u3002",decision:"\u51B3\u7B56",summary:"\u603B\u7ED3",nextStep:"\u4E0B\u4E00\u6B65",resumeSummary:t((e,s,r)=>`[Grub] \u627E\u5230\u5DF2\u4FDD\u5B58\u4EFB\u52A1 ${e}\u3002\u7EE7\u7EED\u65F6\u4F1A\u4ECE\u7B2C ${s} \u8F6E\u5F00\u59CB\uFF08${r}\uFF09\u3002`,"resumeSummary"),resumeHint:"\u53EF\u7528 /grub status \u67E5\u770B\u8FDB\u5EA6\uFF0C/grub resume \u7EE7\u7EED\uFF0C\u6216 /grub stop \u653E\u5F03\u3002",startingIteration:t((e,s)=>`[Grub] \u6B63\u5728\u63A8\u8FDB\u4EFB\u52A1 ${s}\uFF0C\u7B2C ${e} \u8F6E\u3002`,"startingIteration"),startedTask:t(e=>`[Grub] \u5DF2\u542F\u52A8\u4EFB\u52A1 ${e}\u3002`,"startedTask"),initPhase:"\u7B2C\u4E00\u6B65\uFF1A\u5148\u5EFA\u7ACB\u4EFB\u52A1\u6E05\u5355\u548C\u53EF\u91CD\u590D\u7684\u70DF\u6D4B\uFF0C\u518D\u4FEE\u6539\u4EE3\u7801\u3002",safetyLimits:t((e,s)=>`\u5B89\u5168\u4E0A\u9650\uFF1A\u6700\u591A ${e} \u8F6E\uFF1B\u8FDE\u7EED ${s} \u8F6E\u5931\u8D25\u540E\u505C\u6B62\u3002`,"safetyLimits"),resuming:t(e=>`[Grub] \u7EE7\u7EED\u4EFB\u52A1 ${e}\u3002`,"resuming"),stopped:t(e=>`[Grub] \u5DF2\u505C\u6B62\u4EFB\u52A1 ${e}\u3002`,"stopped"),noActiveRunning:"\u5F53\u524D\u6CA1\u6709\u6B63\u5728\u8FD0\u884C\u7684 grub \u4EFB\u52A1\u3002",noPersisted:"\u6CA1\u6709\u53EF\u7EE7\u7EED\u7684\u5DF2\u4FDD\u5B58 grub \u4EFB\u52A1\u3002",failedResume:t((e,s)=>`[Grub] \u65E0\u6CD5\u7EE7\u7EED\u4EFB\u52A1 ${e}\uFF1A${s}`,"failedResume"),failedAdopt:t(e=>`[Grub] \u65E0\u6CD5\u8BFB\u53D6\u5DF2\u4FDD\u5B58\u4EFB\u52A1\uFF1A${e}`,"failedAdopt"),failedNoAssistant:"\u8FD9\u4E00\u8F6E\u6CA1\u6709\u5F97\u5230\u53EF\u7528\u66F4\u65B0\u3002",iterationFailedRetry:t(e=>`[Grub] \u8FD9\u4E00\u8F6E\u6CA1\u6709\u6B63\u5E38\u5B8C\u6210\uFF0C\u51C6\u5907\u91CD\u8BD5\u7B2C ${e} \u8F6E\u3002`,"iterationFailedRetry"),invalidLoopState:"\u6211\u65E0\u6CD5\u4ECE assistant \u56DE\u590D\u4E2D\u8BFB\u5230\u672C\u8F6E\u603B\u7ED3\u3002",invalidLoopRetry:t(e=>`[Grub] \u6211\u65E0\u6CD5\u8BFB\u5230\u672C\u8F6E\u603B\u7ED3\uFF0C\u51C6\u5907\u91CD\u8BD5\u7B2C ${e} \u8F6E\u3002`,"invalidLoopRetry"),prematureComplete:t(e=>`[Grub] \u8FD8\u4E0D\u80FD\u7ED3\u675F\uFF1A${e}\u3002\u7EE7\u7EED\u6267\u884C\u3002`,"prematureComplete"),harnessCreated:"- Harness \u7531 /grub \u521B\u5EFA\u3002",structuredFeatureNote:"- \u7ED3\u6784\u5316\u529F\u80FD\u6E05\u5355\u4F4D\u4E8E feature-list.json\uFF1B\u540E\u7EED\u53EA\u80FD\u4FEE\u6539 passes/evidence\u3002",initScriptNote:"- \u6BCF\u8F6E\u5F00\u59CB\u524D\u7531 init.sh \u6267\u884C\u73AF\u5883\u5B9A\u4F4D\u548C\u70DF\u6D4B\u3002",iterationsHeading:"## \u8FED\u4EE3\u8BB0\u5F55",appendIterationNote:"- \uFF08\u6BCF\u8F6E\u8FFD\u52A0\u4E00\u6761\u7B80\u77ED\u8BB0\u5F55\uFF0C\u5305\u542B\u9A8C\u8BC1\u8BC1\u636E\uFF09",progressLogTitle:t(e=>`# \u8FDB\u5EA6\u65E5\u5FD7\uFF08${e}\uFF09`,"progressLogTitle"),initializationHeading:"## \u521D\u59CB\u5316",task:"\u4EFB\u52A1",progress:"\u8FDB\u5EA6",round:"\u8F6E\u6B21",state:"\u72B6\u6001",savedIn:"\u4FDD\u5B58\u4F4D\u7F6E",taskFiles:"\u4EFB\u52A1\u6587\u4EF6",next:"\u4E0B\u4E00\u6B65",lastUpdate:"\u6700\u8FD1\u66F4\u65B0",lastIssue:"\u9700\u8981\u6CE8\u610F",preparing:"\u6B63\u5728\u51C6\u5907\u6E05\u5355\u548C\u70DF\u6D4B",working:"\u6B63\u5728\u6309\u6E05\u5355\u63A8\u8FDB",waiting:"\u6B63\u5728\u7B49\u5F85\u672C\u8F6E\u5B8C\u6210",ready:"\u53EF\u7EE7\u7EED\u4E0B\u4E00\u8F6E",finished:"\u5DF2\u5B8C\u6210",blocked:"\u5DF2\u963B\u585E",stoppedState:"\u5DF2\u505C\u6B62",failed:"\u56E0\u8FDE\u7EED\u95EE\u9898\u5DF2\u505C\u6B62",unknownProgress:"\u8FDB\u5EA6\uFF1A\u6E05\u5355\u5C1A\u672A\u51C6\u5907\u597D",advancedJson:"\u5982\u9700\u5B8C\u6574\u4FDD\u5B58\u7EC6\u8282\uFF0C\u53EF\u4F7F\u7528 /grub status --json\u3002"}};export{u as detectGrubLocale,g as grubText,d as languageName};

package/dist/extensions/builtin/grub/grub-parser.d.ts

@@ -0,0 +1,24 @@
+/**
+ * [WHO]: parseGrubCommand, buildGrubHelp, getGrubArgumentCompletions
+ * [FROM]: Depends on ./grub-types
+ * [TO]: Consumed by extension entry point (./index.ts)
+ * [HERE]: extensions/builtin/grub/grub-parser.ts - /grub command parser with resume/status --json/--max-iter/--max-fail flags
+ */
+import type { ParsedGrubCommand } from "./grub-types.js";
+import { type GrubLocale } from "./grub-i18n.js";
+type GrubArgumentCompletionContext = {
+    commandName: string;
+    argumentText: string;
+    argumentPrefix: string;
+    tokenIndex: number;
+    previousTokens: string[];
+};
+type GrubCompletionItem = {
+    value: string;
+    label: string;
+    description: string;
+};
+export declare function getGrubArgumentCompletions(argumentPrefix: string, context?: GrubArgumentCompletionContext): GrubCompletionItem[] | null;
+export declare function parseGrubCommand(input: string): ParsedGrubCommand;
+export declare function buildGrubHelp(reason?: string, locale?: GrubLocale): string;
+export {};

package/dist/extensions/builtin/grub/grub-parser.js

@@ -0,0 +1,2 @@
+var h=Object.defineProperty;var u=(s,t)=>h(s,"name",{value:t,configurable:!0});import{grubText as d}from"./grub-i18n.js";const x=[{value:"status",label:"status",description:"Show current progress"},{value:"resume",label:"resume",description:"Continue a saved task"},{value:"stop",label:"stop",description:"Stop the current task"},{value:"help",label:"help",description:"Show usage help"}],b=[{value:"--max-iter",label:"--max-iter",description:"Limit total work rounds"},{value:"--max-fail",label:"--max-fail",description:"Stop after repeated failed rounds"}],k=[{value:"--json",label:"--json",description:"Show full saved details"}];function g(s){const t=[];let e="",n,i=!1;for(const o of s.trim()){if(i){e+=o,i=!1;continue}if(o==="\\"&&n!=="'"){i=!0;continue}if((o==="'"||o==='"')&&!n){n=o;continue}if(o===n){n=void 0;continue}if(/\s/.test(o)&&!n){e&&(t.push(e),e="");continue}e+=o}return i&&(e+="\\"),e&&t.push(e),t}u(g,"scanTokens");function v(s){const t=g(s),e=[],n={},i=new Set(["max-iter","max-iterations","max-fail","max-failures"]);for(let o=0;o<t.length;o+=1){const r=t[o];if(r==="--"){e.push(...t.slice(o+1));break}if(r.startsWith("--")){const c=r.indexOf("=");if(c!==-1){const f=r.slice(2,c);i.has(f)||f==="json"?n[f]=r.slice(c+1):e.push(r);continue}const a=r.slice(2),p=t[o+1];i.has(a)&&p!==void 0?(n[a]=p,o+=1):a==="json"?n[a]=!0:e.push(r);continue}e.push(r)}return{positional:e,flags:n}}u(v,"tokenize");function m(s,t){const e=t.trim().toLowerCase(),n=s.filter(i=>i.value.startsWith(e));return n.length>0?[...n]:null}u(m,"filterCompletions");function T(s,t){if(s.trim().startsWith("--")){const e=t?.previousTokens[0]?.toLowerCase();return m(e==="status"||e==="list"?k:b,s)}return!t||t.tokenIndex===0?m(x,s):null}u(T,"getGrubArgumentCompletions");function l(s){if(typeof s!="string")return;const t=Number.parseInt(s,10);if(!(!Number.isFinite(t)||t<=0))return t}u(l,"parsePositiveInt");function j(s){const t=s.trim();if(!t)return{type:"help",reason:"empty"};const{positional:e,flags:n}=v(t),i=e[0]?.toLowerCase()??"";if(i==="status"||i==="list")return{type:"status",json:n.json===!0||n.json==="true"||e.includes("--json")};if(i==="stop"||i==="clear"||i==="cancel")return{type:"stop"};if(i==="resume"||i==="continue")return{type:"resume"};if(i==="help")return{type:"help"};const o=e.join(" ").trim();return o?{type:"start",goal:o,maxIterations:l(n["max-iter"])??l(n["max-iterations"]),maxConsecutiveFailures:l(n["max-fail"])??l(n["max-failures"])}:{type:"help",reason:"empty"}}u(j,"parseGrubCommand");function C(s,t="en"){const e=d(t),n=[];return s&&n.push(`${e.prefix} ${s}`),n.push(...e.usage),n.join(`
+`)}u(C,"buildGrubHelp");export{C as buildGrubHelp,T as getGrubArgumentCompletions,j as parseGrubCommand};

package/dist/extensions/builtin/grub/grub-persistence.d.ts

@@ -0,0 +1,17 @@
+import { type GrubTaskState, type PersistedGrubState } from "./grub-types.js";
+export declare function grubRoot(cwd: string): string;
+export declare function stateFilePathFor(harnessDirectory: string): string;
+export declare function persistState(task: GrubTaskState, createdAt?: number): void;
+export declare function loadState(stateFilePath: string): PersistedGrubState | null;
+/**
+ * Scan every ".grub/<id>/state.json" under cwd and return each persisted
+ * record whose task.status is "running". Invalid or unreadable files are
+ * skipped silently.
+ */
+export declare function discoverActiveTasks(cwd: string): PersistedGrubState[];
+/**
+ * Remove ".grub/<id>/" directories whose state is terminal and older than
+ * maxAgeMs. Returns the number of directories pruned. Missing or malformed
+ * state files are treated as expired regardless of age to avoid orphans.
+ */
+export declare function pruneStale(cwd: string, maxAgeMs?: number): number;

package/dist/extensions/builtin/grub/grub-persistence.js

@@ -0,0 +1,2 @@
+var L=Object.defineProperty;var r=(e,t)=>L(e,"name",{value:t,configurable:!0});import{randomBytes as T}from"node:crypto";import{existsSync as l,mkdirSync as N,readFileSync as _,readdirSync as A,renameSync as w,rmSync as k,statSync as h,writeFileSync as R}from"node:fs";import{dirname as B,join as p,resolve as D}from"node:path";import{isFeatureList as O}from"./grub-feature-list.js";import{PERSISTED_GRUB_STATE_VERSION as I}from"./grub-types.js";const M=".grub",j="state.json",V=720*60*60*1e3,v=new Set(["running","complete","blocked","stopped","failed"]),z=new Set(["initializer","execution"]),C=new Set(["en","zh"]),G=new Set(["continue","complete","blocked"]);function b(e){return p(e,M)}r(b,"grubRoot");function E(e){return p(e,j)}r(E,"stateFilePathFor");function U(e){l(e)||N(e,{recursive:!0})}r(U,"ensureDirectory");function $(e,t){U(B(e));const n=`${e}.${T(6).toString("hex")}.tmp`;R(n,t,"utf-8"),w(n,e)}r($,"atomicWrite");function J(e){if(!e||typeof e!="object")return!1;const t=e;return t.version!==I||!d(t.createdAt)||!d(t.lastPersistedAt)?!1:W(t.task)}r(J,"isPersistedShape");function W(e){if(!e||typeof e!="object")return!1;const t=e;return!(!o(t.id)||!o(t.goal)||typeof t.locale!="string"||!C.has(t.locale)||typeof t.status!="string"||!v.has(t.status)||typeof t.phase!="string"||!z.has(t.phase)||!d(t.startedAt)||!d(t.updatedAt)||!m(t.currentIteration)||typeof t.awaitingTurn!="boolean"||!P(t.consecutiveFailures)||t.consecutiveBlockedAttempts!==void 0&&!P(t.consecutiveBlockedAttempts)||!m(t.maxIterations)||!m(t.maxConsecutiveFailures)||t.maxInitializerFailures!==void 0&&!m(t.maxInitializerFailures)||!o(t.harnessDirectory)||!o(t.featureChecklistPath)||!o(t.featureListPath)||!o(t.stateFilePath)||!o(t.progressLogPath)||!o(t.initScriptPath)||t.featureListBaseline!==void 0&&!O(t.featureListBaseline)||t.lastDecision!==void 0&&!H(t.lastDecision)||t.lastError!==void 0&&typeof t.lastError!="string")}r(W,"isGrubTaskState");function H(e){if(!e||typeof e!="object")return!1;const t=e;return!(typeof t.status!="string"||!G.has(t.status)||typeof t.summary!="string"||t.nextStep!==void 0&&typeof t.nextStep!="string")}r(H,"isGrubDecision");function o(e){return typeof e=="string"&&e.length>0}r(o,"isNonEmptyString");function d(e){return typeof e=="number"&&Number.isFinite(e)}r(d,"isFiniteNumber");function m(e){return Number.isInteger(e)&&typeof e=="number"&&e>0}r(m,"isPositiveInteger");function P(e){return Number.isInteger(e)&&typeof e=="number"&&e>=0}r(P,"isNonNegativeInteger");function et(e,t){const n=Date.now(),i={version:I,task:e,createdAt:t??e.startedAt??n,lastPersistedAt:n};$(e.stateFilePath,`${JSON.stringify(i,null,2)}
+`)}r(et,"persistState");function x(e){if(!l(e))return null;try{const t=_(e,"utf-8"),n=JSON.parse(t);return J(n)?n:null}catch{return null}}r(x,"loadState");function rt(e){const t=b(e);if(!l(t))return[];let n;try{n=A(t)}catch{return[]}const i=[];for(const a of n){const f=p(t,a);let u=!1;try{u=h(f).isDirectory()}catch{u=!1}if(!u)continue;const y=E(f),s=x(y);s&&s.task.status==="running"&&i.push(s)}return i.sort((a,f)=>f.lastPersistedAt-a.lastPersistedAt),i}r(rt,"discoverActiveTasks");function nt(e,t=V){const n=b(e);if(!l(n))return 0;let i;try{i=A(n)}catch{return 0}const a=D(n),f=Date.now();let u=0;for(const y of i){const s=p(n,y);if(!D(s).startsWith(a+"/"))continue;let S=!1;try{S=h(s).isDirectory()}catch{S=!1}if(!S)continue;const F=E(s),c=x(F);if(c&&c.task.status==="running")continue;const g=c?c.lastPersistedAt:q(s);if(g!==null&&!(f-g<t))try{k(s,{recursive:!0,force:!0}),u+=1}catch{}}return u}r(nt,"pruneStale");function q(e){try{return h(e).mtimeMs}catch{return null}}r(q,"safeMtimeMs");export{rt as discoverActiveTasks,b as grubRoot,x as loadState,et as persistState,nt as pruneStale,E as stateFilePathFor};

package/dist/extensions/builtin/grub/grub-prompts.d.ts

@@ -0,0 +1,12 @@
+/**
+ * [WHO]: Provides buildGrubInitializerPrompt(), buildGrubCodingPrompt(), buildGrubTaskPrompt()
+ * [FROM]: Depends on ./grub-i18n and ./grub-types for locale-aware task prompts
+ * [TO]: Consumed by ./index.ts and ./grub-controller.ts for /grub prompt injection and dispatch
+ * [HERE]: extensions/builtin/grub/grub-prompts.ts - prompt construction boundary for the Grub harness
+ */
+import { type GrubLocale } from "./grub-i18n.js";
+import type { GrubTaskState } from "./grub-types.js";
+export declare function buildGrubInitializerPrompt(locale: GrubLocale): string;
+export declare function buildGrubCodingPrompt(locale: GrubLocale): string;
+export declare function buildGrubTaskPrompt(task: GrubTaskState): string;
+export declare function getPromptPrefix(taskId: string): string;