agy-context-saver 1.3.2 → 1.5.0

package/CHANGELOG.md

@@ -5,6 +5,40 @@ All notable changes to `Agy-Context-Saver` will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.5.0] - 2026-10-08
+
+### Performance & Memory Optimizations
+- **File-Descriptor Leak Fixes (PERF-01, PERF-02)**: Ensured guaranteed stream destruction via `finally { rl.close(); fileStream.destroy(); }` across `batchFindFullSteps`, `handleCheckContextHealth`, `handleReadTranscript`, and `handleQueryTranscript`, eliminating open handle leaks on early exits and line caps (verified 0/20 leaked).
+- **Subprocess Call Reduction in PreToolUse Hook (PERF-03)**: Dropped redundant `rtk --version` probe in hook initialization; executes `rtk rewrite` directly and falls back to plugin binary only on `ENOENT`, reducing cache miss latency from 302ms to 249ms (-17.5%).
+- **Surgical Tail-Window Task State Resolution (PERF-04, PERF-07)**: Unified task lifecycle checking into a single `getTaskState()` reading the last 256KB tail of `transcript.jsonl` with literal needle matching (`scanTaskMarkers`), dropping check latency from 123ms to 2ms on 10.5MB transcripts (-98%).
+- **Atomic Concurrency-Safe Rewrite Cache (PERF-05, PERF-09)**: Rewrite cache now filters out timeouts and non-zero/non-clean exit codes, re-reads disk state to merge concurrent updates, and persists atomically via temporary files.
+- **Pre-Rewrite Fast Denial Ordering (PERF-10)**: Reordered command checks so raw-command gates (internal state access and running task log denials) execute before invoking `rtk rewrite`, eliminating subprocess overhead for denied commands.
+- **Bounded Query Memory & Raw-Line Prefilter (PERF-11, PERF-12)**: Implemented ring-buffered step retention bounded by `effectiveLimit` with `matchedCount` in `query_transcript`, and added raw-line ASCII substring pre-filtering to skip `JSON.parse` on non-matching lines.
+- **Active Conversation Resolution Cache (PERF-13)**: Cached `resolveTranscriptPath("current")` lookups for 5s and implemented resilient per-entry directory stats.
+- **Sliding-Window Parsing & String Pre-Slicing (PERF-14, PERF-15, PERF-16)**: `read_transcript` now streams raw lines and only parses retained turns; `cleanMessageContent` pre-slices oversized payloads to `4 * maxChars` before running regexes; `check_context_health` skips parsing for steps without tool calls.
+- **Redundant Syscall Elimination (PERF-17, PERF-18, PERF-19)**: Removed unnecessary `existsSync` checks before reads and replaced dynamic task id regexes with literal string searching.
+
+### Governance & Configuration Hardening
+- **Installed Hook Matcher Inclusion (OBS-A)**: Added `replace_file_content|write_to_file` to hook matchers in `hooks.json` and `scripts/install-register.mjs`, ensuring benchmark mutation guards (LH-09) are wired in installed environments.
+- **Transcript Authority for Silent Running Tasks (OBS-B)**: Updated task state resolver to treat background tasks with start notices as actively `RUNNING` regardless of log quiet duration until an explicit finish notice appears, preventing premature inspection of quiet background jobs.
+
+---
+
+## [1.4.0] - 2026-10-08
+
+### Added (Output Inspection Governance & Forensic Dereferencing - LH-12)
+- **Folded Surgical Step Dereferencing in `query_transcript` (NFF-05)**: Added optional `stepIndex` (number) and `field` (string) parameters to `query_transcript`, allowing surgical single-step extraction from `transcript_full.jsonl` without creating redundant tools. Recovers un-truncated subagent messages and arguments with zero surrounding context bloat.
+- **Safe-Harbor `rtk read` for Step Output Spillovers (NFF-01 & NFF-02)**: Provided a safe harbor in `execution-guard-hook.mjs` allowing `rtk read` on runtime step output spillovers (`.system_generated/steps/<step>/output.txt`). Native `view_file` and shell `cat` invocations are automatically routed to `rtk read <path>`, leveraging `rtk read`'s built-in line clamping, head/tail windowing, and token truncation.
+- **Lifecycle-Gated Task Output Inspection (NFF-03)**: Added lifecycle governance for background task logs (`tasks/<taskId>.log`) in `execution-guard-hook.mjs`. Invocations are strictly **denied** under Proportional Backoff while tasks are `RUNNING` to stop polling loops, but allowed via `rtk read` once `COMPLETED` / `TERMINATED` for bounded stack trace and failure inspection.
+- **Pointer-Over-Wire (POW) Subagent Contract (NFF-06)**: Integrated the POW protocol into `subagent_brief`. Research findings $>1\text{ KB}$ are written to workspace artifacts (`scratch/...`), while `send_message` transmits only executive summaries and clickable file links, preventing message bus truncations.
+- **Output Governance Test Suite**: Added `tests/test-output-governance.mjs` verifying spillover safe-harbor access, task output lifecycle gating, forensic step extraction, and hook routing.
+
+### Changed
+- **Streamlined Tool Architecture (0 New Tools)**: Eliminated tool proliferation by consolidating capabilities into existing tools and hooks, maintaining strictly the 6 core canonical MCP tools (zero prompt token bloat, zero tool-selection ambiguity).
+- **Typed Argument Descriptors (NFF-04)**: Replaced blind `JSON.stringify().slice(0, 80)` in `formatTranscriptItem()` with typed argument descriptors (`[14.2 KB String]`, `[Array(5)]`, `{Object(3 keys)}`), preserving JSON payload integrity and transcript legibility.
+
+---
+
 ## [1.3.2] - 2026-10-07
 
 ### Governance & Command Semantics (LH-11 Hardening)

package/README.md

@@ -103,6 +103,33 @@ npm run status
 
 ---
 
+## Comprehensive Documentation
+
+For complete technical references, architectural specifications, and governance rules, visit our **[Zensical Documentation Site](https://paragon-ux.github.io/agy-context-saver/)**:
+
+- 📖 **[Getting Started & Installation](docs/installation.md)**: Zero-delay setup, native plugin linking, hooks registration, and verification matrix.
+- 🏗️ **[Architecture & Internals](docs/architecture.md)**: Closed Execution Topology, RTK separation of concerns, and the Four Non-Fragile Architectural Pillars.
+- 🛡️ **[Lifecycle Governance & Hooks](docs/governance.md)**: Proportional Backoff curve, Reactive Wakeup invariants, and the 5-strike circuit breaker.
+- 🧰 **[MCP Tools & CLI Reference](docs/tools.md)**: Complete specifications for all 6 canonical autonomous MCP tools, slash commands, and diagnostic utilities.
+- 🔬 **[Forensic & Output Inspection](docs/architecture.md#6-output-governance--spillover-safe-harbor-0-new-tools)**: Ephemeral tool spillover resolution, post-mortem task retrieval, and Pointer-Over-Wire (POW) contracts.
+- 🚀 **[Publishing & Verification Playbook](docs/publishing.md)**: Clean-room test runs, release procedures, and multi-suite verification matrix.
+
+---
+
+## Local Documentation Server
+
+Build or serve the documentation locally using **Zensical**:
+
+```bash
+# Build static documentation site
+zensical build
+
+# Serve live preview server
+zensical serve
+```
+
+---
+
 ## Zero-Guesswork Testing & Verification Playbook
 
 To cleanly test every layer of the framework without guesswork or interactive stalls:
@@ -119,7 +146,7 @@ node mcp/index.js status
 ```bash
 npm test
 ```
-*Runs all 5 test suites (28 hook tests, MCP protocol tests, E2E probes, installed verification, lifecycle rollback).*
+*Runs all 7 test suites (hook governance, MCP protocol, output inspection governance, E2E probes, performance probes, installed verification, lifecycle rollback).*
 
 ### 3. Run Targeted Tests Individually
 ```bash
@@ -129,9 +156,15 @@ node tests/test-hook.mjs
 # MCP server protocol & method tests
 node tests/test-mcp.mjs
 
+# Output inspection & lifecycle gating tests
+node tests/test-output-governance.mjs
+
 # End-to-end edge case & probe tests
 node tests/test-e2e-probes.mjs
 
+# Performance, streaming & memory probes
+node tests/test-performance-probes.mjs
+
 # Live installed environment verification
 node tests/test-installed-verification.mjs
 
@@ -160,12 +193,16 @@ node tests/test-lifecycle-rollback.mjs
   - `/mcp:agy-context-saver:context_shield`: Injects 3-layer governance rules and RTK standards into any session with one click. *(MCP Prompts appear in your chat autocomplete menu; MCP Tools are called autonomously by the agent).*
 * **Agent MCP Tools**:
   1. `check_context_health`: Diagnoses conversation transcript turn budgets, payload size, RTK status, and polling loops.
-  2. `subagent_brief`: Formulates scope-isolated prompts for delegated subagents.
+  2. `subagent_brief`: Formulates scope-isolated prompts for delegated subagents with Pointer-Over-Wire (POW) delivery contract.
   3. `read_transcript`: Reads recent conversation history in clean Markdown format (compact/full).
-  4. `query_transcript`: Forensic filtering and regex search engine for conversation logs.
+  4. `query_transcript`: Forensic filtering, regex search engine, and surgical single-step dereferencing (`stepIndex`, `field`) from full transcripts.
   5. `get_installation_status`: Inspects live Antigravity plugin link, hook, MCP server, tool schemas, and RTK binary.
   6. `sync_installation`: Re-verifies and repairs all integration layers in ~25ms.
 
+* **Streamlined Output Inspection (0 New Tools)**:
+  - **Runtime Step Spillovers** (`.system_generated/steps/<step>/output.txt`): Inspected via canonical `rtk read <path>` (safe-harbored in the PreToolUse hook; native `view_file` calls automatically route to `rtk read`).
+  - **Completed Background Task Logs**: Inspected via `rtk read tasks/<taskId>.log` (lifecycle-gated in the PreToolUse hook; strictly blocked under Proportional Backoff while running, allowed once completed).
+
 ---
 
 ## License

package/hooks.json

@@ -2,7 +2,7 @@
   "agy-context-saver": {
     "PreToolUse": [
       {
-        "matcher": "manage_task|run_command|schedule",
+        "matcher": "manage_task|schedule|run_command|view_file|read_file|read_many_files|grep_search|find_by_name|list_dir|replace_file_content|write_to_file",
         "hooks": [
           {
             "type": "command",

package/mcp/index.js

@@ -98,7 +98,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.3.2";
+const SERVER_VERSION = "1.5.0";
 
 // --- Tools Specification ---
 const TOOLS = [
@@ -243,6 +243,14 @@ const TOOLS = [
         summaryOnly: {
           type: "boolean",
           description: "If true, returns high-density 1-line step summaries instead of full message blocks to minimize UI card height (default: false)."
+        },
+        stepIndex: {
+          type: "number",
+          description: "Optional step_index to surgically retrieve full un-truncated content for a single step from transcript_full.jsonl."
+        },
+        field: {
+          type: "string",
+          description: "Optional specific field to extract when stepIndex is provided (e.g. 'content', 'thinking', 'tool_calls', 'tool_args', or 'tool_args:Message'). Defaults to full step."
         }
       },
       required: ["conversationId"]
@@ -305,36 +313,52 @@ 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";
 
@@ -379,12 +403,17 @@ function handleSubagentBrief({ objective, scopeFiles = [], expectedDeliverable =
     `ROLE: Scope-Isolated Deep Research Subagent`,
     `OBJECTIVE: ${objective}${scopeStr}`,
     ``,
-    `CRITICAL CONTEXT GOVERNANCE INSTRUCTIONS:`,
-    `1. You are running in an isolated subagent sandbox. Do all necessary multi-file exploration, searches, and analysis here.`,
-    `2. DO NOT dump raw file contents or massive grep outputs in your final response.`,
-    `3. Deliver strictly the high-signal findings in the following format:`,
-    `   ${expectedDeliverable}`,
-    `4. Keep your final response concise, structured, and cite exact file:line references.`
+    `CRITICAL CONTEXT GOVERNANCE INSTRUCTIONS (POINTER-OVER-WIRE):`,
+    `1. Isolated Workspace: Do all necessary multi-file exploration, searches, and analysis in this subagent sandbox.`,
+    `2. Pointer-Over-Wire (POW) Protocol: In-band messaging channels (send_message) have strict transport payload limits (~16-20 KB). If your findings or deliverable exceed 1 KB:`,
+    `   a. Write the full comprehensive deliverable or raw output to a file in the workspace (e.g., 'scratch/<task>_findings.md' or an artifact).`,
+    `   b. In 'send_message', transmit ONLY:`,
+    `      - Executive Summary (3-5 high-signal sentences)`,
+    `      - Verdict / Scoreboard Table`,
+    `      - Clickable File Link: [Full Deliverable](file:///absolute/path/to/findings.md)`,
+    `3. Fast Turn Termination: Once 'send_message' is dispatched, stop calling tools and conclude your turn immediately so the parent agent wakes up without latency.`,
+    `4. Format: ${expectedDeliverable}`,
+    `5. Citation Mandate: Keep your final response concise, structured, and cite exact file:line references.`
   ].join("\n");
 
   return { content: [{ type: "text", text: prompt }] };
@@ -393,12 +422,13 @@ function handleSubagentBrief({ objective, scopeFiles = [], expectedDeliverable =
 function handleGetInstallationStatus() {
   const existing = detectExistingInstallation();
   const rtkInfo = findExistingRtk();
+  const schemaText = existing.details.schemas.exists ? "ALL 6 SCHEMAS PRESENT" : "MISSING";
   const report = [
     `### Agy-Context-Saver Installation Status: ${existing.isComplete ? "HEALTHY & ACTIVE 🛡️" : existing.isInstalled ? "PARTIAL INSTALLATION ⚠️" : "NOT INSTALLED ❌"}`,
     `- Native Plugin Link: ${existing.details.plugin.exists ? `ACTIVE (${existing.details.plugin.target})` : "NOT LINKED"}`,
     `- Governor Lifecycle Hook: ${existing.details.hook.registered ? "REGISTERED in hooks.json" : "NOT REGISTERED"} (Script: ${existing.details.hook.scriptExists ? "Present" : "Missing"})`,
     `- Universal MCP Server: ${existing.details.mcp.registered ? "CONFIGURED in mcp_config.json" : "NOT CONFIGURED"}`,
-    `- Antigravity Tool Schemas: ${existing.details.schemas.exists ? "ALL 6 SCHEMAS PRESENT" : "MISSING"} (${existing.details.schemas.dir})`,
+    `- Antigravity Tool Schemas: ${schemaText} (${existing.details.schemas.dir})`,
     `- RTK Binary: ${rtkInfo ? `INSTALLED (${rtkInfo.version})` : "MISSING"}`,
     `- RTK Hook Optimization: ${existing.details.hook.registered ? "ACTIVE (via PreToolUse)" : "INACTIVE"}`,
     "",
@@ -445,6 +475,9 @@ function extractConvId(p) {
   return match ? match[1] : path.basename(normalized, path.extname(normalized));
 }
 
+let cachedActiveConv = null;
+let cachedActiveConvTime = 0;
+
 function resolveTranscriptPath(target, mode = "compact") {
   const isFull = mode === "full";
   const fileName = isFull ? "transcript_full.jsonl" : "transcript.jsonl";
@@ -455,19 +488,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 = path.join(os.homedir(), ".gemini", "antigravity", "brain");
         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 {}
       }
@@ -527,6 +579,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]");
@@ -549,12 +606,35 @@ 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;
 }
 
+function formatArgumentDescriptor(k, v) {
+  if (typeof v === "string") {
+    if (v.length <= 80 && !v.includes("\n")) {
+      return `${k}=${JSON.stringify(v)}`;
+    }
+    const preview = v.replace(/[\r\n\t]+/g, " ").slice(0, 50).trim();
+    const sizeKb = (Buffer.byteLength(v, "utf8") / 1024).toFixed(1);
+    return `${k}="${preview}..." [${sizeKb} KB]`;
+  }
+  if (typeof v === "number" || typeof v === "boolean" || v === null) {
+    return `${k}=${v}`;
+  }
+  if (Array.isArray(v)) {
+    return `${k}=[Array(${v.length})]`;
+  }
+  if (typeof v === "object") {
+    const keys = Object.keys(v);
+    return `${k}={Object(${keys.length} keys)}`;
+  }
+  return `${k}=${String(v).slice(0, 60)}`;
+}
+
 function formatTranscriptItem(item, options = {}) {
   const { includeThinking = false, includeToolCalls = false, maxContentChars = MAX_TURN_CHARS } = options;
   const stepIdx = item.step_index !== undefined ? item.step_index : "?";
@@ -583,7 +663,7 @@ function formatTranscriptItem(item, options = {}) {
       const name = tc.name || tc.tool_name || "unknown_tool";
       const args = tc.args || tc.arguments || {};
       const compactArgs = Object.entries(args)
-        .map(([k, v]) => `${k}=${JSON.stringify(v).slice(0, 80)}`)
+        .map(([k, v]) => formatArgumentDescriptor(k, v))
         .join(", ");
       return `- \`${name}(${compactArgs})\``;
     });
@@ -626,12 +706,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 {
@@ -639,13 +721,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;
 }
 
@@ -661,35 +745,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");
@@ -697,7 +795,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)})`,
@@ -745,9 +842,105 @@ async function handleQueryTranscript(args = {}) {
     includeThinking = false,
     includeToolCalls = false,
     maxResults = 5,
-    summaryOnly = false
+    summaryOnly = false,
+    stepIndex,
+    field
   } = args;
 
+  // Surgical single-step dereferencing (folded from get_step_detail)
+  if (stepIndex !== undefined && stepIndex !== null) {
+    const numIndex = Number(stepIndex);
+    if (isNaN(numIndex)) {
+      return {
+        isError: true,
+        content: [{ type: "text", text: `Error: 'stepIndex' must be a number (received: ${stepIndex}).` }]
+      };
+    }
+
+    const resolvedFull = resolveTranscriptPath(conversationId, "full");
+    let step = null;
+    if (resolvedFull && resolvedFull.filePath) {
+      step = await findFullStep(resolvedFull.filePath, numIndex);
+    }
+
+    if (!step) {
+      const resolvedCompact = resolveTranscriptPath(conversationId, "compact");
+      if (resolvedCompact && resolvedCompact.filePath) {
+        step = await findFullStep(resolvedCompact.filePath, numIndex);
+      }
+    }
+    if (!step) {
+      return {
+        isError: true,
+        content: [{ type: "text", text: `Step index ${numIndex} not found in transcript.` }]
+      };
+    }
+
+    const MAX_FIELD_CHARS = 24000;
+
+    if (field) {
+      const f = String(field).trim();
+      if (f === "content") {
+        const val = step.content || "(No content in step)";
+        return {
+          content: [{ type: "text", text: `### Step ${numIndex} Content\n\n${val.slice(0, MAX_FIELD_CHARS)}` }]
+        };
+      }
+      if (f === "thinking") {
+        const val = step.thinking || "(No thinking block in step)";
+        return {
+          content: [{ type: "text", text: `### Step ${numIndex} Thinking\n\n${val.slice(0, MAX_FIELD_CHARS)}` }]
+        };
+      }
+      if (f === "tool_calls") {
+        const val = JSON.stringify(step.tool_calls || [], null, 2);
+        return {
+          content: [{ type: "text", text: `### Step ${numIndex} Tool Calls\n\`\`\`json\n${val.slice(0, MAX_FIELD_CHARS)}\n\`\`\`` }]
+        };
+      }
+      if (f === "tool_args" || f.startsWith("tool_args:")) {
+        const argName = f.includes(":") ? f.split(":")[1].trim() : null;
+        const tc = Array.isArray(step.tool_calls) && step.tool_calls.length > 0 ? step.tool_calls[0] : null;
+        if (!tc) {
+          return {
+            content: [{ type: "text", text: `Step ${numIndex} contains no tool calls.` }]
+          };
+        }
+        const tcArgs = tc.args || tc.arguments || {};
+        if (argName) {
+          const argVal = tcArgs[argName];
+          const displayVal = typeof argVal === "string" ? argVal : JSON.stringify(argVal, null, 2);
+          return {
+            content: [
+              {
+                type: "text",
+                text: `### Step ${numIndex} Argument: \`${argName}\`\n\n${String(displayVal).slice(0, MAX_FIELD_CHARS)}`
+              }
+            ]
+          };
+        }
+        return {
+          content: [
+            {
+              type: "text",
+              text: `### Step ${numIndex} Tool Arguments\n\`\`\`json\n${JSON.stringify(tcArgs, null, 2).slice(0, MAX_FIELD_CHARS)}\n\`\`\``
+            }
+          ]
+        };
+      }
+    }
+
+    const formatted = formatTranscriptItem(step, {
+      includeThinking: true,
+      includeToolCalls: true,
+      maxContentChars: MAX_FIELD_CHARS
+    });
+
+    return {
+      content: [{ type: "text", text: formatted }]
+    };
+  }
+
   const resolved = resolveTranscriptPath(conversationId, mode === "full" ? "full" : "compact");
   if (resolved.error) {
     return { isError: true, content: [{ type: "text", text: resolved.error }] };
@@ -755,20 +948,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);
@@ -810,13 +1014,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",
@@ -825,8 +1036,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) {
@@ -834,8 +1045,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);
@@ -869,7 +1080,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)`,
       "",
       "---",
       ""
@@ -885,7 +1096,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})`,
     "",
     "---",
     ""

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agy-context-saver",
-  "version": "1.3.2",
+  "version": "1.5.0",
   "description": "Universal Model Context Protocol (MCP) server & lifecycle governor purpose-built for Google Antigravity",
   "main": "mcp/index.js",
   "bin": {
@@ -12,7 +12,7 @@
     "setup": "node scripts/install-register.mjs",
     "uninstall": "node scripts/install-register.mjs --uninstall",
     "status": "node scripts/install-register.mjs --status",
-    "test": "node tests/test-hook.mjs && node tests/test-mcp.mjs && node tests/test-e2e-probes.mjs && node tests/test-performance-probes.mjs && node tests/test-installed-verification.mjs && node tests/test-lifecycle-rollback.mjs"
+    "test": "node tests/test-hook.mjs && node tests/test-mcp.mjs && node tests/test-output-governance.mjs && node tests/test-e2e-probes.mjs && node tests/test-performance-probes.mjs && node tests/test-installed-verification.mjs && node tests/test-lifecycle-rollback.mjs"
   },
   "keywords": [
     "antigravity",

package/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "agy-context-saver",
-  "version": "1.2.1",
+  "version": "1.5.0",
   "description": "Deterministic background polling governor and subagent context preservation shield for Antigravity"
 }

package/scripts/execution-guard-hook.mjs

@@ -66,13 +66,11 @@ function getStateFilePath(convId = "global") {
 function getSessionState(convId = "global") {
   const file = getStateFilePath(convId);
   try {
-    if (fs.existsSync(file)) {
-      const parsed = JSON.parse(fs.readFileSync(file, "utf-8"));
-      const entry = (parsed && typeof parsed.pollCount === "number") ? parsed : (parsed && parsed[convId]);
-      const now = Date.now();
-      if (entry && typeof entry.lastPollTime === "number" && (now - entry.lastPollTime) < STATE_TTL_MS) {
-        return entry;
-      }
+    const parsed = JSON.parse(fs.readFileSync(file, "utf-8"));
+    const entry = (parsed && typeof parsed.pollCount === "number") ? parsed : (parsed && parsed[convId]);
+    const now = Date.now();
+    if (entry && typeof entry.lastPollTime === "number" && (now - entry.lastPollTime) < STATE_TTL_MS) {
+      return entry;
     }
   } catch {}
   return { pollCount: 0, denials: 0, taskIds: [], lastPollTime: 0 };
@@ -86,14 +84,12 @@ function saveSessionState(convId = "global", entry) {
     let toWrite;
     if (!convId || convId === "global") {
       let state = {};
-      if (fs.existsSync(file)) {
-        try {
-          const parsed = JSON.parse(fs.readFileSync(file, "utf-8"));
-          if (parsed && typeof parsed === "object" && typeof parsed.pollCount !== "number") {
-            state = parsed;
-          }
-        } catch {}
-      }
+      try {
+        const parsed = JSON.parse(fs.readFileSync(file, "utf-8"));
+        if (parsed && typeof parsed === "object" && typeof parsed.pollCount !== "number") {
+          state = parsed;
+        }
+      } catch {}
       state[convId] = entry;
 
       // Prune stale entries
@@ -123,12 +119,7 @@ function saveSessionState(convId = "global", entry) {
  */
 function isProtectedInternalState(targetPath) {
   if (!targetPath || typeof targetPath !== "string") return false;
-  const normalized = targetPath.replace(/\\/g, "/");
-  return (
-    normalized.includes("/.system_generated/") ||
-    normalized.endsWith("/.system_generated") ||
-    /\.system_generated(?:$|[\/\\])/i.test(normalized)
-  );
+  return /\.system_generated(?:$|[\/\\])/i.test(targetPath);
 }
 
 /**
@@ -184,31 +175,124 @@ function isProtectedBenchmarkPath(targetPath) {
   );
 }
 
-let resolvedRtkPath = null;
-function getRtkBinary() {
-  if (resolvedRtkPath) return resolvedRtkPath;
+/**
+ * Checks if target path references runtime step output spillover file.
+ */
+function isStepSpilloverPath(targetPath) {
+  if (!targetPath || typeof targetPath !== "string") return false;
+  if (!isProtectedInternalState(targetPath)) return false; // cheap precheck
+  const normalized = targetPath.replace(/\\/g, "/");
+  return (
+    /\.system_generated[/\\]steps[/\\]\d+[/\\]output\.txt/i.test(normalized) ||
+    (normalized.includes("/.system_generated/steps/") && normalized.endsWith("output.txt"))
+  );
+}
 
-  // 1. Try global rtk on PATH
+/**
+ * Extracts the task-log reference from a target path or command, or null.
+ * Returns { id, token }: `id` is the bare task id; `token` is the matched path text
+ * (relative "tasks/task-1.log" or absolute ".../.system_generated/tasks/task-1.log").
+ */
+function getTaskLogMatch(text) {
+  if (!text || typeof text !== "string" || !text.includes(".log")) return null;
+  const normalized = text.replace(/\\/g, "/");
+  if (!normalized.includes("tasks/")) return null;
+  const m = normalized.match(/(?:^|[\s"'])((?:[^\s"']*\/)?tasks\/(?:task-)?([a-zA-Z0-9_-]+)\.log)/i);
+  if (!m) return null;
+  let token = m[1].replace(/^file:\/\//i, "");
+  if (/^\/[A-Za-z]:/.test(token)) token = token.slice(1);
+  return { id: m[2], token };
+}
+
+const TASK_TAIL_BYTES = 262144; // transcript tail scanned first (256 KB)
+const TASK_QUIET_MS = 300000;   // log-mtime fallback: quiet for 5 min => treated as finished
+
+function getBrainDir() {
+  return process.env.AGY_BRAIN_DIR || path.join(os.homedir(), ".gemini", "antigravity", "brain");
+}
+
+/** Reads the last `bytes` of a file. Returns { text, whole } or null. */
+function readTail(file, bytes) {
+  let fd;
   try {
-    const check = spawnSync("rtk", ["--version"], { timeout: 1000, windowsHide: true });
-    if (check.status === 0) {
-      resolvedRtkPath = "rtk";
-      return resolvedRtkPath;
+    fd = fs.openSync(file, "r");
+    const size = fs.fstatSync(fd).size;
+    const len = Math.min(size, bytes);
+    const buf = Buffer.alloc(len);
+    fs.readSync(fd, buf, 0, len, size - len);
+    return { text: buf.toString("utf-8"), whole: len === size };
+  } catch {
+    return null;
+  } finally {
+    if (fd !== undefined) { try { fs.closeSync(fd); } catch {} }
+  }
+}
+
+/**
+ * Looks for the finish / start notices of `taskName` in transcript text using literal needles
+ * (JSON-escaped and raw variants). Finish: `<conv>/task-N" finished with result`.
+ * Start: `<conv>/task-N` followed by a newline and "Task Description" or "Task logs".
+ * Returns "COMPLETED", "RUNNING" or null.
+ */
+function scanTaskMarkers(text, taskName) {
+  if (text.includes(`/${taskName}\\" finished`) || text.includes(`/${taskName}" finished`)) return "COMPLETED";
+  if (text.includes(`/${taskName}\\nTask `) || text.includes(`/${taskName}\nTask `)) return "RUNNING";
+  return null;
+}
+
+/**
+ * Resolves a background task's lifecycle state: "RUNNING", "COMPLETED" or "UNKNOWN".
+ * Authority order: transcript notices (tail first, full file only if needed), then log mtime.
+ */
+function getTaskState(match, convId) {
+  const taskName = `task-${match.id}`;
+  const token = match.token;
+  let logPath = null;
+  let transcript = null;
+
+  if (/^(?:[A-Za-z]:)?\//.test(token)) {
+    logPath = token;
+    const sysDir = path.posix.dirname(path.posix.dirname(token));
+    if (path.posix.basename(sysDir) === ".system_generated") transcript = `${sysDir}/logs/transcript.jsonl`;
+  }
+  if (convId && convId !== "global") {
+    const sysDir = path.join(getBrainDir(), convId, ".system_generated");
+    logPath = logPath || path.join(sysDir, "tasks", `${taskName}.log`);
+    transcript = transcript || path.join(sysDir, "logs", "transcript.jsonl");
+  }
+
+  if (transcript) {
+    const tail = readTail(transcript, TASK_TAIL_BYTES);
+    if (tail) {
+      let state = scanTaskMarkers(tail.text, taskName);
+      if (!state && !tail.whole) {
+        try { state = scanTaskMarkers(fs.readFileSync(transcript, "utf-8"), taskName); } catch {}
+      }
+      if (state) return state;
     }
-  } catch {}
+  }
 
-  // 2. Try plugin local bin
-  const isWin = os.platform() === "win32";
-  const exeName = isWin ? "rtk.exe" : "rtk";
-  const homeDir = os.homedir();
-  const pluginBin = path.join(homeDir, ".gemini", "config", "plugins", "agy-context-saver", "bin", exeName);
-  if (fs.existsSync(pluginBin)) {
-    resolvedRtkPath = pluginBin;
-    return resolvedRtkPath;
+  if (logPath) {
+    try {
+      return (Date.now() - fs.statSync(logPath).mtimeMs) > TASK_QUIET_MS ? "COMPLETED" : "RUNNING";
+    } catch {}
   }
+  return "UNKNOWN";
+}
 
-  resolvedRtkPath = "rtk";
-  return resolvedRtkPath;
+/**
+ * Runs `rtk rewrite <cmd>`. Spawns the PATH binary directly (a separate `--version` probe doubled
+ * the cost of every cache miss); falls back to the plugin-local binary only when PATH has none.
+ */
+function runRtkRewrite(cmd) {
+  const opts = { encoding: "utf-8", timeout: 2000, windowsHide: true };
+  const res = spawnSync("rtk", ["rewrite", cmd], opts);
+  if (res.error && res.error.code === "ENOENT") {
+    const exeName = os.platform() === "win32" ? "rtk.exe" : "rtk";
+    const pluginBin = path.join(os.homedir(), ".gemini", "config", "plugins", "agy-context-saver", "bin", exeName);
+    if (fs.existsSync(pluginBin)) return spawnSync(pluginBin, ["rewrite", cmd], opts);
+  }
+  return res;
 }
 
 const NON_REWRITABLE_BINARIES = new Set([
@@ -235,31 +319,39 @@ const REWRITE_CACHE_FILE = path.join(os.tmpdir(), "agy-rtk-rewrite-cache.json");
 const REWRITE_CACHE_MAX = 100;
 let inMemoryRewriteCache = null;
 
-function loadRewriteCache() {
-  if (inMemoryRewriteCache) return inMemoryRewriteCache;
+function readRewriteCacheFile() {
   try {
-    if (fs.existsSync(REWRITE_CACHE_FILE)) {
-      const data = JSON.parse(fs.readFileSync(REWRITE_CACHE_FILE, "utf-8"));
-      if (data && typeof data === "object") {
-        inMemoryRewriteCache = data;
-        return inMemoryRewriteCache;
-      }
-    }
+    const data = JSON.parse(fs.readFileSync(REWRITE_CACHE_FILE, "utf-8"));
+    if (data && typeof data === "object" && !Array.isArray(data)) return data;
   } catch {}
-  inMemoryRewriteCache = {};
+  return {};
+}
+
+function loadRewriteCache() {
+  if (!inMemoryRewriteCache) inMemoryRewriteCache = readRewriteCacheFile();
   return inMemoryRewriteCache;
 }
 
-function saveRewriteCache(cache) {
+/**
+ * Persists one rewrite result. Re-reads the file first so concurrent hook processes merge instead
+ * of overwriting each other, trims to the newest entries, and writes atomically (temp + rename).
+ */
+function rememberRewrite(cmd, rewritten) {
+  loadRewriteCache()[cmd] = rewritten;
   try {
-    const keys = Object.keys(cache);
-    let toSave = cache;
-    if (keys.length > REWRITE_CACHE_MAX) {
-      const slice = keys.slice(keys.length - REWRITE_CACHE_MAX);
-      toSave = {};
-      for (const k of slice) toSave[k] = cache[k];
+    const disk = readRewriteCacheFile();
+    delete disk[cmd];
+    disk[cmd] = rewritten;
+    const keys = Object.keys(disk);
+    for (const k of keys.slice(0, Math.max(0, keys.length - REWRITE_CACHE_MAX))) delete disk[k];
+    const tmp = `${REWRITE_CACHE_FILE}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(disk), "utf-8");
+    try {
+      fs.renameSync(tmp, REWRITE_CACHE_FILE);
+    } catch {
+      fs.writeFileSync(REWRITE_CACHE_FILE, JSON.stringify(disk), "utf-8");
+      try { fs.unlinkSync(tmp); } catch {}
     }
-    fs.writeFileSync(REWRITE_CACHE_FILE, JSON.stringify(toSave), "utf-8");
   } catch {}
 }
 
@@ -312,13 +404,12 @@ function rewriteCommandWithRtk(rawCmd) {
   }
 
   let rewritten = trimmed;
+  let cacheable = false;
   try {
-    const rtkBin = getRtkBinary();
-    const res = spawnSync(rtkBin, ["rewrite", trimmed], {
-      encoding: "utf-8",
-      timeout: 2000,
-      windowsHide: true
-    });
+    const res = runRtkRewrite(trimmed);
+    // Never cache timeouts, spawn errors or signals: a transient failure must not pin a command
+    // to "no rewrite" for the lifetime of the cache.
+    cacheable = !res.error && !res.signal && typeof res.status === "number" && res.status >= 0 && res.status <= 3;
 
     // RTK exits 0 or 3 when rewritten, with new command on stdout
     if ((res.status === 0 || res.status === 3) && res.stdout && res.stdout.trim()) {
@@ -326,8 +417,7 @@ function rewriteCommandWithRtk(rawCmd) {
     }
   } catch {}
 
-  cache[trimmed] = rewritten;
-  saveRewriteCache(cache);
+  if (cacheable) rememberRewrite(trimmed, rewritten);
   return rewritten;
 }
 
@@ -342,6 +432,34 @@ function getRequiredBackoffSeconds(pollCount) {
   return Math.min(600, Math.round(30 * Math.pow(2.5, Math.max(0, pollCount - 1))));
 }
 
+/**
+ * Denies reading the log of an actively RUNNING task: records the denial, trips the circuit
+ * breaker at 5 cumulative denials, otherwise answers with the Proportional Backoff message.
+ */
+function denyRunningTask(taskId, convId) {
+  const session = getSessionState(convId);
+  session.denials++;
+  saveSessionState(convId, session);
+
+  if (session.denials >= 5) {
+    respond({
+      decision: "force_ask",
+      reason: `[CIRCUIT BREAKER ACTIVATED] Autonomous loop suspended: reading task log '${taskId}' attempted prematurely ${session.denials} times during active backoff window. Stop calling tools and yield the turn for native Reactive Wakeup (<SYSTEM_MESSAGE>). User confirmation required to proceed.`
+    });
+  }
+
+  const requiredBackoffSec = Math.max(30, getRequiredBackoffSeconds(session.pollCount));
+  const requiredBackoffMs = requiredBackoffSec * 1000;
+  const elapsedMs = session.lastPollTime ? (Date.now() - session.lastPollTime) : Infinity;
+  const elapsedSec = Math.floor(elapsedMs / 1000);
+  const remainingSec = Math.max(1, Math.ceil((requiredBackoffMs - elapsedMs) / 1000));
+
+  respond({
+    decision: "deny",
+    reason: `Antigravity Execution Governance: Task '${taskId}' is actively RUNNING. Reading task logs in .system_generated during execution is strictly prohibited to prevent polling loops. Diagnostic check #${session.pollCount + 1} requires at least ${requiredBackoffSec}s elapsed (${elapsedSec}s elapsed, ${remainingSec}s remaining). Tasks execute asynchronously and notify you automatically via native Reactive Wakeup (<SYSTEM_MESSAGE>) upon completion. Stop calling tools and yield your turn now.`
+  });
+}
+
 // --- Main Hook Entrypoint ---
 let isGovernedTool = false;
 
@@ -389,8 +507,25 @@ try {
       });
     }
 
-    // LH-02-B: Direct shell access to internal Antigravity execution state (.system_generated)
-    if (isProtectedInternalState(rawCmd)) {
+    // LH-09-B: Shell command mutation of protected benchmark artifacts
+    if (
+      (rawCmd.includes(">") || /\b(?:rm|del|Remove-Item)\b/i.test(rawCmd)) &&
+      isProtectedBenchmarkPath(rawCmd)
+    ) {
+      respond({
+        decision: "force_ask",
+        reason:
+          "[BENCHMARK MUTATION DETECTED] Shell command mutation of protected evaluator/benchmark artifact requires explicit user confirmation to prevent benchmark contamination."
+      });
+    }
+
+    // Raw-command governance gates are pure string/fs checks: run them BEFORE the rtk rewrite
+    // spawn so denied commands never pay for a subprocess.
+    const isSpillover = isStepSpilloverPath(rawCmd);
+    const taskMatch = isSpillover ? null : getTaskLogMatch(rawCmd);
+
+    // Check 1: Other protected internal state (transcripts, scheduler, progress)
+    if (!isSpillover && !taskMatch && isProtectedInternalState(rawCmd)) {
       respond({
         decision: "deny",
         reason:
@@ -400,19 +535,35 @@ try {
       });
     }
 
-    // LH-09-B: Shell command mutation of protected benchmark artifacts
-    if (
-      (rawCmd.includes(">") || /\b(?:rm|del|Remove-Item)\b/i.test(rawCmd)) &&
-      isProtectedBenchmarkPath(rawCmd)
-    ) {
+    // Check 2: Task Log Inspection (Lifecycle-Gated, 0 New Tools): RUNNING => Proportional Backoff
+    if (taskMatch && getTaskState(taskMatch, convId) === "RUNNING") {
+      denyRunningTask(taskMatch.id, convId);
+    }
+
+    const rewritten = rewriteCommandWithRtk(rawCmd);
+    const effectiveCmd = rewritten;
+    const isRtkRead = /^rtk(?:\.exe)?\s+read\b/i.test(effectiveCmd);
+
+    // Check 3: Step Output Spillover Safe Harbor (rtk read only; it clamps + windows output)
+    if (isSpillover && !isRtkRead) {
       respond({
-        decision: "force_ask",
+        decision: "deny",
         reason:
-          "[BENCHMARK MUTATION DETECTED] Shell command mutation of protected evaluator/benchmark artifact requires explicit user confirmation to prevent benchmark contamination."
+          "Antigravity Execution Governance: Runtime step output spillover files must be inspected using 'rtk read <path>' via run_command to prevent context blowouts."
+      });
+    }
+
+    // Check 4: Terminated / unknown-state task log: allow only through rtk read
+    if (taskMatch && !isRtkRead) {
+      respond({
+        decision: "deny",
+        reason:
+          "Antigravity Execution Governance: Direct shell access to internal Antigravity execution state (.system_generated) is strictly prohibited to prevent transcript bloat and polling loops.\n" +
+          `- Once completed, inspect output using 'rtk read <path>' via run_command.\n` +
+          "- If actively running, yield execution turn and rely on native Reactive Wakeup (<SYSTEM_MESSAGE>)."
       });
     }
 
-    const rewritten = rewriteCommandWithRtk(rawCmd);
     const isDaemon = args.IsDaemon === true || args.isDaemon === true;
     const waitMs = args.WaitMsBeforeAsync !== undefined ? args.WaitMsBeforeAsync : args.waitMsBeforeAsync;
     const targetMaxWait = Number(process.env.AGY_MAX_WAIT_MS) || 10000;
@@ -456,7 +607,39 @@ try {
       "";
     const target = String(rawTarget).trim();
 
-    // 2a. Internal State Protection by Root (LH-02)
+    // 2a. Step Output Spillover Safe Harbor (hard-route to rtk read)
+    if (isStepSpilloverPath(target)) {
+      respond({
+        decision: "deny",
+        reason: `Antigravity Governance: Native file inspection via '${toolName}' bypasses token optimization. Run 'rtk read ${target}' via run_command instead.`
+      });
+    }
+
+    // 2b. Task Log Inspection (Lifecycle-Gated)
+    const taskMatch = getTaskLogMatch(target);
+    if (taskMatch) {
+      const state = getTaskState(taskMatch, convId);
+      if (state === "RUNNING") {
+        denyRunningTask(taskMatch.id, convId);
+      }
+
+      if (state === "COMPLETED") {
+        // If terminated / completed, route to rtk read:
+        respond({
+          decision: "deny",
+          reason: `Antigravity Governance: Native file inspection via '${toolName}' bypasses token optimization. Run 'rtk read ${target}' via run_command instead.`
+        });
+      }
+
+      // If not verified completed (or does not exist):
+      respond({
+        decision: "deny",
+        reason:
+          "Antigravity Execution Governance: Direct access to internal Antigravity execution state (.system_generated/tasks) is strictly prohibited to prevent polling loops. rely on native Reactive Wakeup (<SYSTEM_MESSAGE>) upon completion."
+      });
+    }
+
+    // 2c. Other Internal State Protection by Root (LH-02)
     if (isProtectedInternalState(target) || isProtectedInternalState(JSON.stringify(args))) {
       respond({
         decision: "deny",
@@ -467,7 +650,7 @@ try {
       });
     }
 
-    // 2b. Allow Antigravity Special Files (SKILL.md, brain artifacts, configs)
+    // 2d. Allow Antigravity Special Files (SKILL.md, brain artifacts, configs)
     if (isAntigravitySpecialFile(target)) {
       respond({ decision: "allow" });
     }

package/scripts/install-register.mjs

@@ -239,7 +239,7 @@ export async function runInstall(options = {}) {
   hooksConfig["execution-guard"] = {
     PreToolUse: [
       {
-        matcher: "manage_task|schedule|run_command|view_file|read_file|read_many_files|grep_search|find_by_name|list_dir",
+        matcher: "manage_task|schedule|run_command|view_file|read_file|read_many_files|grep_search|find_by_name|list_dir|replace_file_content|write_to_file",
         hooks: [
           {
             type: "command",
@@ -280,13 +280,21 @@ export async function runInstall(options = {}) {
   // 5. Mirror Antigravity Tool Schemas in parallel
   await fsPromises.mkdir(antigravityMcpDir, { recursive: true });
 
-  // Clean up legacy safe_command schema if present
-  const legacySafeCommandPath = path.join(antigravityMcpDir, "safe_command.json");
-  if (fs.existsSync(legacySafeCommandPath)) {
-    try {
-      await fsPromises.unlink(legacySafeCommandPath);
-      log(`[OK] Cleaned up legacy safe_command schema from: ${legacySafeCommandPath}`);
-    } catch {}
+  // Clean up retired schemas if present
+  const retiredSchemas = [
+    "safe_command.json",
+    "get_spillover_content.json",
+    "read_task_output.json",
+    "get_step_detail.json"
+  ];
+  for (const s of retiredSchemas) {
+    const sPath = path.join(antigravityMcpDir, s);
+    if (fs.existsSync(sPath)) {
+      try {
+        await fsPromises.unlink(sPath);
+        log(`[OK] Cleaned up retired schema from: ${sPath}`);
+      } catch {}
+    }
   }
 
   const instructionsContent = `# Agy-Context-Saver MCP Server Instructions
@@ -302,15 +310,17 @@ Agy-Context-Saver is the universal Model Context Protocol server and lifecycle g
 2. **Never Read Internal State Directly**:
    - Access to \`.system_generated/\` via \`view_file\` is strictly denied to prevent transcript explosion.
    - Use \`read_transcript\` or \`query_transcript\` to inspect conversation history cleanly.
-3. **Platform-Aware Codebase Inspection**:
+3. **Inspect Output Files Directly with RTK**:
+   - Runtime step output spillovers (\`.system_generated/steps/<step>/output.txt\`) and completed background task logs (\`tasks/<taskId>.log\`) are read directly via \`rtk read <path>\` under hook governance.
+4. **Platform-Aware Codebase Inspection**:
    - **Windows**: Use \`rtk read <file>\`, \`rtk find <path>\`, and \`rtk rg "<pattern>" .\` (the trailing \`.\` is required to avoid stdin stalls).
    - **POSIX**: Use \`rtk read <file>\`, \`rtk ls <path>\`, and \`rtk grep "<pattern>"\` or \`rtk rg "<pattern>"\`.
 
 ## Available MCP Tools
 - \`check_context_health\`: Diagnoses transcript turn counts, byte payload, and polling loops. Accepts \`transcriptPath\` or \`conversationId\`.
-- \`subagent_brief\`: Generates scope-isolated instructions for delegated subagents to prevent parent context bloat.
+- \`subagent_brief\`: Generates scope-isolated instructions for delegated subagents with Pointer-Over-Wire delivery contract.
 - \`read_transcript\`: Streams recent turns from \`transcript.jsonl\` or \`transcript_full.jsonl\` formatted as clean Markdown.
-- \`query_transcript\`: Forensic regex search and filtering engine across transcript steps with optional \`summaryOnly: true\`.
+- \`query_transcript\`: Forensic regex search and filtering engine across transcript steps with optional \`summaryOnly: true\`, and surgical step extraction via \`stepIndex\` and \`field\`.
 - \`get_installation_status\`: Audits live health of the plugin link, hook, MCP server, tool schemas, and RTK.
 - \`sync_installation\`: Synchronizes and repairs all 4 integration layers in ~25ms.
 
@@ -457,6 +467,14 @@ Agy-Context-Saver is the universal Model Context Protocol server and lifecycle g
         summaryOnly: {
           type: "boolean",
           description: "If true, returns high-density 1-line step summaries instead of full message blocks to minimize UI card height (default: false)."
+        },
+        stepIndex: {
+          type: "number",
+          description: "Optional step_index to surgically retrieve full un-truncated content for a single step from transcript_full.jsonl."
+        },
+        field: {
+          type: "string",
+          description: "Optional specific field to extract when stepIndex is provided (e.g. 'content', 'thinking', 'tool_calls', 'tool_args', or 'tool_args:Message'). Defaults to full step."
         }
       },
       required: ["conversationId"]