Update server.js

server.js

@@ -51,9 +51,10 @@ app.use(express.static(path.join(__dirname, "public")));
 
 // ── SINGLE MODEL: LongCat API (Anthropic format) ────────────────────────────
 const LONGCAT_API_URL = "https://api.longcat.chat/anthropic/v1/messages";
-const LONGCAT_API_KEY = "ak_2ep6ba2Ww0pn5cH09U2Mq3Eo0ez1M";
+const LONGCAT_API_KEY         = "ak_2ep6ba2Ww0pn5cH09U2Mq3Eo0ez1M";
+const LONGCAT_API_KEY_BACKUP  = "ak_2k06yh7h44iH7g77T46kB3uJ6b89l";
 
-// All model keys from the UI now map to DeepSeek — one API, no confusion
+// All model keys from the UI map to LongCat-Flash-Lite — one API, no confusion
 const MODELS = {
   "cryo1": { name: "Cryo 1", label: "cryo1", description: "Fast & light" },
   "cryo2": { name: "Cryo 2", label: "cryo2", description: "Reliable & smart" },
@@ -78,9 +79,8 @@ const COMMANDS_REFERENCE = `
 === SHELL COMMANDS (cwd = /home) — ALL commands permitted except: sudo su reboot shutdown mkfs fdisk ===
 
 EXPLORE:   wc -l file | ls -la | find . -name "*.js" | stat filename | which node | env
-READ:      sed -n 'X,Yp' file  ← READ A SECTION by line range (most important)
-           grep -n "pattern" file  ← FIND with line numbers (always do this first)
-           grep -C3 "pattern" file  ← FIND with 3 lines of context
+READ:      sed -n 'X,Yp' file  ← read a section by line range
+           grep -n "pattern" file  ← find with line numbers
            head -n N file | tail -n N file | cat file
 EDIT:      sed -i 's/old/new/g' file  ← replace all occurrences
            sed -i 'Ns/old/new/' file  ← replace on line N only
@@ -92,24 +92,111 @@ RUN:       node file.js | node --check file.js | npm install pkg | python3 file.
 NETWORK:   curl -s URL | wget -q -O out URL
 UTILS:     jq . file.json | wc -l file | diff a b
 
-=== MANDATORY WORKFLOW (follow exactly) ===
-STEP 1 — LOCATE:   wc -l file  →  grep -n "keyword" file   (find the exact line number)
-STEP 2 — READ:     sed -n 'START,ENDp' file                 (read the section around that line)
-STEP 3 — BACKUP:   cp file file.bak                         (before any edit)
-STEP 4 — EDIT:     sed -i 'Ns/exact-old/new/' file          (use line number from step 1)
-STEP 5 — VERIFY:   sed -n 'START,ENDp' file                 (confirm the change is there)
-STEP 6 — CHECK:    node --check file.js                     (after every JS write)
+=== SMART FILE READING — USE THIS BEFORE EDITING (same strategy Claude uses) ===
+Instead of raw commands, you can request structured file reads via "read_file" in your JSON.
+The system reads the file server-side and returns results in your next round's context.
+
+ACTIONS:
+  { "action": "map" }
+    → Returns: file structure overview — total lines, all section headers, all function/route
+      signatures with line numbers, imports list, first 30 lines, last 15 lines.
+      USE THIS FIRST on any file you haven't fully seen yet.
+
+  { "action": "chunk", "start": N, "end": M }
+    → Returns: lines N–M with line numbers (like sed -n 'N,Mp').
+      USE THIS to read any section before editing it.
+
+  { "action": "search", "pattern": "someSymbol" }
+    → Returns: all lines matching the pattern with line numbers (like grep -n).
+      USE THIS to locate all uses of a symbol before changing it.
+
+HOW TO USE: Add a "read_file" array to your JSON response (alongside or instead of "commands"):
+{
+  "read_file": [
+    { "action": "map" },
+    { "action": "search", "pattern": "bot.on" },
+    { "action": "chunk", "start": 45, "end": 90 }
+  ],
+  "commands": [],
+  "done": false,
+  "status": "Reading file structure before editing"
+}
+The results will appear in your NEXT round's context under FILE READ RESULTS.
+You can combine read_file and commands in the same response.
+
+=== WHEN TO USE FULL-FILE REWRITE vs SURGICAL EDITS ===
+SURGICAL EDITS (sed): use when changing ≤ 30% of the file — targeted, safe, precise.
+FULL REWRITE: use when switching libraries/frameworks, restructuring >30%, or file is broken.
+  Set "full_rewrite": true and provide "new_content": "<complete file>".
+  System will stage → validate → write atomically. DO NOT use tee for this.
+
+=== MANDATORY WORKFLOW ===
+STEP 1 — READ MAP:   { "read_file": [{ "action": "map" }] }  ← understand structure first
+STEP 2 — SEARCH:     { "read_file": [{ "action": "search", "pattern": "target" }] }
+STEP 3 — CHUNK:      { "read_file": [{ "action": "chunk", "start": N, "end": M }] }
+STEP 4 — BACKUP:     cp file file.bak
+STEP 5 — EDIT:       sed -i 'Ns/exact-old/new/' file  (use line numbers from step 2)
+STEP 6 — VERIFY:     { "read_file": [{ "action": "chunk", "start": N, "end": M }] }
+STEP 7 — CHECK:      node --check file.js
 
 === STRICT RULES ===
-1. ALWAYS grep -n first — NEVER edit blind without knowing the line number
-2. ALWAYS sed -n to read a section BEFORE editing it — verify the exact text
-3. ALWAYS cp file.bak before rewrites — never destroy without a backup
-4. ALWAYS node --check after every JS write — catch syntax errors immediately
+1. ALWAYS map or search before editing — NEVER edit blind
+2. ALWAYS chunk-read a section BEFORE editing — verify the exact text
+3. ALWAYS cp file.bak before any rewrite
+4. ALWAYS node --check after every JS change
 5. NEVER echo -e for multiline — always tee with heredoc
-6. Mark done:true ONLY after sed -n confirms the change is physically in the file
-7. If a sed -i edit produced no output change, the pattern was wrong — grep again
+6. Mark done:true ONLY after a chunk read CONFIRMS the change is in the file
+7. If sed produced linesChanged:no-match → search again, pattern was wrong
+8. NEVER repeat a command already in COMMAND HISTORY with the same args
+9. If sed failed twice on same pattern → use full_rewrite
 `;
 
+// ── COMMAND DEDUP & SAFETY FILTER ─────────────────────────────────────────
+// Strips commands already run this session (exact match) and known-dangerous patterns.
+// Returns { safe: [...], skipped: [...] }
+const DESTRUCTIVE_PATTERNS = [
+  /^rm\s+-rf?\s+\//, // rm -rf /
+  /^>\s*\//, // redirect to root path
+  /:(){ :|:& };:/, // fork bomb
+];
+function filterCommands(commands, alreadyRun = []) {
+  const safe = [];
+  const skipped = [];
+  const runSet = new Set(alreadyRun.map(c => c.trim()));
+  for (const cmd of commands) {
+    const trimmed = cmd.trim();
+    if (!trimmed) continue;
+    if (runSet.has(trimmed)) { skipped.push({ cmd: trimmed, reason: "duplicate" }); continue; }
+    if (!isSafeCmd(trimmed)) { skipped.push({ cmd: trimmed, reason: "blocked" }); continue; }
+    if (DESTRUCTIVE_PATTERNS.some(p => p.test(trimmed))) { skipped.push({ cmd: trimmed, reason: "destructive" }); continue; }
+    safe.push(trimmed);
+  }
+  return { safe, skipped };
+}
+
+// ── STRUCTURED COMMAND RESULT ──────────────────────────────────────────────
+// Wraps raw stdout/stderr into a structured object the AI can reason about
+function structureResult(cmd, stdout, stderr, code) {
+  const lines = stdout.split("\n").filter(Boolean);
+  const isEdit = /^sed\s+-i/.test(cmd);
+  const isGrep = /^grep/.test(cmd);
+  const isRead = /^sed\s+-n/.test(cmd) || /^(head|tail|cat)\b/.test(cmd);
+  const isCheck = cmd.includes("node --check") || cmd.includes("python3 -m py_compile");
+  return {
+    cmd,
+    exit: code,
+    ok: code === 0,
+    stdout: stdout.substring(0, 1200),
+    stderr: stderr.substring(0, 400),
+    // Structured fields for common operations
+    ...(isGrep && { matches: lines.slice(0, 30) }),
+    ...(isEdit && { linesChanged: code === 0 ? "applied" : "no-match" }),
+    ...(isRead && { content: stdout.substring(0, 2000) }),
+    ...(isCheck && { syntaxOk: code === 0, syntaxError: stderr || null }),
+    warning: code !== 0 ? (stderr || "non-zero exit") : null,
+  };
+}
+
 // ── Multer ─────────────────────────────────────────────────────────────────
 const storage = multer.diskStorage({
   destination: HOME_DIR,
@@ -187,7 +274,8 @@ function runCmd(command) {
       return resolve({ stdout: "", stderr: `Blocked: ${command.trim().split(/\s+/)[0]}`, code: 1 });
     }
     exec(command, { cwd: HOME_DIR, timeout: 30000, shell: "/bin/bash" }, (err, stdout, stderr) => {
-      resolve({ stdout: stdout || "", stderr: stderr || "", code: err ? (err.code || 1) : 0 });
+      const code = err ? (err.code || 1) : 0;
+      resolve({ stdout: stdout || "", stderr: stderr || "", code });
     });
   });
 }
@@ -213,6 +301,120 @@ function getSmartContext(content, query, maxLines = 120) {
   return head + middle + tail;
 }
 
+// ── FILE INSPECTION — Claude-style chunked reading ─────────────────────────
+// Mirrors exactly how Claude reads files: overview first, then targeted chunks.
+// The AI requests inspections; the system resolves them and feeds results back.
+
+// 1. Build a file map: line count, imports, exports, top-level symbols, section headers.
+//    This is the "wc -l + grep structure" step Claude does first.
+function buildFileMap(filePath) {
+  const abs = path.join(HOME_DIR, filePath);
+  if (!fs.existsSync(abs)) return null;
+  const content = fs.readFileSync(abs, "utf8");
+  const lines = content.split("\n");
+  const ext = path.extname(filePath).toLowerCase();
+
+  // Find structural landmarks by line number
+  const landmarks = [];
+  const importLines = [], exportLines = [], fnLines = [], classLines = [], commentSections = [];
+
+  lines.forEach((line, i) => {
+    const n = i + 1;
+    const t = line.trim();
+    if (/^(import|require|from)\b/.test(t) || /\brequire\s*\(/.test(t)) importLines.push(n);
+    if (/^(export|module\.exports)/.test(t)) exportLines.push(n);
+    if (/^(async\s+)?function\s+\w+|const\s+\w+\s*=\s*(async\s+)?\(/.test(t) ||
+        /^(app|router)\.(get|post|put|delete|patch|use)\s*\(/.test(t)) fnLines.push({ n, preview: t.slice(0, 80) });
+    if (/^class\s+\w+/.test(t)) classLines.push({ n, preview: t.slice(0, 60) });
+    if (/^\/\/\s*[─━=]{3,}/.test(t) || /^#{1,3}\s/.test(t)) commentSections.push({ n, text: t.slice(0, 60) });
+  });
+
+  return {
+    file: filePath,
+    totalLines: lines.length,
+    ext,
+    imports: importLines.slice(0, 5),           // first 5 import lines
+    exports: exportLines.slice(0, 5),
+    functions: fnLines.slice(0, 30),             // up to 30 function signatures
+    classes: classLines.slice(0, 10),
+    sections: commentSections.slice(0, 20),      // section comment headers
+    head: lines.slice(0, 30).map((l, i) => `${i+1}\t${l}`).join("\n"),
+    tail: lines.slice(-15).map((l, i) => `${lines.length-15+i+1}\t${l}`).join("\n"),
+  };
+}
+
+// 2. Read a specific chunk of a file by line range — like sed -n 'X,Yp'
+//    Returns line-numbered content so the AI can use exact line numbers in sed.
+function readFileChunk(filePath, startLine, endLine) {
+  const abs = path.join(HOME_DIR, filePath);
+  if (!fs.existsSync(abs)) return null;
+  const lines = fs.readFileSync(abs, "utf8").split("\n");
+  const s = Math.max(1, startLine) - 1;
+  const e = Math.min(lines.length, endLine);
+  return {
+    file: filePath,
+    startLine: s + 1,
+    endLine: e,
+    totalLines: lines.length,
+    content: lines.slice(s, e).map((l, i) => `${s + i + 1}\t${l}`).join("\n"),
+  };
+}
+
+// 3. Search file for a pattern — like grep -n, returns structured matches
+function searchFile(filePath, pattern) {
+  const abs = path.join(HOME_DIR, filePath);
+  if (!fs.existsSync(abs)) return null;
+  const lines = fs.readFileSync(abs, "utf8").split("\n");
+  let re;
+  try { re = new RegExp(pattern, "i"); } catch { re = new RegExp(pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "i"); }
+  const matches = [];
+  lines.forEach((line, i) => {
+    if (re.test(line)) matches.push({ line: i + 1, text: line.trimEnd().slice(0, 120) });
+  });
+  return { file: filePath, pattern, totalLines: lines.length, matches: matches.slice(0, 40) };
+}
+
+// 4. Process an array of read_file actions the AI requested:
+//    [{ action: "map" }, { action: "chunk", start, end }, { action: "search", pattern }]
+function processReadActions(filePath, actions = []) {
+  const results = [];
+  for (const a of actions) {
+    if (a.action === "map") {
+      results.push({ action: "map", result: buildFileMap(filePath) });
+    } else if (a.action === "chunk" && a.start && a.end) {
+      results.push({ action: "chunk", start: a.start, end: a.end, result: readFileChunk(filePath, a.start, a.end) });
+    } else if (a.action === "search" && a.pattern) {
+      results.push({ action: "search", pattern: a.pattern, result: searchFile(filePath, a.pattern) });
+    }
+  }
+  return results;
+}
+
+// 5. Format read results into a concise string the AI can parse in its next prompt
+function formatReadResults(readResults) {
+  return readResults.map(r => {
+    if (r.action === "map" && r.result) {
+      const m = r.result;
+      const fns = m.functions.map(f => `  L${f.n}: ${f.preview}`).join("\n");
+      const secs = m.sections.map(s => `  L${s.n}: ${s.text}`).join("\n");
+      return `=== FILE MAP: ${m.file} (${m.totalLines} lines) ===
+IMPORTS at lines: ${m.imports.join(", ") || "none"}
+SECTIONS:\n${secs || "  (none)"}
+FUNCTIONS/ROUTES:\n${fns || "  (none)"}
+HEAD (lines 1-30):\n${m.head}
+TAIL (last 15):\n${m.tail}`;
+    }
+    if (r.action === "chunk" && r.result) {
+      return `=== CHUNK ${r.result.file} lines ${r.result.startLine}-${r.result.endLine} (of ${r.result.totalLines}) ===\n${r.result.content}`;
+    }
+    if (r.action === "search" && r.result) {
+      const hits = r.result.matches.map(m => `  L${m.line}: ${m.text}`).join("\n");
+      return `=== SEARCH "${r.result.pattern}" in ${r.result.file} — ${r.result.matches.length} hits ===\n${hits || "  (no matches)"}`;
+    }
+    return "";
+  }).filter(Boolean).join("\n\n");
+}
+
 // ── VERSIONING ─────────────────────────────────────────────────────────────
 function readVersions() {
   if (!fs.existsSync(VERSIONS_FILE)) return {};
@@ -296,8 +498,11 @@ async function webSearch(query) {
 // ── callAI — LongCat API (Anthropic format) ────────────────────────────────
 // system   = role/task definition + original user request for context anchoring
 // query    = specific data for this call (file snippet, cmd results, etc.)
-// _modelKey accepted but ignored — all calls route to LongCat-Flash-Chat
+// _modelKey accepted but ignored — all calls route to LongCat-Flash-Lite
 // history  = [{role:"user"|"assistant", content:"..."}] — conversation transcript
+//
+// On HTTP 429 / rate_limit_exceeded the call is transparently retried once
+// using the backup API key — the caller never sees the error.
 async function callAI(system, query, _modelKey, history = []) {
   const userMessage = query ? `${system}\n\n${query}` : system;
 
@@ -305,36 +510,50 @@ async function callAI(system, query, _modelKey, history = []) {
   const safeHistory = (Array.isArray(history) ? history : [])
     .filter(h => h && (h.role === "user" || h.role === "assistant") && h.content)
     .slice(-20) // last 10 user+assistant pairs
-    .map(h => ({ role: h.role, content: String(h.content).slice(0, 800) })); // cap each turn
+    .map(h => ({ role: h.role, content: String(h.content).slice(0, 800) }));
 
-  // Build messages array: inject history then the new user message
   const messages = [
     ...safeHistory,
     { role: "user", content: userMessage.slice(0, 5500) },
   ];
 
   const payload = {
-    model: "LongCat-Flash-Chat",
+    model: "LongCat-Flash-Lite",
     max_tokens: 2000,
     system: "You are Cryo, a precise developer AI. Respond with valid JSON only — no markdown fences, no prose. The original user request is embedded in the message; never lose sight of it.",
     messages,
   };
 
-  const { data } = await axios.post(LONGCAT_API_URL, payload, {
-    timeout: 60000,
-    headers: {
-      "Content-Type": "application/json",
-      "Authorization": `Bearer ${LONGCAT_API_KEY}`,
-      "anthropic-version": "2023-06-01",
-    },
-  });
+  // Inner helper — attempt one call with the given key
+  async function attempt(apiKey) {
+    const { data } = await axios.post(LONGCAT_API_URL, payload, {
+      timeout: 60000,
+      headers: {
+        "Content-Type": "application/json",
+        "Authorization": `Bearer ${apiKey}`,
+        "anthropic-version": "2023-06-01",
+      },
+    });
+    // Anthropic format: data.content is an array of blocks
+    if (data.content && Array.isArray(data.content)) {
+      const textBlock = data.content.find(b => b.type === "text");
+      return textBlock ? textBlock.text : "";
+    }
+    return data.reply || data.text || data.message || "";
+  }
 
-  // Anthropic format: data.content is an array of blocks
-  if (data.content && Array.isArray(data.content)) {
-    const textBlock = data.content.find(b => b.type === "text");
-    return textBlock ? textBlock.text : "";
+  try {
+    return await attempt(LONGCAT_API_KEY);
+  } catch (err) {
+    // Detect quota exhaustion: HTTP 429 with rate_limit_exceeded code
+    const status = err.response?.status;
+    const errCode = err.response?.data?.error?.code;
+    if (status === 429 && errCode === "rate_limit_exceeded") {
+      // Silently retry with backup key — no error propagated to caller
+      return await attempt(LONGCAT_API_KEY_BACKUP);
+    }
+    throw err; // any other error re-thrown normally
   }
-  return data.reply || data.text || data.message || "";
 }
 
 // ── SYNTAX FIX LOOP ────────────────────────────────────────────────────────
@@ -404,22 +623,49 @@ async function runAgentLoop(opts) {
   let cmdIndex = 0;
   let fileContent = initialContent;
   let sessionTasks = [];
+  let pendingReadResults = []; // read_file results waiting to be shown to AI in next round
 
   // ── Helper: run a batch of commands and collect results ───────────────
+  // Deduplicates against already-run commands, structures output, guards retries
+  const cmdRetryCount = {}; // tracks per-cmd-pattern retry attempts
   async function runBatch(commands) {
-    for (const cmd of commands) {
-      if (!cmd || !cmd.trim()) continue;
+    const alreadyRunCmds = allCommandResults.map(r => r.cmd);
+    const { safe, skipped } = filterCommands(commands, alreadyRunCmds);
+
+    // Notify about skipped commands so AI sees them in history
+    for (const s of skipped) {
+      send("status", { text: `Skipped (${s.reason}): ${s.cmd}` });
+    }
+
+    for (const cmd of safe) {
+      // Per-command retry cap: same base command (first 40 chars) max 3 times
+      const cmdKey = cmd.slice(0, 40);
+      cmdRetryCount[cmdKey] = (cmdRetryCount[cmdKey] || 0) + 1;
+      if (cmdRetryCount[cmdKey] > 3) {
+        send("status", { text: `Max retries reached for: ${cmd.slice(0, 60)}` });
+        continue;
+      }
+
       const idx = cmdIndex++;
       send("status", { text: `[${idx + 1}] ${cmd}` });
       send("command", { cmd, index: idx });
       const result = await runCmd(cmd);
-      allCommandResults.push({ cmd, ...result });
+      const structured = structureResult(cmd, result.stdout, result.stderr, result.code);
+      allCommandResults.push({ cmd, ...result, structured });
       historyEntries.push({ cmd, stdout: result.stdout.slice(0, 500), stderr: result.stderr.slice(0, 200), code: result.code, ts: Date.now() });
+
+      // Emit full structured result — frontend sees stdout, stderr, exit code
       send("command_result", {
-        cmd, stdout: result.stdout.substring(0, 1000),
-        stderr: result.stderr.substring(0, 500),
-        index: idx, isError: result.code !== 0 && !!result.stderr
+        cmd,
+        stdout: result.stdout,
+        stderr: result.stderr,
+        exit: result.code,
+        ok: result.code === 0,
+        structured,
+        index: idx,
+        isError: result.code !== 0 && !!result.stderr,
       });
+
       // Auto-fix syntax errors in JS files
       if (cmd.includes("node --check") && result.code !== 0 && result.stderr) {
         const target = cmd.trim().split(/\s+/).pop().replace(/\s*\(.*\)$/, "");
@@ -467,13 +713,19 @@ async function runAgentLoop(opts) {
       return (headBlock + middleBlock + "\n" + tailBlock).substring(0, 2200);
     })();
 
-    // Full command history with actual outputs — this is what the AI uses to
-    // know WHAT grep found, WHAT sed changed, WHERE errors occurred
+    // Full command history with structured outputs — AI knows exactly what grep found,
+    // what sed changed, what errors occurred, without guessing from raw text
     const cmdLog = allCommandResults.slice(-14).map((r, i) => {
-      const out = r.stdout.trim().slice(0, 400);
-      const err = r.stderr.trim().slice(0, 200);
+      const s = r.structured || {};
       const exitLabel = r.code === 0 ? "✓" : `✗(${r.code})`;
-      return `[${i + 1}] ${exitLabel} $ ${r.cmd}${out ? "\n     OUT: " + out : ""}${err ? "\n     ERR: " + err : ""}`;
+      let detail = "";
+      if (s.matches) detail = `\n     MATCHES: ${s.matches.slice(0,10).join(" | ")}`;
+      else if (s.content) detail = `\n     CONTENT: ${s.content.slice(0, 300)}`;
+      else if (r.stdout.trim()) detail = `\n     OUT: ${r.stdout.trim().slice(0, 300)}`;
+      if (r.stderr.trim()) detail += `\n     ERR: ${r.stderr.trim().slice(0, 150)}`;
+      if (s.linesChanged) detail += `\n     EDIT: ${s.linesChanged}`;
+      if (s.syntaxError) detail += `\n     SYNTAX: ${s.syntaxError.slice(0, 120)}`;
+      return `[${i + 1}] ${exitLabel} $ ${r.cmd}${detail}`;
     }).join("\n");
 
     // Highlight any commands that failed — the AI must not repeat them blindly
@@ -500,8 +752,11 @@ PENDING (${pending.length} remaining):
 ${pending.length > 0 ? pending.map((t, i) => `  ${i + 1}. ${t.task}`).join("\n") : "  ALL TASKS DONE"}
 
 COMMAND HISTORY (${allCommandResults.length} total — includes grep results, sed outputs, check results):
-${cmdLog || "  (none yet — start with wc -l and grep -n)"}
-
+${cmdLog || "  (none yet — start with read_file map)"}
+${pendingReadResults.length > 0 ? `
+FILE READ RESULTS (from your read_file requests last round):
+${formatReadResults(pendingReadResults)}
+` : ""}
 FILE CONTENT WITH LINE NUMBERS (use these line numbers in sed -i 'Ns/...' commands):
 ${numberedCtx}
 === END CONTEXT ===`;
@@ -521,40 +776,45 @@ ${numberedCtx}
     .map((l, i) => `${initTailStart + i + 1}\t${l}`).join("\n");
   const initCtx = (initHeadBlock + `\n...[lines 41–${initTailStart} omitted — use grep -n to find sections]...\n` + initTailBlock).substring(0, 2200);
 
+  // ── Auto file map for Round 1 — AI gets full structure before planning ──
+  // This is exactly what Claude does: understand structure before touching anything.
+  const fileMap = buildFileMap(filePath);
+  const fileMapStr = fileMap ? formatReadResults([{ action: "map", result: fileMap }]) : "";
+
   const planPrompt = `You are Cryo - a developer AI agent. You edit files using shell commands.
 
 ${COMMANDS_REFERENCE}
 
+${fileMapStr ? `=== FILE STRUCTURE (auto-read before you start) ===\n${fileMapStr}\n` : ""}
 FILE: ${filePath} | TOTAL LINES: ${fileLines}
-FILE CONTENT (with line numbers — use these in sed -i 'Ns/...' commands):
+FILE CONTENT HEAD+TAIL (with line numbers):
 ${initCtx}
 
 USER REQUEST: "${message}"
 
 ⚠ Complete ONLY what was requested. Do not add unrequested features.
+⚠ The FILE STRUCTURE above shows all functions and sections with line numbers.
+⚠ Use read_file chunk/search to read any section you need before editing.
+⚠ For library swaps or >30% restructures, plan to use full_rewrite after reading.
 
-YOUR FIRST BATCH must follow the mandatory workflow:
-  1. wc -l ${filePath}                        → confirm line count
-  2. grep -n "keyword" ${filePath}            → locate the exact lines to change
-  3. sed -n 'START,ENDp' ${filePath}          → read that section to see exact text
-  4. cp ${filePath} ${filePath}.bak           → backup before editing
-  5. sed -i 'Ns/exact-old-text/new-text/' ${filePath}  → make the targeted edit
-  6. node --check ${filePath}                 → verify syntax (if JS)
+For your FIRST response, output read_file actions to read the sections you'll need,
+OR output commands if you already have enough context from the file map above.
 
 Respond with ONLY raw JSON:
 {
   "task_type": "query" | "edit" | "create",
   "status": "brief status for the user",
   "tasks": [{"task": "specific subtask", "done": false}],
-  "commands": ["wc -l ${filePath}", "grep -n \\"keyword\\" ${filePath}", "..."],
-  "reasoning": "what you are looking for and why",
+  "read_file": [{ "action": "chunk", "start": N, "end": M }, ...],
+  "commands": ["cp ${filePath} ${filePath}.bak", "..."],
+  "reasoning": "what sections you need to read and why",
   "done": false
 }`;
 
   const planRaw = await callAI(planPrompt, "", modelKey, transcript);
   let plan = parseJSON(planRaw);
 
-  if (!plan || !plan.commands) {
+  if (!plan || (!plan.commands && !plan.read_file)) {
     const extracted = extractCommandsFromText(planRaw || "");
     plan = {
       task_type: "edit",
@@ -570,6 +830,17 @@ Respond with ONLY raw JSON:
   send("status", { text: plan.status || "Processing..." });
   send("task_update", { tasks: sessionTasks });
 
+  // Process any read_file actions from the plan (Round 1 reads)
+  if (plan.read_file && Array.isArray(plan.read_file) && plan.read_file.length > 0) {
+    send("status", { text: `Reading file structure (${plan.read_file.map(a => a.action).join(", ")})...` });
+    const readResults = processReadActions(filePath, plan.read_file);
+    pendingReadResults = readResults;
+    for (const r of readResults) {
+      const label = r.action === "map" ? "file map" : r.action === "chunk" ? `lines ${r.start}–${r.end}` : `search "${r.pattern}"`;
+      send("command_result", { cmd: `[read_file:${r.action}] ${filePath} ${label}`, stdout: formatReadResults([r]), stderr: "", exit: 0, ok: true, isError: false, index: cmdIndex++ });
+    }
+  }
+
   await runBatch(plan.commands || []);
 
   // ── ROUNDS 2–N: Continue until all tasks done ─────────────────────────
@@ -589,6 +860,7 @@ ${COMMANDS_REFERENCE}
 ⚠ YOUR ONLY PURPOSE: complete the ORIGINAL REQUEST shown at the top.
 ⚠ READ THE COMMAND HISTORY — it shows what grep found, what lines exist, what failed.
 ⚠ USE THE LINE NUMBERS in the file content to write precise sed -i 'Ns/...' commands.
+⚠ NEVER repeat a command already in COMMAND HISTORY with the same arguments.
 
 DECISION TREE THIS ROUND:
 - If you haven't grepped yet → grep -n first to locate lines
@@ -596,9 +868,12 @@ DECISION TREE THIS ROUND:
 - If you have the exact text → sed -i 'Ns/old/new/' to make the targeted change
 - If you just edited → sed -n 'START,ENDp' to verify the change is in the file
 - If JS file was written → node --check to verify syntax
+- If the change is major (library swap, full restructure) → use full_rewrite with new_content
 - If all tasks verified in file → set done:true
 
-Respond with ONLY raw JSON:
+Respond with ONLY raw JSON (choose A or B):
+
+A) Normal commands:
 {
   "done": true | false,
   "status": "what you are doing",
@@ -607,7 +882,17 @@ Respond with ONLY raw JSON:
   "reasoning": "what the grep/sed output told you and what you are doing next"
 }
 
-CRITICAL: done:true only when sed -n CONFIRMS the change is physically in the file.`;
+B) Full file rewrite (for major changes like library swaps):
+{
+  "done": true,
+  "full_rewrite": true,
+  "new_content": "COMPLETE new file content here",
+  "status": "Rewrote file to use X",
+  "tasks": [{"task": "...", "done": true}],
+  "reasoning": "why a full rewrite is needed"
+}
+
+CRITICAL: done:true only when sed -n CONFIRMS the change is physically in the file, OR full_rewrite:true is set.`;
 
     const contRaw = await callAI(continuePrompt, "", modelKey, transcript);
     let cont = parseJSON(contRaw);
@@ -618,6 +903,84 @@ CRITICAL: done:true only when sed -n CONFIRMS the change is physically in the fi
       cont = { done: false, commands: extracted, tasks: sessionTasks, status: "Continuing...", reasoning: "Extracted" };
     }
 
+    // ── READ_FILE: AI requested structured file inspection ─────────────
+    // Process immediately and store results for the NEXT round's context.
+    // This is the "Claude reads file in chunks" pattern — map → search → chunk → edit.
+    if (cont.read_file && Array.isArray(cont.read_file) && cont.read_file.length > 0) {
+      send("status", { text: `Reading file (${cont.read_file.map(a => a.action).join(", ")})...` });
+      const readResults = processReadActions(filePath, cont.read_file);
+      pendingReadResults = readResults; // will appear in next round's context
+
+      // Also emit each result to the frontend so user can see what was read
+      for (const r of readResults) {
+        const label = r.action === "map" ? "file map"
+          : r.action === "chunk" ? `lines ${r.start}–${r.end}`
+          : `search "${r.pattern}"`;
+        send("command_result", {
+          cmd: `[read_file:${r.action}] ${filePath} ${label}`,
+          stdout: formatReadResults([r]),
+          stderr: "",
+          exit: 0,
+          ok: true,
+          isError: false,
+          index: cmdIndex++,
+        });
+      }
+
+      // Update task list if AI provided one
+      if (cont.tasks && cont.tasks.length > 0) {
+        sessionTasks = cont.tasks;
+        send("task_update", { tasks: sessionTasks });
+      }
+      send("status", { text: cont.status || `Read complete — round ${round + 1} will use results` });
+      // Also run any commands the AI included alongside read_file
+      if (cont.commands && cont.commands.length > 0) await runBatch(cont.commands);
+      continue; // go to next round with read results in context
+    }
+
+    // Clear pending reads once the AI has seen them (they were in this round's context)
+    pendingReadResults = [];
+    if (cont.full_rewrite && cont.new_content) {
+      send("status", { text: "Staging full rewrite..." });
+      const stageName = `__cryo_stage_${Date.now()}${path.extname(filePath)}`;
+      const stagePath = path.join(HOME_DIR, stageName);
+      fs.writeFileSync(stagePath, cont.new_content, "utf8");
+
+      // Validate staged file before overwriting
+      let stageOk = true;
+      if (filePath.endsWith(".js")) {
+        const chk = await runCmd(`node --check ${stageName}`);
+        send("command_result", { cmd: `node --check ${stageName}`, stdout: chk.stdout, stderr: chk.stderr, exit: chk.code, ok: chk.code === 0, isError: chk.code !== 0, index: cmdIndex++ });
+        if (chk.code !== 0) {
+          send("status", { text: "Staged rewrite has syntax errors — fixing..." });
+          await syntaxFixLoop(stageName, send, modelKey, 3, transcript);
+          stageOk = (await runCmd(`node --check ${stageName}`)).code === 0;
+        }
+      }
+
+      if (stageOk) {
+        versionFile(filePath); // backup current before overwrite
+        fs.copyFileSync(stagePath, absPath);
+        fs.unlinkSync(stagePath);
+        fileContent = fs.readFileSync(absPath, "utf8");
+        send("command_result", { cmd: `[full_rewrite] ${filePath}`, stdout: "✓ File replaced atomically", stderr: "", exit: 0, ok: true, isError: false, index: cmdIndex++ });
+        allCommandResults.push({ cmd: `[full_rewrite] ${filePath}`, stdout: "replaced", stderr: "", code: 0 });
+        send("status", { text: "Full rewrite applied ✓" });
+        if (cont.tasks && cont.tasks.length > 0) { sessionTasks = cont.tasks; send("task_update", { tasks: sessionTasks }); }
+        if (cont.done) break;
+        continue;
+      } else {
+        fs.unlinkSync(stagePath);
+        send("status", { text: "Staged rewrite failed validation — continuing with commands" });
+      }
+    }
+
+    if (!cont) {
+      const extracted = extractCommandsFromText(contRaw || "");
+      if (extracted.length === 0) break;
+      cont = { done: false, commands: extracted, tasks: sessionTasks, status: "Continuing...", reasoning: "Extracted" };
+    }
+
     // Update task list from AI's assessment
     if (cont.tasks && cont.tasks.length > 0) {
       sessionTasks = cont.tasks;
@@ -651,10 +1014,21 @@ CRITICAL: done:true only when sed -n CONFIRMS the change is physically in the fi
     plan,
     sessionTasks,
     hadSedEdits: allCommandResults.some(r => r.cmd.startsWith("sed -i") && r.code === 0),
-    hadTeeWrites: allCommandResults.some(r => (r.cmd.startsWith("tee ") || r.cmd.includes(" > ")) && r.code === 0)
+    hadTeeWrites: allCommandResults.some(r => (r.cmd.startsWith("tee ") || r.cmd.includes(" > ")) && r.code === 0),
+    hadFullRewrite: allCommandResults.some(r => r.cmd.startsWith("[full_rewrite]") && r.code === 0),
   };
 }
 
+// ── FILE INSPECT API (map / chunk / search) ───────────────────────────────
+app.post("/api/inspect", (req, res) => {
+  const { filePath, actions } = req.body;
+  if (!filePath) return res.status(400).json({ error: "filePath required" });
+  const abs = path.join(HOME_DIR, filePath);
+  if (!abs.startsWith(HOME_DIR)) return res.status(403).json({ error: "Forbidden" });
+  const results = processReadActions(filePath, actions || [{ action: "map" }]);
+  res.json({ results, formatted: formatReadResults(results) });
+});
+
 // ── FILE TREE ──────────────────────────────────────────────────────────────
 app.get("/api/tree", (req, res) => {
   const buildTree = (dir, base = HOME_DIR) => {
@@ -743,10 +1117,14 @@ app.get("/api/models", (req, res) => {
 app.post("/api/exec", (req, res) => {
   const { command } = req.body;
   if (!isSafeCmd(command)) {
-    return res.json({ stdout: "", stderr: `Blocked: ${command.trim().split(/\s+/)[0]}`, code: 1 });
+    return res.json({ stdout: "", stderr: `Blocked: ${command.trim().split(/\s+/)[0]}`, code: 1, ok: false });
   }
   exec(command, { cwd: HOME_DIR, timeout: 30000, shell: "/bin/bash" }, (err, stdout, stderr) => {
-    res.json({ stdout: stdout || "", stderr: stderr || "", code: err ? (err.code || 1) : 0 });
+    const code = err ? (err.code || 1) : 0;
+    res.json({
+      ...structureResult(command, stdout || "", stderr || "", code),
+      code,
+    });
   });
 });
 
@@ -874,7 +1252,7 @@ RULES:
       filePath, fileContent, message, modelKey, send, maxRounds: 6, transcript
     });
 
-    const { allCommandResults, hadSedEdits, plan } = loopResult;
+    const { allCommandResults, hadSedEdits, hadFullRewrite, plan } = loopResult;
     fileContent = loopResult.fileContent;
 
     const resultsText = allCommandResults
@@ -914,7 +1292,7 @@ RULES:
 
     } else {
       // ── EDIT/CREATE: sed/tee was used → verify & summarize ─────��────────
-      if (hadSedEdits || (loopResult.hadTeeWrites)) {
+      if (hadSedEdits || loopResult.hadTeeWrites || hadFullRewrite) {
         send("status", { text: "Verifying edits..." });
         if (filePath.endsWith(".js")) {
           await syntaxFixLoop(filePath, send, modelKey, 3, transcript);