agy-context-saver 1.2.1 → 1.3.2

package/CHANGELOG.md

@@ -5,6 +5,37 @@ 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.2] - 2026-10-07
+
+### Governance & Command Semantics (LH-11 Hardening)
+- **Opt-In Fail-Fast Semantics**: Reverted forced `-x -q` parameter injection on bare test runner invocations to preserve native command semantics. Fail-fast (`-x`, `--maxfail=1`) remains strictly opt-in, preventing the "whack-a-mole" repair loop and preserving complete failure blast radius visibility across multi-module test suites.
+- **Architectural Separation**: Replaced forced command mutation with the **Coordinated Watchdog Protocol** and **Mandatory Pre-Yield Status Cards** in `rules/AGENTS.md`, ensuring visibility during multi-minute full-repository sweeps without distorting test results.
+- **Loophole Ledger Synchronization**: Updated `LEDGER.md` (LH-11) documenting the trade-offs of fail-fast injection vs native command semantics.
+
+---
+
+## [1.3.1] - 2026-10-07
+
+### Governance & Asynchronous Execution Observability (LH-11)
+- **Fail-Fast Auto-Injection on Bare Test Sweeps**: `execution-guard-hook.mjs` transparently normalizes bare `pytest` and `python -m pytest` invocations to include `-x -q` (fail-fast, quiet mode). In large codebases (e.g. 900+ tests), this prevents multi-minute unconstrained sweeps by stopping execution immediately at the first failure.
+- **Coordinated Watchdog Protocol Codification**: Updated `rules/AGENTS.md` to explicitly train agents on the Coordinated Watchdog Protocol: when launching heavy background operations ($> 15\text{s}$), agents must schedule a coordinated watchdog timer (`schedule(DurationSeconds=45, ...)`) to prevent silent yielding into unmonitored execution black holes.
+- **Mandatory Pre-Yield Status Cards**: Codified in `rules/AGENTS.md` that agents launching background tasks must output a structured markdown status card (command, scope, estimated duration, watchdog tier) before yielding their turn, eliminating user uncertainty during prolonged runs.
+- **Loophole Ledger LH-11 Addition**: Formally documented LH-11 (Silent Background Deadlock & Bare Sweep Exhaustion) from Incident `07b0f8d8` in `LEDGER.md`.
+
+---
+
+## [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.2";
 
 // --- 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.2",
+  "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/rules/AGENTS.md

@@ -6,11 +6,27 @@
 
 ---
 
-## Layer 1: Background Tasks & Polling Ban (Reactive Wakeup SSOT)
-- **Zero-Tolerance on Task Polling**: Do NOT call `manage_task(Action='status')` or `schedule` timers in a loop to wait for running background tasks. Background tasks execute asynchronously and automatically resume the agent via **Reactive Wakeup** (`<SYSTEM_MESSAGE>`).
-- **Yield Turn Immediately**: When a process moves to the background, stop calling tools, output a concise status message, and yield the turn.
-- **No Keyword or Timer Exemptions**: Words like "debug", "timeout", "diagnose", or "stuck" do NOT exempt an agent from lifecycle governance. Timers with `duration >= 120` are NOT exempt.
-- **Circuit Breaker**: Repeated polling calls across any tasks in a session trigger an escalating circuit breaker. At 5 cumulative denials, autonomous execution is frozen via `force_ask`.
+## Layer 1: Background Tasks & Proportional Backoff Protocol (Reactive Wakeup SSOT)
+- **Zero-Tolerance on Busy-Polling**: Do NOT call `manage_task(Action='status')` in tight loops or schedule rapid timers to wait for running background tasks. Background tasks execute asynchronously and automatically resume the agent via **Reactive Wakeup** (`<SYSTEM_MESSAGE>`).
+- **Proportional Backoff Protocol**: Diagnostic inspections scale along an exponential backoff curve:
+  $\text{Cooldown} = \min(600, \text{round}(30 \times 2.5^{\text{pollCount} - 1})) \quad [0\text{s} \to 30\text{s} \to 75\text{s} \to 188\text{s} \to 469\text{s} \to 600\text{s}]$
+  - Check #1 (Immediate upon launch): Permitted ($0\text{s}$).
+  - Premature status checks within an active backoff window are denied. 5 consecutive premature checks trigger the `force_ask` circuit breaker.
+  - Silent/hung background tasks: Once the backoff window elapses, a single diagnostic check is permitted to inspect logs, detect deadlocks, and issue `manage_task(Action='kill')` if needed.
+- **Coordinated Watchdog Protocol (`schedule`)**: For long-running operations (builds, migrations, test suites) expected to take $> 15\text{s}$:
+  - Schedule a coordinated watchdog timer: `schedule(DurationSeconds=45, Prompt="Check status of background task-X", TimerCondition="task-X")`.
+  - Watchdog timers must satisfy `DurationSeconds >= Math.max(30, requiredBackoffSec)`. Short timers are denied.
+  - If the task completes early, Reactive Wakeup auto-cancels the timer and resumes the agent immediately.
+  - If the task is still running when the watchdog fires, perform a legal diagnostic check (`manage_task(status)`) and post a live progress update in chat for the user.
+- **Mandatory Pre-Yield Status Card**: When a command moves to the background, NEVER yield with a silent or generic one-liner. Output a structured Markdown card so the user is never left wondering if the IDE has stalled:
+  ```markdown
+  ### ⏳ Background Execution Started
+  - **Command**: `<cmd>`
+  - **Scope / Target**: `<scope>`
+  - **Estimated Duration**: `~X minutes`
+  - **Watchdog Active**: Coordinated check scheduled in 45s via Reactive Wakeup.
+  ```
+- **Kill & Stdin Immediate Exemption**: `manage_task(Action='kill')` and `manage_task(Action='send_input')` are ALWAYS permitted immediately ($0\text{s}$ backoff, zero penalties).
 
 ---
 
@@ -34,7 +50,11 @@
 
 ## Layer 3: Synchronous Execution & Subagent Delegation
 - **Maximum Synchronous Window**: Non-daemon `run_command` calls are automatically set to `WaitMsBeforeAsync: 10000` to complete synchronously and prevent unnecessary background detachment.
-- **Targeted Test Execution**: Avoid massive multi-minute test sweeps in interactive turns. Run targeted, quiet, fail-fast commands (e.g. `pytest tests/test_core.py -q -x`).
+- **Targeted Test Execution & Opt-In Fail-Fast (LH-11)**:
+  - **Targeted Invocations**: In interactive turns, prefer targeting specific test files or directories (e.g. `pytest tests/test_core.py`) rather than running full multi-minute repository sweeps.
+  - **Fail-Fast Flags are Opt-In**: Fail-fast flags (`-x`, `--maxfail=1`) are opt-in. Use them when quickly debugging a localized failure, but omit them when assessing the full blast radius across the codebase to avoid the "whack-a-mole" loop.
+  - **Coordinated Watchdog Mandatory for Full Sweeps**: When running full multi-minute test sweeps without `-x`, agents **MUST** pair execution with the **Coordinated Watchdog Protocol** (`schedule(DurationSeconds=45, ...)`) and output a **Pre-Yield Status Card**. Never yield silently.
+  - **Subagent Delegation for Deep Audits**: When a comprehensive repository-wide test audit is required, delegate the sweep to a subagent (`invoke_subagent`) to keep the main thread responsive.
 - **Subagent Delegation**: Delegate heavy multi-file exploration and exploratory research to subagents (`invoke_subagent`). Subagents absorb intermediate steps and return high-signal summaries.
 - **Benchmark / Evaluator Integrity**: Never mutate benchmark definitions, prompt templates, or scoring artifacts during an active evaluation without explicit user confirmation.
 

package/scripts/execution-guard-hook.mjs

@@ -276,7 +276,21 @@ function rewriteCommandWithRtk(rawCmd) {
     return trimmed;
   }
 
-  // Fast-path bypass for shell builtins, non-rewritable binaries, and powershell cmdlets
+  // 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 (
     NON_REWRITABLE_BINARIES.has(firstWord) ||
@@ -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