@xelth/eck-snapshot 5.9.0 → 6.4.0

package/README.md

@@ -1,190 +1,267 @@
-# eck-snapshot
-
-A CLI tool that packs your entire Git repository into a single text file optimized for LLMs. Give any AI full project context in one copy-paste.
-
-```bash
-npm install -g @xelth/eck-snapshot
-```
-
-## Recommended AI Setup
-
-For best results, we recommend splitting roles between models:
-
-- **Architect** (large context window): Gemini, Grok Fast, ChatGPT — upload the full snapshot, design the architecture, plan tasks
-- **Coder** (execution): Claude (via Claude Code), GLM (via OpenCode) — receive tasks from the architect, write and fix code
-
-eck-snapshot generates tailored instructions (`CLAUDE.md`, `AGENTS.md`) for each role automatically.
-
-## Core Workflow
-
-### 1. Full Snapshot
-
-Run `eck-snapshot` in your project root. It scans every tracked file, filters out noise (lock files, build artifacts, secrets), and produces a single `.md` file ready for an AI chat.
-
-```bash
-eck-snapshot
-# -> .eck/snapshots/eckMyProject_26-02-15_12-00_abc1234.md
-```
-
-Upload the file to your architect AI and start working.
-
-### 2. Incremental Update
-
-After you make changes, don't re-send the entire project. Send only what changed since the last full snapshot:
-
-```bash
-eck-snapshot update
-# -> .eck/snapshots/eckMyProject_26-02-15_14-30_abc1234_up1_42kb.md
-```
-
-This uses a Git anchor (saved automatically during full snapshot) to detect all modified files and includes their full content. No redundant diffs, no wasted tokens.
-
-Notice the `_42kb` suffix in the filename — this is the **Anti-Truncation Guard** (see below).
-
-## Context Profiles
-
-Large repositories waste tokens on irrelevant code. Profiles let you partition the codebase so the AI only sees what matters.
-
-### Auto-Detection
-
-Let AI scan your directory tree and generate profiles automatically:
-
-```bash
-eck-snapshot profile-detect
-# -> Saves profiles to .eck/profiles.json
-```
-
-### Manual Guide
-
-For very large repos where auto-detection is too slow, generate a prompt guide, paste it into a powerful Web LLM (Gemini, ChatGPT), and save the resulting JSON:
-
-```bash
-eck-snapshot generate-profile-guide
-# -> .eck/profile_generation_guide.md (paste into AI, get profiles back)
-```
-
-### Using Profiles
-
-```bash
-eck-snapshot --profile                            # List all available profiles
-eck-snapshot --profile backend                    # Use a named profile
-eck-snapshot --profile backend --skeleton         # Profile + skeleton mode
-eck-snapshot --profile "src/**/*.rs,-**/test_*"   # Ad-hoc glob filtering
-```
-
-Profiles work with both full snapshots and incremental updates.
-
-## Anti-Truncation Guard
-
-Web AI interfaces (Gemini, ChatGPT) sometimes silently drop the content of large uploaded files, replacing them with a small JSON metadata stub like `{"fileName": "...", "contentFetchId": "..."}`. The AI then hallucinates code it never actually received.
-
-eck-snapshot counters this with two mechanisms:
-
-**1. Size-stamped filenames.** Every snapshot — full and incremental — embeds its exact size in kilobytes directly in the filename:
-
-```
-eckMyProject_26-02-15_12-00_abc1234_1250kb.md      ← full snapshot
-eckMyProject_26-02-15_14-30_abc1234_up1_42kb.md    ← incremental update
-```
-
-**2. AI instructions baked into the snapshot.** The snapshot header instructs the AI to cross-check the `kb` value in the filename against the actual payload it received. If there is a mismatch, the AI is required to stop and alert you instead of hallucinating:
-
-> 🚨 **System Error:** The web interface truncated the file `eckMyProject_..._1250kb.md`. I only received the metadata/JSON stub, not the actual 1250 kb of code. Please split the snapshot or paste the text directly.
-
-This protection works on any web interface that embeds the filename (Gemini, ChatGPT, Grok, etc.).
-
-## Smart Filtering
-
-eck-snapshot automatically detects your project type (Rust, Node.js, Android, Python, etc.) and excludes language-specific noise:
-
-- **Rust**: `Cargo.lock`, `target/`
-- **Node.js**: `package-lock.json`, `node_modules/`
-- **Android**: build artifacts, generated code
-- **All projects**: `.git/`, IDE configs, binary files
-
-The built-in `SecretScanner` also redacts API keys, tokens, and credentials before they reach the AI.
-
-## Multi-Agent Architecture
-
-eck-snapshot generates tailored `CLAUDE.md` instructions for different AI agent roles:
-
-```bash
-eck-snapshot --jas    # Junior Architect Sonnet - fast, standard features
-eck-snapshot --jao    # Junior Architect Opus - deep, critical architecture
-eck-snapshot --jag    # Junior Architect Gemini - massive context tasks
-```
-
-### Chinese Delegation (`--zh`)
-
-For GLM Z.AI workers (trained on Chinese data), the `--zh` flag instructs the architect to formulate all worker tasks in Chinese, improving output quality:
-
-```bash
-eck-snapshot --jas --zh    # Claude Code: delegate to GLM workers in Chinese
-eck-snapshot --zh          # OpenCode/GLM: generate AGENTS.md with Chinese protocol
-```
-
-The architect still communicates with you in your language. Only the `instruction` parameter sent to GLM workers switches to Chinese. Code, variable names, and commit messages stay in English.
-
-### MCP Server Integration
-
-Delegate coding tasks to the GLM Z.AI Worker Fleet via MCP:
-
-```bash
-export ZAI_API_KEY="your-key"
-eck-snapshot setup-mcp --both    # Setup for Claude Code + OpenCode
-```
-
-This gives your AI access to specialized workers: `glm_zai_frontend`, `glm_zai_backend`, `glm_zai_qa`, `glm_zai_refactor`, and the `eck_finish_task` commit tool.
-
-## Skeleton Mode & Lazy Loading
-
-For extremely large projects, skeleton mode strips function bodies and keeps only signatures, types, and structure:
-
-```bash
-eck-snapshot --skeleton
-```
-
-When using skeleton mode, the AI can request full content of specific files on demand:
-
-```bash
-eck-snapshot show src/auth.rs src/handlers/sync.rs
-```
-
-Useful for initial orientation in massive codebases, but full snapshots with profiles are usually more practical.
-
-## Other Commands
-
-```bash
-eck-snapshot restore <snapshot>    # Restore files from a snapshot to disk
-eck-snapshot prune <snapshot>      # AI-powered snapshot size reduction
-eck-snapshot doctor                # Check project health
-eck-snapshot env push              # Encrypt and sync .eck/ config between machines
-eck-snapshot env pull              # Restore .eck/ config on another machine
-```
-
-## Changelog
-
-### v5.8.6
-- **Anti-Truncation Guard:** Every snapshot filename now includes its size in KB (e.g., `_1250kb.md`). The snapshot header instructs the AI to verify the payload size matches the filename and alert the user if the web UI truncated the file instead of hallucinating missing code.
-- **Incremental snapshot filtering parity:** `eck-snapshot update` now applies the same file guards as full snapshots — hidden paths (`.idea/`, `.vscode/`), binary files, and glob patterns in `filesToIgnore` are all properly filtered out, preventing IDE config files or committed binaries from bloating update snapshots.
-
-### v5.8.5
-- Re-publish to fix missing README on npmjs.com.
-
-### v5.8.4
-- Fixed directory filtering in incremental snapshots. Paths like `web/build/app.js` are now correctly ignored when `build/` is in the ignore list.
-
-### v5.8.3
-- Optimized agent report formatting with clean Markdown to improve token efficiency.
-- Fixed report injection order so it appears correctly after system instructions.
-
-### v5.8.2
-- Fixed agent report injection in incremental snapshots. The `AnswerToSA.md` file is now preserved on disk for manual debugging and uses an internal `[SYSTEM: EMBEDDED]` marker to prevent duplicate injections into future snapshots.
-
-### v5.8.1
-- Improved Android project parsing by ignoring boilerplate and vector graphics.
-- Removed duplicate `ecksnapshot` MCP server and fixed JSON parsing in `update-auto`.
-
-## License
-
-MIT
+# 📸 eckSnapshot v6.3.2 (AI-Native Edition)
+
+A specialized, AI-native CLI tool that creates single-file text snapshots of entire Git repositories and feeds them directly into LLM context windows. Instead of letting AI agents guess which files to read, eckSnapshot force-feeds the complete project into the model's context — giving it a "university degree" in your codebase from the very first prompt.
+
+It also serves as the coordination hub for multi-agent AI coding workflows: generating role-specific instructions (`CLAUDE.md`, `AGENTS.md`), maintaining project manifests (`.eck/` directory), and providing MCP integration for automatic context sync after every code change.
+
+> **Want to see it in action?** This project snapshots itself.
+> [**Download ecksnapshot-context.md**](https://github.com/xelth-com/eckSnapshot/releases/download/v6.2.3/ecksnapshot-context.md) (364 KB), drop it into [Gemini](https://gemini.google.com/), ChatGPT, or any LLM with a large context window — and ask anything in your language — the AI will answer you natively while keeping code-level discussions in English. It becomes a Senior Architect who built this tool.
+
+---
+
+## 📦 Installation
+
+```bash
+npm install -g @xelth/eck-snapshot
+```
+
+---
+
+## 🎯 The Battle-Tested Workflow
+
+### 1. Initial Context (Full Snapshot)
+Take a full snapshot and feed it to a powerful **Web LLM** — the **Senior Architect**.
+
+```bash
+eck-snapshot
+```
+
+The generated `.md` file goes into the chat of your chosen Architect model. The Architect analyzes the full codebase and produces a detailed technical plan.
+
+*(For massive monorepos, slice the context using profiles: `eck-snapshot '{"name": "eck_snapshot", "arguments": {"profile": "frontend"}}'`)*
+
+### 2. Direct Execution
+Pass the Architect's technical plan to your local **Coder agent** (Claude Code / OpenCode / Codex). The Coder implements the changes directly in your repository.
+
+### 3. Auto-Updates
+When the Coder agent finishes a task, it automatically calls the built-in MCP tool (`eck_finish_task`), which commits the code and generates an incremental delta update snapshot. Feed that update back to the Architect to keep it in sync.
+
+---
+
+## 🧠 Which Models to Use
+
+### Senior Architect (Web LLM — reads the snapshot)
+
+The Architect needs a **massive context window** and strong reasoning to digest the full codebase snapshot:
+
+| Model | Context Window | Notes |
+|-------|---------------|-------|
+| **Grok 4 Fast** | **2M tokens** | Largest context available. Can swallow even the biggest monorepos whole. |
+| **Gemini 3.1 Pro** | 1M tokens | Excellent for large projects. Handles huge snapshots effortlessly. *(Author's choice)* |
+| **ChatGPT (GPT-5.4 via web)** | 1M tokens | Works, but can be stubborn with instructions. You **MUST** paste the specific prompt provided at the end of the snapshot output as your first message — otherwise ChatGPT will act as a generic code reviewer instead of assuming the Architect role. |
+
+### Coder Agent (Local — executes the plan)
+
+The Coder needs **tool access** (file editing, terminal, MCP) and works locally in your repository:
+
+| Tool | Engine | Best For |
+|------|--------|----------|
+| **Claude Code** | Claude Sonnet/Opus 4.6 (1M context) | Primary choice. Deep tool integration, native MCP support, context compaction for long sessions. |
+| **OpenCode** | GLM-4.7 / any model | Cost-effective alternative. AGENTS.md support, GLM Z.AI worker swarm via MCP. |
+| **Codex CLI** | GPT models | OpenAI's coding agent. Auto-configured via `.codex/config.toml`. |
+
+### MCP Setup (One-Time)
+Register the MCP servers so your Coder agent can auto-commit and sync context:
+```bash
+eck-snapshot setup-mcp
+```
+
+---
+
+## 🤖 The AI-Native JSON Interface (New in v6.1)
+
+`eck-snapshot` is a **100% pure JSON/MCP bridge**. AI agents interact with the CLI by passing a single JSON payload:
+
+```bash
+eck-snapshot '{"name": "eck_snapshot", "arguments": {"profile": "backend", "jas": true}}'
+eck-snapshot '{"name": "eck_update"}'
+```
+
+### 🧑‍💻 Human Shorthands (Ranked by Usage)
+For humans typing in the terminal, short commands work too:
+
+| # | Command | Description |
+|---|---------|-------------|
+| 1 | `eck-snapshot snapshot` | Full project snapshot |
+| 2 | `eck-snapshot update` | Delta update (changed files only) |
+| 3 | `eck-snapshot profile [name]` | Snapshot filtered by profile (no arg = list profiles) |
+| 4 | `eck-snapshot scout [0-9]` | Scout external repo (see depth scale below) |
+| 5 | `eck-snapshot fetch "src/**/*.rs"` | Fetch specific files by glob |
+| 6 | `eck-snapshot link [0-9]` | Linked companion snapshot |
+| 7 | `eck-snapshot booklm` | Export for NotebookLM — Scout mode (see below) |
+| 8 | `eck-snapshot notelm` | Export for NotebookLM — Architect mode (see below) |
+| 9 | `eck-snapshot setup-mcp` | Configure MCP servers |
+| 10 | `eck-snapshot detect` | Detect project type and active filters |
+| 11 | `eck-snapshot doctor` | Check project health and stubs |
+
+Running `eck-snapshot` with no arguments defaults to a full snapshot.
+
+### ✉️ Feedback & Telemetry
+```bash
+eck-snapshot -e "Great tool, but scout could be faster"   # Normal feedback
+eck-snapshot -E "Crash on Windows when path has spaces"   # Urgent bug report
+eck-snapshot telemetry disable                             # Opt out completely
+eck-snapshot telemetry enable                              # Opt back in
+eck-snapshot telemetry                                     # Check current status
+```
+
+Feedback is saved locally to `.eck/telemetry_queue.json` and will be sent to developers during the next telemetry sync.
+
+#### 🔒 Datenschutz / Privacy
+By default, eck-snapshot collects **anonymous usage counts** and **crash logs** to improve the tool. **NO source code or sensitive data is ever sent.** Each CLI instance is identified by a random UUID stored in `~/.eck/cli-config.json`. You can completely disable telemetry at any time with `eck-snapshot telemetry disable`.
+
+---
+
+## 🔗 Cross-Context: Scouts & Links (Working with External Projects)
+
+When your AI is working on **Project A** but needs awareness of **Project B** (a shared backend, a component library, a microservice), feeding it a standard snapshot of Project B will cause "context pollution" — the AI forgets which project it's supposed to edit.
+
+eckSnapshot solves this with two complementary tools that share a **unified depth scale (0-9)** for controlling how much content is included:
+
+### `scout` — Quick Exploration (read-only)
+Run inside the external repository:
+```bash
+cd ../project-b
+eck-snapshot scout        # depth 0: tree only (fast overview)
+eck-snapshot scout 3      # depth 3: tree + 60 lines per file
+eck-snapshot scout 5      # depth 5: tree + function signatures
+```
+*Result:* Generates `.eck/scouts/scout_tree_...md` — a directory tree (and optionally file contents) with strict instructions telling the AI **NOT** to edit this code. Feed it to your AI, and it can request specific files via `eck-snapshot fetch "src/**/*.js"`.
+
+### `link` — Deep Cross-Context Snapshot (companion file)
+Run inside the companion project:
+```bash
+cd ../project-b
+eck-snapshot link 5       # skeleton: function signatures
+eck-snapshot link 9       # full: complete file contents
+```
+*Result:* Generates a standalone `link_*.md` file saved to `.eck/links/` with a read-only cross-context header. Upload it alongside your main project snapshot. The AI will automatically receive instructions to **not edit** the linked project and will be given `eck_fetch` commands to drill deeper if needed.
+
+### `fetch` — Targeted File Extraction (by glob pattern)
+```bash
+eck-snapshot fetch "src/core/parser.js" "docs/**/*.md"
+```
+*Result:* Generates `.eck/scouts/scout_data_...md` containing only the requested file contents, perfectly formatted for reading without losing the primary role.
+
+### Shared Depth Scale (0-9)
+Both `scout` and `link` use the same depth scale to control content granularity:
+
+| Depth | Mode | Use Case |
+|-------|------|----------|
+| **0** | Tree only | "Just show me the folder structure" |
+| **1** | Truncated (10 lines) | Imports and file headers only |
+| **2** | Truncated (30 lines) | Quick surface scan |
+| **3** | Truncated (60 lines) | API surface overview |
+| **4** | Truncated (100 lines) | Detailed surface scan |
+| **5** | Skeleton | Function/class signatures only (no docs) |
+| **6** | Skeleton + docs | Signatures with JSDoc/docstrings preserved |
+| **7** | Full (compact) | Full content, truncated at 500 lines per file |
+| **8** | Full (standard) | Full content, truncated at 1000 lines per file |
+| **9** | Full (unlimited) | Everything, no limits |
+
+---
+
+## 🌟 Core Features
+
+* **🔄 Smart Delta Updates:** Tracks incremental changes via Git anchors. Accurately tracks and reports deleted files to prevent LLM hallucinations.
+* **🛡️ Security (SecretScanner):** Automatically redacts API keys and credentials before sending context to LLMs. Features both Regex matching and **Shannon Entropy** analysis.
+* **🔌 Native MCP Integration:** Instantly spins up Model Context Protocol (MCP) servers (`eck-core` and `glm-zai`) for Claude Code, OpenCode, and Codex.
+* **📁 The `.eck/` Manifest:** Automatically maintains project context files (`CONTEXT.md`, `ROADMAP.md`, `TECH_DEBT.md`). Dynamic scanning — any `.md` file you add to `.eck/` is automatically included in snapshots.
+* **☠️ Skeleton Mode:** Uses Tree-sitter and Babel to strip function bodies, drastically reducing token count for huge codebases.
+* **📚 NotebookLM Export:** Semantic chunking for Google's NotebookLM with "Brain + Body" architecture (see below).
+* **🧠 Multi-Agent Protocol:** Junior Architect delegation system for multi-agent coding workflows (see below).
+
+---
+
+## 📚 NotebookLM Integration (New in v6.3 — Testing)
+
+> **Status:** Active testing. The core chunking works, prompt tuning is ongoing.
+
+### The Problem
+Your project is 2M+ tokens. Your Architect (Gemini/Grok) has a limited context window and costs money per query. You can't afford to feed the full codebase on every question.
+
+### The Solution: Free RAG via NotebookLM
+Google's NotebookLM supports up to **50 sources** and uses **RAG** (Retrieval-Augmented Generation) to search across them for free. eckSnapshot splits your codebase into semantically packed chunks that NotebookLM can index and search.
+
+### Architecture: Brain + Body
+
+```
+Part 0 (Brain)    — Instructions, .eck/ manifests, full directory tree. No code.
+Part 1 (Body)     — Source code chunk (~2.5MB), grouped by directory.
+Part 2 (Body)     — Source code chunk (~2.5MB), grouped by directory.
+...
+Part N (Body)     — Source code chunk (~2.5MB), grouped by directory.
+```
+
+Files are packed using a **directory-aware bin packing** algorithm: files from the same folder stay together for better RAG retrieval. The directory tree lives only in Part 0 to avoid duplication across chunks.
+
+### Two Modes
+
+**`booklm` — The Scout (Primary Use Case)**
+```bash
+eck-snapshot booklm
+```
+NotebookLM becomes a free "code librarian" for your paid Architect. Ask it: *"I'm working on fiscalization, which files do I need?"* — it analyzes the entire codebase via RAG and returns precise `eck-snapshot fetch` commands:
+```bash
+cd /path/to/project
+eck-snapshot fetch "**/FiscalPrinter.kt" "**/TaxCalculator.kt" "**/receipt_config.json"
+```
+You run the fetch command locally, get a tiny focused snapshot, and hand *that* to your real Architect. This saves money and context window.
+
+**`notelm` — The Architect (Experimental)**
+```bash
+eck-snapshot notelm
+```
+Same chunking, but Part 0 instructs NotebookLM to act as the Senior Architect itself — analyzing architecture, proposing refactoring, designing features. This is experimental and results vary.
+
+### Quick Start
+1. Run `eck-snapshot booklm` (or `notelm`) inside your project
+2. Upload all generated `part*.md` files as sources in a new NotebookLM project
+3. Paste the **Starter Prompt** (printed in your terminal) as your first message
+4. Start asking questions
+
+---
+
+## 🧠 Multi-Agent Protocol: Junior Architects (Testing)
+
+> **Status:** Active testing. The delegation protocol works, prompt optimization is ongoing.
+
+### The Concept
+For large projects, a single AI can't hold the full context AND write code efficiently. eckSnapshot implements a **Royal Court** hierarchy:
+
+```
+Senior Architect (Gemini/Grok — Web LLM, huge context)
+    │
+    ├── Junior Architect Sonnet (jas) — Claude Code with Sonnet 4.6
+    ├── Junior Architect Opus  (jao) — Claude Code with Opus 4.6
+    ├── Junior Architect GLM   (jaz) — OpenCode with GLM-4.7
+    │       │
+    │       └── GLM Z.AI Workers (MCP) — cheap bulk coding
+    │
+    └── Coder (default) — standard developer mode
+```
+
+The Senior Architect reads the full snapshot, plans the work, and delegates tasks via the Eck-Protocol v2. Junior Architects receive filtered snapshots with role-specific `CLAUDE.md` / `AGENTS.md` instructions and execute the plan locally.
+
+### Usage
+```bash
+eck-snapshot '{"name": "eck_snapshot", "arguments": {"jas": true}}'   # Sonnet mode
+eck-snapshot '{"name": "eck_snapshot", "arguments": {"jao": true}}'   # Opus mode
+eck-snapshot '{"name": "eck_snapshot", "arguments": {"jaz": true}}'   # GLM/OpenCode mode
+```
+
+Each mode generates a snapshot with tailored AI headers and updates the corresponding agent config file (`CLAUDE.md` for jas/jao, `AGENTS.md` for jaz).
+
+---
+
+## 💡 The Philosophy: Why force a full snapshot?
+
+LLMs work like humans who have memorized a textbook. Giving an AI a "file search" tool is like putting a beginner next to a bookshelf — they have to guess what to look for. Forcing a complete project snapshot into the LLM's massive context window is like giving it a university degree in your specific codebase. That is what `eck-snapshot` does.
+
+## Ethical Automation Policy
+
+This project respects the Terms of Service of AI providers. We do not implement browser automation to bypass or spoof web chat interfaces intended for human use. All AI integrations use official APIs.
+
+## License
+MIT © xelth-com
+<div align="right"><sup>made in Eschborn</sup></div>

package/package.json

@@ -1,7 +1,20 @@
 {
   "name": "@xelth/eck-snapshot",
-  "version": "5.9.0",
-  "description": "A powerful CLI tool to create and restore single-file text snapshots of Git repositories and directories. Optimized for AI context and LLM workflows.",
+  "version": "6.4.0",
+  "description": "A powerful CLI tool to create and restore single-file text snapshots of Git repositories. Optimized for AI context, LLM workflows, and multi-agent Swarm coordination.",
+  "keywords": [
+    "ai",
+    "llm",
+    "mcp",
+    "snapshot",
+    "context",
+    "claude",
+    "gemini",
+    "grok",
+    "chatgpt",
+    "agent",
+    "prompt"
+  ],
   "main": "index.js",
   "type": "module",
   "bin": {

package/scripts/mcp-eck-core.js

@@ -23,9 +23,23 @@ const server = new Server(
 server.setRequestHandler(ListToolsRequestSchema, async () => {
   return {
     tools: [
+      {
+        name: "eck_fail_task",
+        description: "Use this if you are stuck, blocked, or unable to complete the task. It saves your report to AnswerToSA.md and generates an emergency snapshot WITHOUT committing broken code. Do NOT use this if tests pass.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            status: {
+              type: "string",
+              description: "Detailed explanation of why you are blocked, what you tried, and what the Architect should know."
+            }
+          },
+          required: ["status"]
+        }
+      },
       {
         name: "eck_finish_task",
-        description: "Completes the current coding task. 1) Overwrites AnswerToSA.md with status for the Architect. 2) Stages all changes. 3) Commits with the provided message. 4) Automatically updates the context snapshot. Use this instead of manual git commands.",
+        description: "Completes the current coding task. 1) Overwrites AnswerToSA.md with status for the Architect. 2) Stages all changes. 3) Commits with the provided message. 4) Automatically updates the context snapshot. WARNING: USE ONLY ONCE PER TASK WHEN 100% FINISHED. Do NOT use this for intermediate saves or testing during your debugging loop.",
         inputSchema: {
           type: "object",
           properties: {
@@ -46,6 +60,40 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
 });
 
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  if (request.params.name === "eck_fail_task") {
+    const { status } = request.params.arguments;
+    const workDir = process.cwd();
+
+    try {
+      const answerDir = path.join(workDir, '.eck', 'lastsnapshot');
+      await fs.mkdir(answerDir, { recursive: true });
+      await fs.writeFile(
+        path.join(answerDir, 'AnswerToSA.md'),
+        `# Agent Report (BLOCKED/FAILED)\n\n${status}\n`,
+        'utf-8'
+      );
+
+      const cliPath = path.join(PROJECT_ROOT, "index.js");
+      const { stdout } = await execa("node", [cliPath, JSON.stringify({ name: "eck_update_auto", arguments: { fail: true } })], { cwd: workDir, timeout: 120000 });
+
+      let result;
+      try {
+        result = JSON.parse(stdout);
+      } catch (e) {
+        return { content: [{ type: "text", text: `⚠️ Task aborted, but snapshot update returned invalid JSON: ${stdout}` }] };
+      }
+
+      return {
+        content: [{
+          type: "text",
+          text: `🚨 Task marked as FAILED.\n📝 AnswerToSA.md updated\n📸 Emergency Snapshot: ${result.snapshot_file} (${result.files_count} files)`
+        }]
+      };
+    } catch (error) {
+      return { content: [{ type: "text", text: `❌ Error: ${error.message}\n${error.stderr || ''}` }], isError: true };
+    }
+  }
+
   if (request.params.name === "eck_finish_task") {
     const { status, message } = request.params.arguments;
     const workDir = process.cwd();
@@ -68,7 +116,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
       // 4. Auto Update Snapshot
       const cliPath = path.join(PROJECT_ROOT, "index.js");
-      const { stdout } = await execa("node", [cliPath, "update-auto"], { cwd: workDir, timeout: 120000 });
+      const { stdout } = await execa("node", [cliPath, JSON.stringify({ name: "eck_update_auto" })], { cwd: workDir, timeout: 120000 });
 
       let result;
       try {
@@ -106,14 +154,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   };
 });
 
-const transport = new StdioServerTransport();
-await server.connect(transport);
-
-// --- Graceful Shutdown Handler ---
-process.stdout.on('error', (err) => {
-  if (err.code === 'EPIPE') {
-    process.exit(0);
-  }
-});
-process.on('SIGINT', () => process.exit(0));
-process.on('SIGTERM', () => process.exit(0));
+const transport = new StdioServerTransport();
+await server.connect(transport);
+
+// --- Graceful Shutdown Handler ---
+process.stdout.on('error', (err) => {
+  if (err.code === 'EPIPE') {
+    process.exit(0);
+  }
+});
+process.on('SIGINT', () => process.exit(0));
+process.on('SIGTERM', () => process.exit(0));