agy-context-saver 1.2.1 → 1.3.0

package/CHANGELOG.md

@@ -5,6 +5,18 @@ 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

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.2.1";
+const SERVER_VERSION = "1.3.0";
 
 // --- Tools Specification ---
 const TOOLS = [

package/package.json

@@ -1,42 +1,42 @@
-{
-  "name": "agy-context-saver",
-  "version": "1.2.1",
-  "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"
-}
+{
+  "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/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