agy-context-saver 1.4.0 → 1.6.0

package/mcp/index.js

@@ -28,30 +28,51 @@ import os from "node:os";
 import path from "node:path";
 import readline from "node:readline";
 import { fileURLToPath } from "node:url";
-import { runInstall, runUninstall, runStatus, detectExistingInstallation } from "../scripts/install-register.mjs";
+import { runInstall, runUninstall, runStatus, runRestoreBackups, detectExistingInstallation } from "../scripts/install-register.mjs";
 import { findExistingRtk } from "../scripts/provision-rtk.mjs";
 
 // Handle CLI subcommands (e.g. npx agy-context-saver install)
-const cliArg = process.argv[2];
-const checkFlag = process.argv.includes("--check") || process.argv.includes("-c");
-if (cliArg === "install" || cliArg === "--install") {
-  await runInstall({ checkOnly: checkFlag });
+const cliArgs = process.argv.slice(2);
+const cliArg = cliArgs[0];
+const checkFlag = cliArgs.includes("--check") || cliArgs.includes("-c");
+const statusFlag = cliArgs.includes("--status") || cliArgs.includes("status");
+const uninstallFlag = cliArgs.includes("--uninstall") || cliArgs.includes("uninstall");
+const restoreFlag = cliArgs.includes("--restore-backups") || cliArgs.includes("restore-backups");
+const helpFlag = cliArgs.includes("--help") || cliArgs.includes("-h") || cliArgs.includes("help");
+const allowDegraded = cliArgs.includes("--allow-degraded");
+
+if (helpFlag) {
+  printHelp();
   process.exit(0);
-} else if (cliArg === "uninstall" || cliArg === "--uninstall") {
-  const restoreBackups = process.argv.includes("--restore-backups");
-  await runUninstall({ restoreBackups });
+}
+if ((checkFlag || statusFlag) && (uninstallFlag || restoreFlag)) {
+  console.error("Error: Read-only flags (--check, --status) cannot be combined with mutating flags (--uninstall, --restore-backups).");
+  process.exit(1);
+}
+if (checkFlag && statusFlag) {
+  console.error("Error: Conflicting flags: specify either --check or --status, not both.");
+  process.exit(1);
+}
+if (checkFlag) {
+  await runInstall({ checkOnly: true, allowDegraded });
   process.exit(0);
-} else if (cliArg === "status" || cliArg === "--status") {
+} else if (statusFlag) {
   runStatus();
   process.exit(0);
-} else if (cliArg === "--help" || cliArg === "-h" || cliArg === "help") {
-  printHelp();
+} else if (uninstallFlag) {
+  await runUninstall({ restoreBackups: restoreFlag });
+  process.exit(0);
+} else if (restoreFlag) {
+  await runRestoreBackups();
+  process.exit(0);
+} else if (cliArg === "install" || cliArg === "--install") {
+  await runInstall({ allowDegraded });
   process.exit(0);
 }
 
 function printHelp() {
   console.log(`
-Agy-Context-Saver 🛡️ (v1.2.1)
+Agy-Context-Saver 🛡️ (v1.6.0)
 Universal MCP Server & Lifecycle Governor for Google Antigravity (Powered by RTK)
 
 Usage:
@@ -98,7 +119,7 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const rulesPath = path.resolve(__dirname, "../rules/AGENTS.md");
 
 const SERVER_NAME = "agy-context-saver";
-const SERVER_VERSION = "1.4.0";
+const SERVER_VERSION = "1.6.0";
 
 // --- Tools Specification ---
 const TOOLS = [
@@ -121,13 +142,21 @@ const TOOLS = [
   },
   {
     name: "subagent_brief",
-    description: "Generates a scope-isolated, anti-bloat prompt for invoking a subagent. Instructs the subagent to absorb all intermediate file reads/searches and return only high-signal findings.",
+    description: "Generates scope-isolated, anti-bloat prompts and ready-to-use invoke_subagent JSON payloads for single or multiple delegated subagents. Instructs subagents to absorb intermediate file reads/searches and return only high-signal findings.",
     inputSchema: {
       type: "object",
       properties: {
         objective: {
           type: "string",
-          description: "The core research or investigative objective."
+          description: "The core research or investigative objective (for single subagent)."
+        },
+        role: {
+          type: "string",
+          description: "2-5 word role description (e.g. 'Comprehensive Test Engineer', 'Codebase Security Auditor'). Defaults to 'Scope-Isolated Deep Research Subagent'."
+        },
+        instructions: {
+          type: "string",
+          description: "Optional step-by-step instructions or specialized directives."
         },
         scopeFiles: {
           type: "array",
@@ -137,9 +166,40 @@ const TOOLS = [
         expectedDeliverable: {
           type: "string",
           description: "The concise format expected back by the parent agent."
+        },
+        typeName: {
+          type: "string",
+          description: "Subagent type name: 'self' (default, inherits parent tools/prompt/model) or 'research' (read-only)."
+        },
+        model: {
+          type: "string",
+          enum: ["inherit", "flash_lite", "flash", "pro"],
+          description: "Model tier: 'inherit' (default), 'flash_lite', 'flash', or 'pro'."
+        },
+        workspace: {
+          type: "string",
+          enum: ["inherit", "branch", "share"],
+          description: "Workspace isolation: 'inherit' (default), 'branch', or 'share'."
+        },
+        subagents: {
+          type: "array",
+          description: "Optional array of subagent configurations to formulate multiple subagents at once.",
+          items: {
+            type: "object",
+            properties: {
+              role: { type: "string", description: "2-5 word role description." },
+              objective: { type: "string", description: "The core objective for this subagent." },
+              instructions: { type: "string", description: "Optional step-by-step instructions." },
+              scopeFiles: { type: "array", items: { type: "string" }, description: "Files/directories to investigate." },
+              expectedDeliverable: { type: "string", description: "Expected deliverable format." },
+              typeName: { type: "string", description: "Subagent type name: 'self' or 'research'." },
+              model: { type: "string", enum: ["inherit", "flash_lite", "flash", "pro"], description: "Model tier." },
+              workspace: { type: "string", enum: ["inherit", "branch", "share"], description: "Workspace isolation." }
+            },
+            required: ["objective"]
+          }
         }
-      },
-      required: ["objective"]
+      }
     }
   },
   {
@@ -313,55 +373,77 @@ async function handleCheckContextHealth(args = {}) {
     let corruptLines = 0;
     const MAX_LINES = 100000;
 
-    for await (const line of rl) {
-      if (!line.trim()) continue;
-      totalSteps++;
-      totalBytes += line.length;
+    try {
+      for await (const line of rl) {
+        if (!line.trim()) continue;
+        totalSteps++;
+        totalBytes += line.length;
 
-      if (totalSteps > MAX_LINES) {
-        break;
-      }
+        if (totalSteps > MAX_LINES) {
+          break;
+        }
 
-      try {
-        const item = JSON.parse(line);
-        if (item.type === "USER_INPUT") userTurns++;
-        if (item.type === "PLANNER_RESPONSE") modelTurns++;
-        if (item.tool_calls && item.tool_calls.length) {
-          toolCalls += item.tool_calls.length;
-          for (const tc of item.tool_calls) {
-            const name = tc.tool_name || tc.name;
-            const args = tc.args || tc.arguments || {};
-            const action = String(args.Action || args.action || "").replace(/^["']|["']$/g, "").trim().toLowerCase();
-            const prompt = String(args.Prompt || args.prompt || "").replace(/^["']|["']$/g, "").trim().toLowerCase();
-            const cond = String(args.TimerCondition || args.timerCondition || "").replace(/^["']|["']$/g, "").trim().toLowerCase();
-            if (name === "manage_task" && action === "status") pollingEvents++;
-            if (name === "schedule" && (cond.startsWith("task") || cond.includes("task") || prompt.includes("test") || prompt.includes("check on") || prompt.includes("status"))) pollingEvents++;
+        // Fast check for common step types without parsing if no tool calls (PERF-16)
+        const hasToolCalls = line.includes('"tool_calls"');
+        const head = line.slice(0, 300);
+        const isUserInput = head.includes('"type":"USER_INPUT"');
+        const isPlannerResp = head.includes('"type":"PLANNER_RESPONSE"');
+
+        if (!hasToolCalls && (isUserInput || isPlannerResp)) {
+          if (isUserInput) userTurns++;
+          else modelTurns++;
+          continue;
+        }
+
+        try {
+          const item = JSON.parse(line);
+          if (item.type === "USER_INPUT") userTurns++;
+          if (item.type === "PLANNER_RESPONSE") modelTurns++;
+          if (item.tool_calls && item.tool_calls.length) {
+            toolCalls += item.tool_calls.length;
+            for (const tc of item.tool_calls) {
+              const name = tc.tool_name || tc.name;
+              const args = tc.args || tc.arguments || {};
+              const action = String(args.Action || args.action || "").replace(/^["']|["']$/g, "").trim().toLowerCase();
+              const prompt = String(args.Prompt || args.prompt || "").replace(/^["']|["']$/g, "").trim().toLowerCase();
+              const cond = String(args.TimerCondition || args.timerCondition || "").replace(/^["']|["']$/g, "").trim().toLowerCase();
+              if (name === "manage_task" && action === "status") pollingEvents++;
+              if (name === "schedule" && (cond.startsWith("task") || cond.includes("task") || prompt.includes("test") || prompt.includes("check on") || prompt.includes("status"))) pollingEvents++;
+            }
           }
+        } catch (err) {
+          corruptLines++;
         }
-      } catch (err) {
-        corruptLines++;
       }
+    } finally {
+      rl.close();
+      fileStream.destroy();
     }
-
     const kb = (totalBytes / 1024).toFixed(1);
     const healthStatus = pollingEvents > 3 ? "CRITICAL (Active Polling Loops Detected)" : userTurns > 40 ? "WARNING (High Turn Budget)" : "HEALTHY";
 
     const rtkInfo = findExistingRtk();
     const reportLines = [
       `### Context Health Report: ${healthStatus}`,
+      "",
+      "#### [Active Session Metrics]",
       `- Total Steps: ${totalSteps}`,
       `- User Turns: ${userTurns}`,
       `- Assistant Responses: ${modelTurns}`,
       `- Tool Calls: ${toolCalls}`,
       `- Detected Busy-Polling Events: ${pollingEvents}`,
-      `- Approximate Raw Transcript Size: ${kb} KB`,
-      `- RTK Command Optimizer: ${rtkInfo ? `Active (${rtkInfo.version})` : "Missing (run sync_installation)"}`
+      `- Approximate Raw Transcript Size: ${kb} KB`
     ];
 
     if (corruptLines > 0) {
       reportLines.push(`- Corrupted/Unparsed Lines: ${corruptLines}`);
     }
 
+    reportLines.push("");
+    reportLines.push("#### [Local RTK Environment]");
+    reportLines.push(`- RTK Command Optimizer: ${rtkInfo ? `Active (${rtkInfo.version})` : "Missing (run sync_installation)"}`);
+    reportLines.push(`- Note: Lifetime token gains from 'rtk gain' represent cumulative machine-wide host savings, not single-session metrics.`);
+
     reportLines.push("");
     if (pollingEvents > 0) {
       reportLines.push("⚠️ Recommendation: Background polling detected! Cease manage_task(status) calls and yield execution to native Reactive Wakeup.");
@@ -381,11 +463,18 @@ async function handleCheckContextHealth(args = {}) {
   }
 }
 
-function handleSubagentBrief({ objective, scopeFiles = [], expectedDeliverable = "Synthesized factual findings" }) {
-  const scopeStr = scopeFiles.length ? `\n\nTarget files:\n${scopeFiles.map(f => `- ${f}`).join("\n")}` : "";
-  const prompt = [
-    `ROLE: Scope-Isolated Deep Research Subagent`,
-    `OBJECTIVE: ${objective}${scopeStr}`,
+function formatSingleBrief({
+  role = "Scope-Isolated Deep Research Subagent",
+  objective = "",
+  instructions = "",
+  scopeFiles = [],
+  expectedDeliverable = "Synthesized factual findings"
+} = {}) {
+  const scopeStr = scopeFiles && scopeFiles.length ? `\n\nTarget files:\n${scopeFiles.map(f => `- ${f}`).join("\n")}` : "";
+  const instrStr = instructions && instructions.trim() ? `\n\nSPECIFIC INSTRUCTIONS:\n${instructions.trim()}` : "";
+  return [
+    `ROLE: ${role}`,
+    `OBJECTIVE: ${objective}${scopeStr}${instrStr}`,
     ``,
     `CRITICAL CONTEXT GOVERNANCE INSTRUCTIONS (POINTER-OVER-WIRE):`,
     `1. Isolated Workspace: Do all necessary multi-file exploration, searches, and analysis in this subagent sandbox.`,
@@ -399,8 +488,71 @@ function handleSubagentBrief({ objective, scopeFiles = [], expectedDeliverable =
     `4. Format: ${expectedDeliverable}`,
     `5. Citation Mandate: Keep your final response concise, structured, and cite exact file:line references.`
   ].join("\n");
+}
+
+function handleSubagentBrief(args = {}) {
+  let specs = [];
+  if (Array.isArray(args.subagents) && args.subagents.length > 0) {
+    specs = args.subagents;
+  } else if (args.objective || args.role || args.instructions) {
+    specs = [args];
+  } else {
+    return {
+      isError: true,
+      content: [{ type: "text", text: "subagent_brief error: provide either 'objective' (for a single subagent) or 'subagents' array (for multiple subagents)." }]
+    };
+  }
+
+  const subagentsPayload = [];
+  const renderedBriefs = [];
+
+  for (let i = 0; i < specs.length; i++) {
+    const spec = specs[i] || {};
+    const role = spec.role || spec.Role || "Scope-Isolated Deep Research Subagent";
+    const objective = spec.objective || spec.Objective || "";
+    const instructions = spec.instructions || spec.Instructions || "";
+    const scopeFiles = spec.scopeFiles || spec.ScopeFiles || [];
+    const expectedDeliverable = spec.expectedDeliverable || spec.ExpectedDeliverable || "Synthesized factual findings";
+    const typeName = spec.typeName || spec.TypeName || "self";
+    const model = spec.model || spec.Model || "inherit";
+    const workspace = spec.workspace || spec.Workspace || "inherit";
+
+    const promptText = formatSingleBrief({
+      role,
+      objective,
+      instructions,
+      scopeFiles,
+      expectedDeliverable
+    });
+
+    subagentsPayload.push({
+      TypeName: typeName,
+      Role: role,
+      Model: model,
+      Workspace: workspace,
+      Prompt: promptText
+    });
+
+    if (specs.length === 1) {
+      renderedBriefs.push(promptText);
+    } else {
+      renderedBriefs.push(`### Subagent ${i + 1}: ${role}\n${promptText}`);
+    }
+  }
+
+  const payloadJson = JSON.stringify({ Subagents: subagentsPayload }, null, 2);
+
+  const fullText = [
+    renderedBriefs.join("\n\n---\n\n"),
+    "",
+    "==================================================",
+    "READY-TO-USE invoke_subagent PAYLOAD:",
+    "```json",
+    payloadJson,
+    "```"
+  ].join("\n");
 
-  return { content: [{ type: "text", text: prompt }] };
+  return { content: [{ type: "text", text: fullText }] };
 }
 
 function handleGetInstallationStatus() {
@@ -459,6 +611,17 @@ function extractConvId(p) {
   return match ? match[1] : path.basename(normalized, path.extname(normalized));
 }
 
+let cachedActiveConv = null;
+let cachedActiveConvTime = 0;
+
+function getProfileHomeDir() {
+  return process.env.AGY_TEST_PROFILE_DIR || os.homedir();
+}
+
+function getBrainDir() {
+  return process.env.AGY_BRAIN_DIR || path.join(getProfileHomeDir(), ".gemini", "antigravity", "brain");
+}
+
 function resolveTranscriptPath(target, mode = "compact") {
   const isFull = mode === "full";
   const fileName = isFull ? "transcript_full.jsonl" : "transcript.jsonl";
@@ -469,19 +632,38 @@ function resolveTranscriptPath(target, mode = "compact") {
     if (process.env.GEMINI_CONVERSATION_ID) {
       raw = process.env.GEMINI_CONVERSATION_ID;
     } else {
-      const brainDir = path.join(os.homedir(), ".gemini", "antigravity", "brain");
-      if (fs.existsSync(brainDir)) {
+      const now = Date.now();
+      if (cachedActiveConv && (now - cachedActiveConvTime) < 5000) {
+        raw = cachedActiveConv;
+      } else {
+        const brainDir = getBrainDir();
         try {
-          const entries = fs.readdirSync(brainDir, { withFileTypes: true })
-            .filter((d) => d.isDirectory())
-            .map((d) => {
-              const p = path.join(brainDir, d.name);
-              const stat = fs.statSync(p);
-              return { name: d.name, mtime: stat.mtimeMs };
-            })
-            .sort((a, b) => b.mtime - a.mtime);
-          if (entries.length > 0) {
-            raw = entries[0].name;
+          const entries = fs.readdirSync(brainDir, { withFileTypes: true });
+          let bestMtime = 0;
+          let bestName = null;
+          for (const d of entries) {
+            if (!d.isDirectory()) continue;
+            try {
+              const transPath = path.join(brainDir, d.name, ".system_generated", "logs", "transcript.jsonl");
+              const mtime = fs.statSync(transPath).mtimeMs;
+              if (mtime > bestMtime) {
+                bestMtime = mtime;
+                bestName = d.name;
+              }
+            } catch {
+              try {
+                const mtime = fs.statSync(path.join(brainDir, d.name)).mtimeMs;
+                if (mtime > bestMtime) {
+                  bestMtime = mtime;
+                  bestName = d.name;
+                }
+              } catch {}
+            }
+          }
+          if (bestName) {
+            raw = bestName;
+            cachedActiveConv = bestName;
+            cachedActiveConvTime = now;
           }
         } catch {}
       }
@@ -506,14 +688,14 @@ function resolveTranscriptPath(target, mode = "compact") {
     }
   }
 
-  // 4. UUID / Directory resolution under ~/.gemini/antigravity/brain/<id>
-  const homeDir = os.homedir();
-  const brainCandidate = path.join(homeDir, ".gemini", "antigravity", "brain", normalized, ".system_generated", "logs", fileName);
+  // 4. UUID / Directory resolution under <brainDir>/<id>
+  const primaryBrainDir = getBrainDir();
+  const brainCandidate = path.join(primaryBrainDir, normalized, ".system_generated", "logs", fileName);
   if (fs.existsSync(brainCandidate)) {
     return { filePath: brainCandidate, convId: normalized };
   }
   if (isFull) {
-    const compactFallback = path.join(homeDir, ".gemini", "antigravity", "brain", normalized, ".system_generated", "logs", "transcript.jsonl");
+    const compactFallback = path.join(primaryBrainDir, normalized, ".system_generated", "logs", "transcript.jsonl");
     if (fs.existsSync(compactFallback)) {
       return { filePath: compactFallback, convId: normalized };
     }
@@ -541,6 +723,11 @@ function cleanMessageContent(content, maxChars = MAX_TURN_CHARS) {
     return text;
   }
 
+  const origLength = text.length;
+  // Pre-slice huge text to ~4x maxChars before heavy regex and line clamping (PERF-15)
+  if (text.length > maxChars * 4) {
+    text = text.slice(0, maxChars * 4);
+  }
   // Strip huge base64 media blocks only if relevant keywords or large length
   if (text.includes("base64") || text.length > 200) {
     text = text.replace(/data:image\/[^;]+;base64,[A-Za-z0-9+/=]+/g, "[Embedded Media/Binary Omitted]");
@@ -563,8 +750,9 @@ function cleanMessageContent(content, maxChars = MAX_TURN_CHARS) {
     }
   }
 
-  if (text.length > maxChars) {
-    return text.slice(0, maxChars) + `\n\n... [Content Truncated (${text.length - maxChars} chars omitted to preserve token budget)] ...`;
+  if (origLength > maxChars || text.length > maxChars) {
+    const omitted = Math.max(origLength - maxChars, 0);
+    return text.slice(0, maxChars) + `\n\n... [Content Truncated (${omitted} chars omitted to preserve token budget)] ...`;
   }
   return text;
 }
@@ -662,12 +850,14 @@ function getCompiledRegex(pattern) {
 
 async function batchFindFullSteps(fullPath, stepIndicesSet) {
   const result = new Map();
-  if (!fs.existsSync(fullPath) || !stepIndicesSet || stepIndicesSet.size === 0) return result;
-
-  const fileStream = fs.createReadStream(fullPath, { encoding: "utf-8" });
-  const rl = readline.createInterface({ input: fileStream, crlfDelay: Infinity });
+  if (!stepIndicesSet || stepIndicesSet.size === 0) return result;
 
+  let fileStream;
+  let rl;
   try {
+    fileStream = fs.createReadStream(fullPath, { encoding: "utf-8" });
+    rl = readline.createInterface({ input: fileStream, crlfDelay: Infinity });
+
     for await (const line of rl) {
       if (!line.trim()) continue;
       try {
@@ -675,13 +865,15 @@ async function batchFindFullSteps(fullPath, stepIndicesSet) {
         if (stepIndicesSet.has(item.step_index)) {
           result.set(item.step_index, item);
           if (result.size >= stepIndicesSet.size) {
-            rl.close();
             break;
           }
         }
       } catch {}
     }
-  } catch {}
+  } catch {} finally {
+    if (rl) rl.close();
+    if (fileStream) fileStream.destroy();
+  }
   return result;
 }
 
@@ -697,35 +889,49 @@ async function handleReadTranscript({ conversationId, mode = "compact", lastTurn
   }
 
   const { filePath, convId } = resolved;
-  const items = [];
-  const fileStream = fs.createReadStream(filePath, { encoding: "utf-8" });
-  const rl = readline.createInterface({ input: fileStream, crlfDelay: Infinity });
+  const rawLines = [];
+  let fileStream;
+  let rl;
 
   let totalStepsCount = 0;
   const WINDOW_SIZE = lastTurns > 0 ? Math.max(100, lastTurns * 15) : Infinity;
 
   try {
+    fileStream = fs.createReadStream(filePath, { encoding: "utf-8" });
+    rl = readline.createInterface({ input: fileStream, crlfDelay: Infinity });
     for await (const line of rl) {
-      if (!line.trim()) continue;
-      try {
-        const item = JSON.parse(line);
-        totalStepsCount++;
-        items.push(item);
-        if (items.length > WINDOW_SIZE) {
-          items.shift();
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      totalStepsCount++;
+      if (WINDOW_SIZE === Infinity) {
+        rawLines.push(trimmed);
+      } else {
+        rawLines.push(trimmed);
+        if (rawLines.length > WINDOW_SIZE) {
+          rawLines.shift();
         }
-      } catch {
-        // Tolerates incomplete trailing flushes during concurrent writes
       }
     }
   } catch (err) {
     return { isError: true, content: [{ type: "text", text: `Error reading transcript stream: ${err.message}` }] };
+  } finally {
+    if (rl) rl.close();
+    if (fileStream) fileStream.destroy();
   }
 
   if (totalStepsCount === 0) {
     return { content: [{ type: "text", text: `Transcript is empty at: ${filePath}` }] };
   }
 
+  const items = [];
+  for (const line of rawLines) {
+    try {
+      items.push(JSON.parse(line));
+    } catch {
+      // Tolerates incomplete trailing flushes during concurrent writes
+    }
+  }
+
   let selected = items;
   if (lastTurns > 0) {
     const turnItems = items.filter((it) => it.type === "USER_INPUT" || it.type === "PLANNER_RESPONSE");
@@ -733,7 +939,6 @@ async function handleReadTranscript({ conversationId, mode = "compact", lastTurn
     const minStep = turnItems[cutoff] ? turnItems[cutoff].step_index : 0;
     selected = items.filter((it) => (it.step_index || 0) >= minStep);
   }
-
   const header = [
     `# Conversation Transcript: \`${convId}\``,
     `- Mode: **${mode}** (${path.basename(filePath)})`,
@@ -798,17 +1003,16 @@ async function handleQueryTranscript(args = {}) {
 
     const resolvedFull = resolveTranscriptPath(conversationId, "full");
     let step = null;
-    if (resolvedFull && resolvedFull.filePath && fs.existsSync(resolvedFull.filePath)) {
+    if (resolvedFull && resolvedFull.filePath) {
       step = await findFullStep(resolvedFull.filePath, numIndex);
     }
 
     if (!step) {
       const resolvedCompact = resolveTranscriptPath(conversationId, "compact");
-      if (resolvedCompact && resolvedCompact.filePath && fs.existsSync(resolvedCompact.filePath)) {
+      if (resolvedCompact && resolvedCompact.filePath) {
         step = await findFullStep(resolvedCompact.filePath, numIndex);
       }
     }
-
     if (!step) {
       return {
         isError: true,
@@ -888,20 +1092,31 @@ async function handleQueryTranscript(args = {}) {
 
   const { filePath, convId } = resolved;
   const fullSiblingPath = filePath.replace(/transcript\.jsonl$/, "transcript_full.jsonl");
-  const hasFullSibling = fs.existsSync(fullSiblingPath);
 
   const roleSet = new Set((Array.isArray(roles) ? roles : [roles]).map((r) => String(r).toLowerCase()));
   const matchAllRoles = roleSet.has("all");
 
   const queryRegex = getCompiledRegex(query);
+  const isPlainLiteral = query && /^[A-Za-z0-9_ -]+$/.test(query);
 
-  const matched = [];
-  const fileStream = fs.createReadStream(filePath, { encoding: "utf-8" });
-  const rl = readline.createInterface({ input: fileStream, crlfDelay: Infinity });
+  const effectiveLimit = Math.min(lastTurns > 0 ? lastTurns : Infinity, maxResults > 0 ? maxResults : 5);
+  const ringCap = Number.isFinite(effectiveLimit) ? effectiveLimit : 1000;
+  const ring = [];
+  let matchedCount = 0;
+
+  let fileStream;
+  let rl;
 
   try {
+    fileStream = fs.createReadStream(filePath, { encoding: "utf-8" });
+    rl = readline.createInterface({ input: fileStream, crlfDelay: Infinity });
+
     for await (const line of rl) {
       if (!line.trim()) continue;
+
+      // PERF-12: Raw-line prefilter for plain literal queries
+      if (isPlainLiteral && !queryRegex.test(line)) continue;
+
       let item;
       try {
         item = JSON.parse(line);
@@ -943,13 +1158,20 @@ async function handleQueryTranscript(args = {}) {
         if (!matches) continue;
       }
 
-      matched.push(item);
+      matchedCount++;
+      ring.push(item);
+      if (ring.length > ringCap) {
+        ring.shift();
+      }
     }
   } catch (err) {
     return { isError: true, content: [{ type: "text", text: `Error streaming transcript: ${err.message}` }] };
+  } finally {
+    if (rl) rl.close();
+    if (fileStream) fileStream.destroy();
   }
 
-  if (matched.length === 0) {
+  if (matchedCount === 0) {
     return {
       content: [{
         type: "text",
@@ -958,8 +1180,8 @@ async function handleQueryTranscript(args = {}) {
     };
   }
 
-  let finalItems = matched;
-  if (lastTurns && lastTurns > 0) {
+  let finalItems = ring;
+  if (lastTurns && lastTurns > 0 && finalItems.length > lastTurns) {
     finalItems = finalItems.slice(-lastTurns);
   }
   if (finalItems.length > maxResults) {
@@ -967,8 +1189,8 @@ async function handleQueryTranscript(args = {}) {
   }
 
   // Auto-dereferencing if mode is "auto" and fields were truncated (single pass)
-  if (mode === "auto" && hasFullSibling) {
-    const truncatedIndices = new Set();
+  // PERF-17: check fs.existsSync(fullSiblingPath) lazily ONLY if truncatedIndices.size > 0
+  if (mode === "auto") {    const truncatedIndices = new Set();
     for (const it of finalItems) {
       if (Array.isArray(it.truncated_fields) && it.truncated_fields.length > 0 && it.step_index !== undefined) {
         truncatedIndices.add(it.step_index);
@@ -1002,7 +1224,7 @@ async function handleQueryTranscript(args = {}) {
     const header = [
       `## Transcript Query Summary: \`${convId}\``,
       `- Filter: query=${query ? `"${query}"` : "NONE"}, roles=[${Array.from(roleSet).join(", ")}], mode=${mode}`,
-      `- Matched Steps: ${matched.length} (showing ${finalItems.length} in compact summary mode)`,
+      `- Matched Steps: ${matchedCount} (showing ${finalItems.length} in compact summary mode)`,
       "",
       "---",
       ""
@@ -1018,7 +1240,7 @@ async function handleQueryTranscript(args = {}) {
   const header = [
     `## Transcript Query Results: \`${convId}\``,
     `- Filter: query=${query ? `"${query}"` : "NONE"}, roles=[${Array.from(roleSet).join(", ")}], mode=${mode}`,
-    `- Matched Steps: ${matched.length} (showing ${finalItems.length})`,
+    `- Matched Steps: ${matchedCount} (showing ${finalItems.length})`,
     "",
     "---",
     ""