agy-context-saver 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -0,0 +1,72 @@
+# Changelog
+
+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.3.0] - 2026-10-07
+
+### Governance & Loophole Elimination
+- **Proportional Backoff Engine**: Eliminated the "Pendulum Freeze Trap" (where total bans on task polling caused hung/deadlocked background commands to run unmonitored forever) by implementing an exponential backoff curve ($0\text{s} \to 30\text{s} \to 75\text{s} \to 188\text{s} \to 469\text{s} \to 600\text{s}$). Tasks can be safely diagnosed when silent without enabling busy-waiting loops.
+- **Watchdog Timer Coordination**: Coordinated `schedule` watchdog timers with the active proportional backoff window. Timers shorter than the backoff cooldown are rejected with detailed feedback, while legitimate watchdog timers ($\ge 30\text{s}$) are permitted and auto-cancel via native Reactive Wakeup.
+- **Shell Wrapper Unwrapping (LH-01-B)**: Added recursive shell wrapper unwrapping (`cmd /c`, `powershell -Command`, `pwsh -c`, `bash -c`) inside `run_command` so wrapped commands are transparently rewritten to RTK equivalents instead of bypassing token optimization.
+- **Internal State Shell Guard (LH-02-B)**: Added strict shell command guards blocking direct shell access (`cat`, `Get-Content`, `type`) to internal Antigravity execution state (`.system_generated/`), routing transcript queries to MCP tools.
+- **Benchmark Shell Mutation Protection (LH-09-B)**: Extended benchmark and evaluator protections to shell redirect and removal operations (`>`, `rm`, `del`, `Remove-Item`), preventing benchmark tampering via the terminal.
+- **Single Source of Truth Ledger**: Authored comprehensive `LEDGER.md` tracking all 10 historical loopholes (LH-01 to LH-10), remnant escape routes, backoff mathematical formulas, and architectural invariants.
+
+---
+
+## [1.2.1] - 2026-10-07
+
+### Documentation & Developer Experience
+- **MCP Prompts Documentation**: Formally documented the `/mcp:agy-context-saver:context_shield` prompt across `README.md` and the documentation site, clarifying the operational difference between user slash commands (Prompts) and autonomous agent capabilities (Tools).
+- **Quickstart Optimization**: Repositioned the Quickstart installation block to the very top of `README.md` and `docs/index.md` for immediate onboarding.
+- **Zensical Docs Site Overhaul**: Added `context_shield` reference and tip callouts across `docs/index.md`, `docs/tools.md`, and `docs/governance.md`; updated navigation title to `Tools & Prompts`.
+- **Dynamic Test Assertions**: Updated installed MCP server verification test to dynamically synchronize with `package.json` version.
+
+---
+
+## [1.2.0] - 2026-10-07
+
+### Performance & Forensics
+- **Batch Full-Transcript Dereferencing**: Replaced sequential full-transcript scans with `batchFindFullSteps()`, reducing $N$-item dereferencing from $O(N)$ full-file passes down to a single streaming pass ($O(1)$) in 18.4ms.
+- **Sliding-Window Turn Retention**: Bounded transcript memory retention in `read_transcript` (`WINDOW_SIZE = Math.max(100, lastTurns * 15)`) with an early-stopping block formatter, parsing 2,000 steps in 21.8ms under 24 KB memory.
+- **Regex LRU Caching**: Added in-memory LRU cache (`regexCache`, capacity: 100) for query pattern compilation in `query_transcript`.
+- **Short-Circuit Field Search**: Converted transcript search to test fields sequentially (`content` $\to$ `thinking` $\to$ `tool_calls`), avoiding heavy string concatenations.
+- **Fast-Path Message Cleaning**: Added fast-path bypass in `cleanMessageContent` for strings $\le 120$ characters, eliminating redundant base64 regexes and newline splits.
+- **Static Rules In-Memory Cache**: Cached `rules/AGENTS.md` in memory with `mtimeMs` file stat invalidation, eliminating disk I/O on `resources/read` and `prompts/get`.
+
+### Execution Governor & Hook
+- **Fast-Path Builtin Bypass**: Added `NON_REWRITABLE_BINARIES` set (`node`, `powershell`, `pwsh`, `cmd`, `dir`, `echo`, `cd`, `del`, etc.) and PowerShell cmdlet prefixes to bypass `spawnSync("rtk")`, dropping execution latency from ~30ms to $< 0.05$ms.
+- **Persistent Command Rewrite LRU Cache**: Implemented persistent disk LRU cache (`agy-rtk-rewrite-cache.json` in `os.tmpdir()`) for rewritable commands, reducing repeat rewrite lookups to $< 0.1$ms.
+- **Session Ledger State Partitioning**: Partitioned session state by conversation ID (`agy-session-${safeId}.json`) to eliminate cross-session file contention.
+
+### Registration & Lifecycle
+- **Idempotent Config & Schema Synchronization**: Added `safeWriteFileIfChanged` and `safeCopyFileIfChanged` across all configuration (`hooks.json`, `mcp_config.json`) and MCP tool schemas (`~/.gemini/antigravity/mcp/agy-context-saver/`), eliminating disk churn during repeat syncs.
+- **RTK Provisioning Check Reuse**: Passed pre-detected RTK metadata to `ensureRtkInstalled()` to eliminate redundant `execSync` version checks during installation.
+
+### Security & Reliability
+- **Stdio Payload Safety Ceiling**: Added 10 MB payload guard (`MAX_STDIO_PAYLOAD_BYTES`) on the MCP stdio line reader, emitting standard JSON-RPC `-32600 Invalid Request` on oversized payloads.
+- **New Performance Verification Suite**: Added `tests/test-performance-probes.mjs` verifying batch dereferencing, sliding window bounds, stdio safety ceiling, and idempotent writes.
+
+---
+
+## [1.1.0] - 2026-10-07
+
+### Added
+- **Closed Execution Topology & Governance Invariants**: Comprehensive PreToolUse hook intercepting native inspection tools (`view_file`, `grep_search`, `list_dir`, `find_by_name`) and hard-routing them to RTK.
+- **Root-Based Antigravity State Protection**: Denied direct access to `.system_generated/` internal files to prevent transcript bloat and loop degradation.
+- **Session-Wide Lifecycle Ledger**: Non-resettable session task polling counter with Tier 3 `force_ask` circuit breaker at 5 denials.
+- **Evaluator & Benchmark Mutation Safeguard**: Gated mutation of evaluator or benchmark artifacts behind user confirmation.
+- **Platform-Aware Windows Routing**: Windows-native routing for `rtk rg "<pattern>" .` and `rtk find <path>` to eliminate stdin hangs.
+- **Universal MCP Server**: 6 core tools (`check_context_health`, `subagent_brief`, `get_installation_status`, `sync_installation`, `read_transcript`, `query_transcript`).
+
+---
+
+## [1.0.0] - 2026-10-07
+
+### Initial Release
+- Initial release of Agy-Context-Saver.
+- Antigravity Model Context Protocol (MCP) server.
+- Background task lifecycle governance and reactive wakeup enforcement.

package/README.md

@@ -13,6 +13,23 @@ It permanently eliminates session degradation, memory bloat, and context window
 
 ---
 
+## Quickstart (Instant Install)
+
+Install and synchronize the governor and RTK across your Antigravity environment:
+
+```bash
+# Fastest: one-line registration via npx
+npx agy-context-saver install
+
+# Or locally from this repository
+npm run setup
+
+# Audit health across all layers at any time
+npm run status
+```
+
+---
+
 ## Architectural Division of Responsibilities
 
 ```text
@@ -65,23 +82,6 @@ It permanently eliminates session degradation, memory bloat, and context window
 
 ---
 
-## Quickstart (Instant Install)
-
-Install and synchronize the governor and RTK across your Antigravity environment:
-
-```bash
-# Fastest: one-line registration via npx
-npx agy-context-saver install
-
-# Or locally from this repository
-npm run setup
-
-# Audit health across all layers at any time
-npm run status
-```
-
----
-
 ## Key Capabilities
 
 - **Transparent RTK Rewriting**: Native `run_command` calls are automatically rewritten (e.g. `pytest` $\to$ `rtk pytest`) via Antigravity PreToolUse hooks.
@@ -154,14 +154,17 @@ node tests/test-lifecycle-rollback.mjs
 
 ---
 
-## Available 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.
-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.
-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.
+## MCP Tools & Slash Commands
+
+* **User Slash Command (`/mcp:...`)**:
+  - `/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.
+  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.
+  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.
 
 ---
 

package/mcp/index.js

@@ -51,7 +51,7 @@ if (cliArg === "install" || cliArg === "--install") {
 
 function printHelp() {
   console.log(`
-Agy-Context-Saver 🛡️ (v1.2.0)
+Agy-Context-Saver 🛡️ (v1.2.1)
 Universal MCP Server & Lifecycle Governor for Google Antigravity (Powered by RTK)
 
 Usage:
@@ -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.2.0";
+const SERVER_VERSION = "1.3.0";
 
 // --- Tools Specification ---
 const TOOLS = [

package/package.json

@@ -1,41 +1,42 @@
-{
-  "name": "agy-context-saver",
-  "version": "1.2.0",
-  "description": "Universal Model Context Protocol (MCP) server & lifecycle governor purpose-built for Google Antigravity",
-  "main": "mcp/index.js",
-  "bin": {
-    "agy-context-saver": "mcp/index.js"
-  },
-  "type": "module",
-  "scripts": {
-    "start": "node mcp/index.js",
-    "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"
-  },
-  "keywords": [
-    "antigravity",
-    "mcp",
-    "model-context-protocol",
-    "gemini",
-    "context-window",
-    "lifecycle-hooks",
-    "agentic-coding"
-  ],
-  "files": [
-    "mcp",
-    "scripts",
-    "rules",
-    "skills",
-    "hooks.json",
-    "plugin.json",
-    "mcp_config.json",
-    "install.ps1",
-    "install.sh",
-    "README.md",
-    "LICENSE"
-  ],
-  "author": "paragon-ux",
-  "license": "MIT"
-}
+{
+  "name": "agy-context-saver",
+  "version": "1.3.0",
+  "description": "Universal Model Context Protocol (MCP) server & lifecycle governor purpose-built for Google Antigravity",
+  "main": "mcp/index.js",
+  "bin": {
+    "agy-context-saver": "mcp/index.js"
+  },
+  "type": "module",
+  "scripts": {
+    "start": "node mcp/index.js",
+    "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"
+  },
+  "keywords": [
+    "antigravity",
+    "mcp",
+    "model-context-protocol",
+    "gemini",
+    "context-window",
+    "lifecycle-hooks",
+    "agentic-coding"
+  ],
+  "files": [
+    "mcp",
+    "scripts",
+    "rules",
+    "skills",
+    "hooks.json",
+    "plugin.json",
+    "mcp_config.json",
+    "install.ps1",
+    "install.sh",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "author": "paragon-ux",
+  "license": "MIT"
+}

package/plugin.json

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

package/scripts/execution-guard-hook.mjs

@@ -276,6 +276,20 @@ function rewriteCommandWithRtk(rawCmd) {
     return trimmed;
   }
 
+  // Unwrap shell wrappers (e.g. cmd /c "...", powershell -Command "...", bash -c "...") (LH-01-B)
+  const shellWrapperMatch = trimmed.match(
+    /^(cmd(?:\.exe)?\s+\/[cC]|(?:powershell|pwsh)(?:\.exe)?\s+(?:-Command|-c)|(?:bash|sh)\s+-c)\s+["']?(.+?)["']?$/i
+  );
+  if (shellWrapperMatch) {
+    const wrapperPrefix = shellWrapperMatch[1];
+    const innerCmd = shellWrapperMatch[2].trim();
+    const rewrittenInner = rewriteCommandWithRtk(innerCmd);
+    if (rewrittenInner !== innerCmd) {
+      return `${wrapperPrefix} "${rewrittenInner}"`;
+    }
+    return trimmed;
+  }
+
   // Fast-path bypass for shell builtins, non-rewritable binaries, and powershell cmdlets
   const firstWord = (trimmed.match(/^[^\s"']+/)?.[0] || "").toLowerCase();
   if (
@@ -317,6 +331,17 @@ function rewriteCommandWithRtk(rawCmd) {
   return rewritten;
 }
 
+/**
+ * Calculates the required minimum cooldown interval (in seconds)
+ * proportional to the number of diagnostic status inspections already performed.
+ * Formula: Math.min(600, Math.round(30 * Math.pow(2.5, Math.max(0, pollCount - 1))))
+ * Levels: Level 0 -> 0s (baseline), Level 1 -> 30s, Level 2 -> 75s, Level 3 -> 188s, Level 4 -> 469s, Level 5+ -> 600s
+ */
+function getRequiredBackoffSeconds(pollCount) {
+  if (pollCount <= 0) return 0;
+  return Math.min(600, Math.round(30 * Math.pow(2.5, Math.max(0, pollCount - 1))));
+}
+
 // --- Main Hook Entrypoint ---
 let isGovernedTool = false;
 
@@ -364,6 +389,29 @@ try {
       });
     }
 
+    // LH-02-B: Direct shell access to internal Antigravity execution state (.system_generated)
+    if (isProtectedInternalState(rawCmd)) {
+      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" +
+          "- To inspect conversation transcripts: Call MCP tool read_transcript(conversationId=\"...\", mode=\"compact\") or query_transcript(...).\n" +
+          "- To inspect background tasks: Yield execution turn and rely on native Reactive Wakeup (<SYSTEM_MESSAGE>). Do not read internal task logs."
+      });
+    }
+
+    // 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."
+      });
+    }
+
     const rewritten = rewriteCommandWithRtk(rawCmd);
     const isDaemon = args.IsDaemon === true || args.isDaemon === true;
     const waitMs = args.WaitMsBeforeAsync !== undefined ? args.WaitMsBeforeAsync : args.waitMsBeforeAsync;
@@ -486,33 +534,43 @@ try {
       session.taskIds.push(taskId);
     }
 
-    // First inspection check in the session is permitted
-    if (session.pollCount === 0) {
-      session.pollCount = 1;
+    const now = Date.now();
+    const requiredBackoffSec = Math.max(30, getRequiredBackoffSeconds(session.pollCount));
+    const requiredBackoffMs = requiredBackoffSec * 1000;
+    const elapsedMs = session.lastPollTime ? (now - session.lastPollTime) : Infinity;
+    const elapsedSec = Math.floor(elapsedMs / 1000);
+
+    // Premature check before backoff interval has elapsed
+    if (elapsedMs < requiredBackoffMs) {
+      session.denials++;
       saveSessionState(convId, session);
-      respond({ decision: "allow" });
-    }
 
-    // Any subsequent polling checks in the session are strictly denied
-    session.denials++;
-    saveSessionState(convId, session);
+      if (session.denials >= 5) {
+        respond({
+          decision: "force_ask",
+          reason: `[CIRCUIT BREAKER ACTIVATED] Autonomous loop suspended: manage_task('${action}') called prematurely ${session.denials} times during active backoff window across tasks [${session.taskIds.join(", ")}]. Stop calling tools and yield the turn for native Reactive Wakeup (<SYSTEM_MESSAGE>). User confirmation required to proceed.`
+        });
+      }
 
-    if (session.denials >= 5) {
+      const remainingSec = Math.ceil((requiredBackoffMs - elapsedMs) / 1000);
       respond({
-        decision: "force_ask",
-        reason: `[CIRCUIT BREAKER ACTIVATED] Autonomous loop suspended: manage_task('${action}') has been denied ${session.denials} times across tasks [${session.taskIds.join(", ")}]. Stop calling tools and yield the turn for native Reactive Wakeup (<SYSTEM_MESSAGE>). User confirmation required to proceed.`
+        decision: "deny",
+        reason: `Antigravity Execution Governance: Proportional Backoff Active (Level ${session.pollCount}, ${session.denials} denial${session.denials > 1 ? "s" : ""}). Diagnostic check #${session.pollCount + 1} requires at least ${requiredBackoffSec}s elapsed since previous check (${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.`
       });
     }
 
-    respond({
-      decision: "deny",
-      reason: `Antigravity Execution Governance: Background task polling is prohibited (${session.denials} denial). Tasks execute asynchronously and notify you automatically via native Reactive Wakeup (<SYSTEM_MESSAGE>) upon completion. Stop calling tools and yield your turn now.`
-    });
+    // Backoff window satisfied! Allow diagnostic check and advance level:
+    session.pollCount++;
+    session.lastPollTime = now;
+    session.denials = 0;
+    saveSessionState(convId, session);
+    respond({ decision: "allow" });
   }
 
   if (toolName === "schedule") {
     const prompt = String(args.Prompt || args.prompt || "").replace(/^["']|["']$/g, "").trim().toLowerCase();
     const cond = String(args.TimerCondition || args.timerCondition || "").replace(/^["']|["']$/g, "").trim().toLowerCase();
+    const duration = Number(args.DurationSeconds || args.durationSeconds || args.duration || 0);
 
     const isTaskPoll =
       cond.startsWith("task-") ||
@@ -525,23 +583,30 @@ try {
       ((prompt.includes("check") || prompt.includes("status") || prompt.includes("poll") || prompt.includes("monitor") || prompt.includes("wait")) &&
        (prompt.includes("task") || prompt.includes("process") || prompt.includes("job") || prompt.includes("test") || prompt.includes("command") || prompt.includes("suite")));
 
-    // All polling timers are strictly denied regardless of duration (LH-03)
     if (isTaskPoll) {
       const session = getSessionState(convId);
-      session.denials++;
-      saveSessionState(convId, session);
+      const requiredBackoffSec = Math.max(30, getRequiredBackoffSeconds(session.pollCount));
+
+      // Task watchdog timers must be AT LEAST the required backoff window!
+      if (duration < requiredBackoffSec) {
+        session.denials++;
+        saveSessionState(convId, session);
+
+        if (session.denials >= 5) {
+          respond({
+            decision: "force_ask",
+            reason: `[CIRCUIT BREAKER ACTIVATED] Autonomous loop suspended: schedule polling timer has been denied ${session.denials} times. Background tasks notify you automatically upon completion. User confirmation required to proceed.`
+          });
+        }
 
-      if (session.denials >= 5) {
         respond({
-          decision: "force_ask",
-          reason: `[CIRCUIT BREAKER ACTIVATED] Autonomous loop suspended: schedule polling timer has been denied ${session.denials} times. Background tasks notify you automatically upon completion. User confirmation required to proceed.`
+          decision: "deny",
+          reason: `Antigravity Execution Governance: Task watchdog timer duration too short (${duration}s, ${session.denials} denial${session.denials > 1 ? "s" : ""}). Under Proportional Backoff (Level ${session.pollCount}), watchdog timer must be at least ${requiredBackoffSec}s. Tasks notify you automatically via native Reactive Wakeup (<SYSTEM_MESSAGE>). Stop calling tools and yield the turn instead.`
         });
       }
 
-      respond({
-        decision: "deny",
-        reason: "Antigravity Execution Governance: Scheduling timers to poll or monitor background tasks is prohibited regardless of duration. Background tasks notify you automatically via native Reactive Wakeup (<SYSTEM_MESSAGE>). Stop calling tools and yield the turn instead."
-      });
+      // If duration >= requiredBackoffSec, watchdog timer is permitted!
+      respond({ decision: "allow" });
     }
 
     // Non-polling timers (e.g. user-requested reminders) are allowed