agy-context-saver 1.5.0 → 1.6.0

package/CHANGELOG.md

@@ -5,6 +5,36 @@ 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.6.0] - 2026-10-12
+
+### Added
+- **Full Cycle Product Development (FCPD) Strategic Roadmap**: Published `docs/roadmap.md` establishing a phased product architecture grounded in FCPD methodology: MVP hardening (shipped in v1.6.0), public validation & bug triage loop, and Antigravity ecosystem scale.
+- **Multi-Role Subagent Batching & Pointer-Over-Wire (POW)**: Added turnkey multi-agent batch configuration in `subagent_brief` (`subagents` array) with per-agent role, model, and workspace customizability. Validated across single-subagent, multi-role, and error-recovery trials (`tests/test-subagent-trials.mjs`).
+- **Comprehensive MCP Tool, Prompt & CLI Reference**: Authored an exhaustive handbook in `docs/tools.md` detailing all 6 canonical MCP tools with parameter tables, concrete JSON-RPC payloads, sample outputs, forensic search walkthroughs, and diagnostic triage playbooks.
+- **Labeled Diagnostic Telemetry**: Refined `check_context_health` with explicit labeled sections (`[Active Session Metrics]` vs. `[Local RTK Environment]`), eliminating metric ambiguity between active conversation byte weight and machine-wide cumulative `rtk gain` host tokens.
+
+### Changed
+- **Broadened Multi-Agent Positioning**: Shifted documentation and positioning from a narrow coding focus to affordable, reliable multi-agent workflows across general tasks (development, deep research, operations, analysis, and document drafting).
+- **Subagent Brief Schema Freeze**: Formally froze `subagent_brief` as a lightweight ergonomic utility adhering strictly to YAGNI principles; rejected feature creep (finding ledgers, citation judges, blinding switches).
+- **Zensical Documentation Navigation**: Registered `docs/roadmap.md` in navigation and validated zero dead anchors across the entire documentation site (`zensical build`).
+- **Release-Readiness & Hero Positioning**: Elevated Pointer-Over-Wire (POW) and the Enterprise Non-Destructive Guarantee to landing hero sections, added the flagship before/after comparison table to `README.md`, unified the 3-Layer Governance taxonomy, and completed 100% parameter tables in `docs/tools.md`.
+
+### Security, Installer Hardening & Hermetic CI
+- **Strict Read-Only `--check` & CLI Flag Validation (`scripts/install-register.mjs`, `mcp/index.js`, `install.ps1`)**: Hoisted `--check` pre-flight validation ahead of all filesystem and network operations, added fail-closed `parseAndValidateJsonConfig()` checks on existing `hooks.json` and `mcp_config.json` before any writes or `--check` success returns, and rejected conflicting read-only + mutating CLI flags (`--check --restore-backups`, `--check --uninstall`, `--check --status`) with exit code `1`.
+- **Windows `install.ps1` Wrapper Safety (`install.ps1`)**: Reordered `install.ps1` to execute `scripts/install-register.mjs` validation **before** writing `node.cmd`, added automatic backup (`.bak`) for pre-existing unmanaged `node.cmd` wrappers, and added clean wrapper removal/restoration during `--uninstall`.
+- **RTK Supply-Chain SHA-256 Verification & Semver Pinning (`scripts/provision-rtk.mjs`, `scripts/execution-guard-hook.mjs`)**: Pinned RTK provisioning to `v0.51.0` with precomputed SHA-256 archive digest verification across all 5 supported OS/arch targets, enforced strict `[>=0.50.0 <0.52.0]` runtime compatibility without bypasses, and updated `execution-guard-hook.mjs` (`resolveCompatibleRtk()`) to fall back to the compatible local binary path when `PATH` contains an incompatible RTK version.
+- **10-Suite Hermetic Test Matrix & Cross-OS CI (`tests/helpers/hermetic-fixture.mjs`, `.github/workflows/ci-matrix.yml`)**: Expanded automated verification from 8 to 10 hermetic test suites (`test-check-only-readonly.mjs`, `test-malformed-config-preservation.mjs`, and shared `setupHermeticTestEnv()` fixtures) running with zero host-profile mutation across Ubuntu, macOS, and Windows on Node.js 22 and 24.
+- **Release Engineering & Governance Policies (`scripts/release-preflight.mjs`, `.github/workflows/release-tag.yml`)**: Added non-destructive release preflight validation, tag-gated npm Trusted Publishing (`--provenance`), and repository governance policies (`SECURITY.md`, `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `docs/INSTALLER-HARDENING.md`, `docs/RTK-SUPPORT-MATRIX.md`).
+
+## [1.5.1] - 2026-10-11
+
+### Added
+- **Bounded Slice Safe Harbor for `view_file`**: Added support for bounded line slice inspection (`StartLine` & `EndLine` $\le 150$ lines) directly in `execution-guard-hook.mjs`. Enables surgical, token-efficient code inspections (e.g. reviewing specific function bodies, classes, or test spans) natively without triggering hook denials or requiring subagents to fall back to custom Node.js reading scripts.
+
+### Changed
+- **Anti-Gaming Inspection Guidance**: Preserved the original denial message (`Run 'rtk read <file>' via run_command instead`) for standard unbounded `view_file` calls with zero slice advertisement, preventing LLM agents from systematically gaming the system with synthetic line slices to bypass RTK. Oversized slice guidance is surfaced only when the caller explicitly attempts an inspection exceeding 150 lines.
+- **Root Protection Integrity**: Maintained absolute root-level denial on internal execution state (`.system_generated/`) ahead of the slice safe harbor, ensuring bounded ranges cannot be used to inspect raw transcripts or active task logs.
+
 ## [1.5.0] - 2026-10-08
 
 ### Performance & Memory Optimizations
@@ -123,3 +153,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Initial release of Agy-Context-Saver.
 - Antigravity Model Context Protocol (MCP) server.
 - Background task lifecycle governance and reactive wakeup enforcement.
+
+[1.6.0]: https://github.com/paragon-ux/agy-context-saver/compare/v1.5.1...v1.6.0
+[1.5.1]: https://github.com/paragon-ux/agy-context-saver/compare/v1.5.0...v1.5.1
+[1.5.0]: https://github.com/paragon-ux/agy-context-saver/compare/v1.4.0...v1.5.0
+[1.4.0]: https://github.com/paragon-ux/agy-context-saver/compare/v1.3.2...v1.4.0
+[1.3.2]: https://github.com/paragon-ux/agy-context-saver/compare/v1.3.1...v1.3.2
+[1.3.1]: https://github.com/paragon-ux/agy-context-saver/compare/v1.3.0...v1.3.1
+[1.3.0]: https://github.com/paragon-ux/agy-context-saver/compare/v1.2.1...v1.3.0
+[1.2.1]: https://github.com/paragon-ux/agy-context-saver/compare/v1.2.0...v1.2.1
+[1.2.0]: https://github.com/paragon-ux/agy-context-saver/compare/v1.1.0...v1.2.0
+[1.1.0]: https://github.com/paragon-ux/agy-context-saver/compare/v1.0.0...v1.1.0
+[1.0.0]: https://github.com/paragon-ux/agy-context-saver/releases/tag/v1.0.0

package/README.md

@@ -13,6 +13,29 @@ It permanently eliminates session degradation, memory bloat, and context window
 
 ---
 
+## Core Value Proposition
+
+| Metric / Capability | Without Governor | With Agy-Context-Saver + RTK |
+| :--- | :--- | :--- |
+| **Command Output Bloat** | Unlimited raw test dots, ANSI dumps | RTK transparent reduction (60–90% token savings) |
+| **Workspace File Inspection** | Massive uncompressed view_file dumps | Compact `rtk read`, `rtk grep`, `rtk find` |
+| **Long Command Execution** | Detached after 5s $\to$ busy-wait loop | Synchronous window expanded to 10s $\to$ finishes in-turn |
+| **Background Task Monitoring** | Repetitive busy-polling loops | Enforced Reactive Wakeup with 5-strike circuit breaker |
+| **Subagent Delegation** | In-band truncated >16KB JSON dumps | Pointer-Over-Wire (POW) protocols via `subagent_brief` |
+| **Configuration Safety** | Risk of third-party config clobber | Non-destructive preservation of foreign hooks/MCP with `.bak` backups |
+| **Transcript Review** | Raw JSONL dumped into context | Clean human-readable Markdown via `read_transcript` |
+| **Runtime Dependencies** | N/A | **Zero** external npm dependencies (100% Node.js stdlib) + native RTK binary |
+
+---
+
+## Canonical 3-Layer Governance Architecture
+
+1. **Layer 1: Reactive Lifecycle & Polling Immunity**: Replaces destructive busy-polling loops with native Antigravity **Reactive Wakeup**, governed by an exponential Proportional Backoff curve and a 5-strike circuit breaker.
+2. **Layer 2: Transparent CLI & Codebase Streamlining**: Intercepts shell execution via PreToolUse hooks, transparently rewriting commands to RTK (`rtk git`, `rtk pytest`), hard-routing workspace searches to `rtk read`/`find`/`rg`, and shielding internal `.system_generated` state.
+3. **Layer 3: Orchestration, Delegation & Pointer-Over-Wire (POW)**: Expands synchronous execution windows to 10s and enforces Pointer-Over-Wire contracts across subagent teams (`subagent_brief`).
+
+---
+
 ## Quickstart (Instant Install)
 
 Install and synchronize the governor and RTK across your Antigravity environment:
@@ -28,6 +51,9 @@ npm run setup
 npm run status
 ```
 
+> [!TIP]
+> **Enterprise Non-Destructive Guarantee**: Agy-Context-Saver requires **zero external npm dependencies** (100% native Node.js standard library), strictly preserves existing foreign hooks (e.g. `waymark-continuity`) and foreign MCP servers, automatically writes atomic `.bak` configuration backups, and supports clean 1-step rollback.
+
 ---
 
 ## Architectural Division of Responsibilities
@@ -79,12 +105,14 @@ npm run status
 2. **The Terminal Bloat Trap**: Routine test runs and git operations dump hundreds of lines of noise into context. RTK compresses these outputs natively before they enter model context.
 3. **The Raw Transcript Trap**: Reading `transcript.jsonl` dumps megabytes of raw JSON into context. Agy blocks direct reads of `.system_generated` and provides high-density Markdown streaming tools.
 4. **Native Inspection Bypass**: Native inspection tools (`view_file`, `grep_search`, `find_by_name`, `list_dir`) bypass token reduction. Agy hard-routes workspace inspection to RTK's canonical CLI (`rtk read`, `rtk grep`, `rtk find`, `rtk ls`).
+5. **The Subagent Truncation Trap**: When subagents return massive audits or code in-band over `send_message`, payloads exceed transport limits (~16 KB) and pollute parent context. Agy enforces **Pointer-Over-Wire (POW)**: subagents dump detailed reports to disk and transmit only high-signal summaries and clickable links.
 
 ---
 
 ## Key Capabilities
 
 - **Transparent RTK Rewriting**: Native `run_command` calls are automatically rewritten (e.g. `pytest` $\to$ `rtk pytest`) via Antigravity PreToolUse hooks.
+- **Pointer-Over-Wire (POW) Subagent Architecture**: Equips `subagent_brief` payloads with isolated workspaces and file-pointer reporting, eliminating context pollution and message truncation during multi-agent workflows.
 - **Canonical Codebase Inspection**:
   - `rtk read <file>`: Read file with intelligent token filtering and line ranges.
   - `rtk find <path>`: Compact file search tree and directory listing (cross-platform, works on Windows & POSIX).
@@ -111,8 +139,9 @@ For complete technical references, architectural specifications, and governance
 - 🏗️ **[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.
+- 🔬 **[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.
+- 🗺️ **[Product Roadmap](docs/roadmap.md)**: Phased strategic roadmap focusing on affordable and reliable multi-agent workflows across general tasks.
 
 ---
 
@@ -146,7 +175,7 @@ node mcp/index.js status
 ```bash
 npm test
 ```
-*Runs all 7 test suites (hook governance, MCP protocol, output inspection governance, E2E probes, performance probes, installed verification, lifecycle rollback).*
+*Runs all 10 test suites (hook governance, MCP protocol, output inspection governance, E2E probes, performance probes, installed verification, lifecycle rollback, subagent delegation trials, check-only read-only safety, and malformed configuration preservation).*
 
 ### 3. Run Targeted Tests Individually
 ```bash
@@ -170,6 +199,15 @@ node tests/test-installed-verification.mjs
 
 # Clean install/uninstall/restore lifecycle test
 node tests/test-lifecycle-rollback.mjs
+
+# Subagent delegation trials & batching
+node tests/test-subagent-trials.mjs
+
+# Check-only read-only isolation regression test
+node tests/test-check-only-readonly.mjs
+
+# Malformed config preservation fail-closed regression test
+node tests/test-malformed-config-preservation.mjs
 ```
 
 ### 4. Test MCP Tools from Antigravity Agent

package/assets/logo.svg

@@ -0,0 +1,51 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128" width="128" height="128">
+  <defs>
+    <linearGradient id="shieldGrad" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#4F46E5" />
+      <stop offset="50%" stop-color="#7C3AED" />
+      <stop offset="100%" stop-color="#2563EB" />
+    </linearGradient>
+    <linearGradient id="coreGrad" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#38BDF8" />
+      <stop offset="100%" stop-color="#818CF8" />
+    </linearGradient>
+    <filter id="glow" x="-20%" y="-20%" width="140%" height="140%">
+      <feDropShadow dx="0" dy="2" stdDeviation="4" flood-color="#4F46E5" flood-opacity="0.35" />
+    </filter>
+  </defs>
+
+  <!-- Outer Shield Outline -->
+  <path d="M 64 12 C 86 24 104 28 108 30 C 108 64 96 98 64 116 C 32 98 20 64 20 30 C 24 28 42 24 64 12 Z" 
+        fill="none" 
+        stroke="url(#shieldGrad)" 
+        stroke-width="5" 
+        stroke-linejoin="round"
+        filter="url(#glow)" />
+
+  <!-- Inner Protective Plate -->
+  <path d="M 64 22 C 82 32 94 35 98 37 C 98 65 88 92 64 106 C 40 92 30 65 30 37 C 34 35 46 32 64 22 Z" 
+        fill="url(#shieldGrad)" 
+        fill-opacity="0.12" 
+        stroke="url(#coreGrad)" 
+        stroke-width="2.5" 
+        stroke-linejoin="round" />
+
+  <!-- Dynamic Energy Node / Context Saver Symbol -->
+  <!-- Central Pulse Ring -->
+  <circle cx="64" cy="62" r="14" fill="none" stroke="url(#coreGrad)" stroke-width="3" stroke-dasharray="4 3" />
+  
+  <!-- Central Shield Core Dot -->
+  <circle cx="64" cy="62" r="6" fill="url(#coreGrad)" />
+
+  <!-- Synapse Rings (Context Boundary Links) -->
+  <line x1="64" y1="36" x2="64" y2="48" stroke="#38BDF8" stroke-width="3" stroke-linecap="round" />
+  <line x1="64" y1="76" x2="64" y2="88" stroke="#38BDF8" stroke-width="3" stroke-linecap="round" />
+  <line x1="42" y1="62" x2="50" y2="62" stroke="#818CF8" stroke-width="3" stroke-linecap="round" />
+  <line x1="78" y1="62" x2="86" y2="62" stroke="#818CF8" stroke-width="3" stroke-linecap="round" />
+
+  <!-- Node Dots -->
+  <circle cx="64" cy="34" r="3.5" fill="#38BDF8" />
+  <circle cx="64" cy="90" r="3.5" fill="#38BDF8" />
+  <circle cx="40" cy="62" r="3.5" fill="#818CF8" />
+  <circle cx="88" cy="62" r="3.5" fill="#818CF8" />
+</svg>

package/install.ps1

@@ -1,42 +1,86 @@
-# Agy-Context-Saver Universal Installer for Windows
-# Installs hook script, wrapper, and registers in ~/.gemini/config/hooks.json & mcp_config.json
-
-$ErrorActionPreference = "Stop"
-
-$GeminiConfigDir = [System.IO.Path]::Combine($env:USERPROFILE, ".gemini", "config")
-$DestHook = [System.IO.Path]::Combine($GeminiConfigDir, "scripts", "execution-guard-hook.mjs")
-
-# 1. Ensure ~/.gemini/config exists
-if (-not (Test-Path $GeminiConfigDir)) {
-    New-Item -ItemType Directory -Path $GeminiConfigDir -Force | Out-Null
-}
-
-# 2. Create node.cmd wrapper in ~/.gemini/config (prevents Windows cmd quote issues)
-$NodeCmdPath = [System.IO.Path]::Combine($GeminiConfigDir, "node.cmd")
-$NodeCmdLines = @(
-    '@echo off',
-    'setlocal',
-    'set "ARGS=%*"',
-    '',
-    'echo %ARGS% | findstr /i "execution-guard" >nul',
-    'if %errorlevel% equ 0 (',
-    "    `"C:\Program Files\nodejs\node.exe`" `"$DestHook`"",
-    '    exit /b %errorlevel%',
-    ')',
-    '',
-    'echo %ARGS% | findstr /i "waymark" >nul',
-    'if %errorlevel% equ 0 (',
-    '    "C:\Program Files\nodejs\node.exe" "%USERPROFILE%\Desktop\Frameworks\Deepseek-Project\Waymark\scripts\hooks\waymark-compact-hook.mjs"',
-    '    exit /b %errorlevel%',
-    ')',
-    '',
-    'echo {"decision": "allow"}',
-    'exit /b 0'
-)
-$NodeCmdContent = $NodeCmdLines -join "`r`n"
-Set-Content -Path $NodeCmdPath -Value $NodeCmdContent -Encoding ASCII
-Write-Host "[OK] Node wrapper installed to: $NodeCmdPath" -ForegroundColor Green
-
-# 3. Run cross-platform registration engine
-$RegisterScript = [System.IO.Path]::Combine($PSScriptRoot, "scripts", "install-register.mjs")
-& node "$RegisterScript"
+# Agy-Context-Saver Universal Installer for Windows
+# Installs hook script, wrapper, and registers in ~/.gemini/config/hooks.json & mcp_config.json
+
+$ErrorActionPreference = "Stop"
+
+$ProfileRoot = if ($env:AGY_TEST_PROFILE_DIR) { $env:AGY_TEST_PROFILE_DIR } else { $env:USERPROFILE }
+$GeminiConfigDir = [System.IO.Path]::Combine($ProfileRoot, ".gemini", "config")
+$DestHook = [System.IO.Path]::Combine($GeminiConfigDir, "scripts", "execution-guard-hook.mjs")
+$NodeCmdPath = [System.IO.Path]::Combine($GeminiConfigDir, "node.cmd")
+$NodeCmdBakPath = [System.IO.Path]::Combine($GeminiConfigDir, "node.cmd.bak")
+
+# Dynamic Node executable resolution
+$NodeCmdObj = Get-Command node -ErrorAction SilentlyContinue
+if ($NodeCmdObj -and $NodeCmdObj.Source) {
+    $NodeExe = $NodeCmdObj.Source
+} elseif (Test-Path "C:\Program Files\nodejs\node.exe") {
+    $NodeExe = "C:\Program Files\nodejs\node.exe"
+} else {
+    $NodeExe = "node"
+}
+
+# 1. Run cross-platform registration engine FIRST (validates config & provisions RTK before any wrapper write)
+$RegisterScript = [System.IO.Path]::Combine($PSScriptRoot, "scripts", "install-register.mjs")
+& $NodeExe "$RegisterScript" @args
+$RegExitCode = $LASTEXITCODE
+if ($RegExitCode -ne 0) {
+    exit $RegExitCode
+}
+
+$IsReadOnly = $args -contains "--check" -or $args -contains "-c" -or $args -contains "--status" -or $args -contains "status" -or $args -contains "--help" -or $args -contains "-h" -or $args -contains "help"
+$IsUninstall = $args -contains "--uninstall" -or $args -contains "uninstall"
+$IsRestoreOnly = ($args -contains "--restore-backups" -or $args -contains "restore-backups") -and (-not $IsUninstall)
+
+if ($IsUninstall) {
+    if (Test-Path $NodeCmdPath) {
+        $ExistingContent = Get-Content -Path $NodeCmdPath -Raw -ErrorAction SilentlyContinue
+        if ($ExistingContent -match "agy-context-saver-managed") {
+            Remove-Item -Path $NodeCmdPath -Force -ErrorAction SilentlyContinue
+            if (Test-Path $NodeCmdBakPath) {
+                Copy-Item -Path $NodeCmdBakPath -Destination $NodeCmdPath -Force
+                Write-Host "[OK] Restored previous node.cmd from backup: $NodeCmdBakPath" -ForegroundColor Green
+            } else {
+                Write-Host "[OK] Removed managed node.cmd wrapper: $NodeCmdPath" -ForegroundColor Green
+            }
+        }
+    }
+    exit 0
+}
+
+if (-not $IsReadOnly -and -not $IsRestoreOnly) {
+    # 2. Ensure ~/.gemini/config exists after preflight/registration succeeded
+    if (-not (Test-Path $GeminiConfigDir)) {
+        New-Item -ItemType Directory -Path $GeminiConfigDir -Force | Out-Null
+    }
+
+    # Preserve any pre-existing unmanaged node.cmd wrapper
+    if (Test-Path $NodeCmdPath) {
+        $ExistingWrapper = Get-Content -Path $NodeCmdPath -Raw -ErrorAction SilentlyContinue
+        if ($ExistingWrapper -and ($ExistingWrapper -notmatch "agy-context-saver-managed") -and (-not (Test-Path $NodeCmdBakPath))) {
+            Copy-Item -Path $NodeCmdPath -Destination $NodeCmdBakPath -Force
+            Write-Host "[OK] Backed up existing node.cmd to: $NodeCmdBakPath" -ForegroundColor Green
+        }
+    }
+
+    # 3. Create managed node.cmd wrapper in ~/.gemini/config (delegates non-governor calls to real node.exe)
+    $NodeCmdLines = @(
+        '@echo off',
+        'REM agy-context-saver-managed',
+        'setlocal',
+        'set "ARGS=%*"',
+        '',
+        'echo %ARGS% | findstr /i "execution-guard" >nul',
+        'if %errorlevel% equ 0 (',
+        "    `"$NodeExe`" `"$DestHook`"",
+        '    exit /b %errorlevel%',
+        ')',
+        '',
+        "`"$NodeExe`" %*",
+        'exit /b %errorlevel%'
+    )
+    $NodeCmdContent = $NodeCmdLines -join "`r`n"
+    Set-Content -Path $NodeCmdPath -Value $NodeCmdContent -Encoding ASCII
+    Write-Host "[OK] Node wrapper installed to: $NodeCmdPath" -ForegroundColor Green
+}
+
+exit 0

package/mcp/index.js

@@ -28,30 +28,51 @@ import os from "node:os";
 import path from "node:path";
 import readline from "node:readline";
 import { fileURLToPath } from "node:url";
-import { runInstall, runUninstall, runStatus, detectExistingInstallation } from "../scripts/install-register.mjs";
+import { runInstall, runUninstall, runStatus, runRestoreBackups, detectExistingInstallation } from "../scripts/install-register.mjs";
 import { findExistingRtk } from "../scripts/provision-rtk.mjs";
 
 // Handle CLI subcommands (e.g. npx agy-context-saver install)
-const cliArg = process.argv[2];
-const checkFlag = process.argv.includes("--check") || process.argv.includes("-c");
-if (cliArg === "install" || cliArg === "--install") {
-  await runInstall({ checkOnly: checkFlag });
+const cliArgs = process.argv.slice(2);
+const cliArg = cliArgs[0];
+const checkFlag = cliArgs.includes("--check") || cliArgs.includes("-c");
+const statusFlag = cliArgs.includes("--status") || cliArgs.includes("status");
+const uninstallFlag = cliArgs.includes("--uninstall") || cliArgs.includes("uninstall");
+const restoreFlag = cliArgs.includes("--restore-backups") || cliArgs.includes("restore-backups");
+const helpFlag = cliArgs.includes("--help") || cliArgs.includes("-h") || cliArgs.includes("help");
+const allowDegraded = cliArgs.includes("--allow-degraded");
+
+if (helpFlag) {
+  printHelp();
   process.exit(0);
-} else if (cliArg === "uninstall" || cliArg === "--uninstall") {
-  const restoreBackups = process.argv.includes("--restore-backups");
-  await runUninstall({ restoreBackups });
+}
+if ((checkFlag || statusFlag) && (uninstallFlag || restoreFlag)) {
+  console.error("Error: Read-only flags (--check, --status) cannot be combined with mutating flags (--uninstall, --restore-backups).");
+  process.exit(1);
+}
+if (checkFlag && statusFlag) {
+  console.error("Error: Conflicting flags: specify either --check or --status, not both.");
+  process.exit(1);
+}
+if (checkFlag) {
+  await runInstall({ checkOnly: true, allowDegraded });
   process.exit(0);
-} else if (cliArg === "status" || cliArg === "--status") {
+} else if (statusFlag) {
   runStatus();
   process.exit(0);
-} else if (cliArg === "--help" || cliArg === "-h" || cliArg === "help") {
-  printHelp();
+} else if (uninstallFlag) {
+  await runUninstall({ restoreBackups: restoreFlag });
+  process.exit(0);
+} else if (restoreFlag) {
+  await runRestoreBackups();
+  process.exit(0);
+} else if (cliArg === "install" || cliArg === "--install") {
+  await runInstall({ allowDegraded });
   process.exit(0);
 }
 
 function printHelp() {
   console.log(`
-Agy-Context-Saver 🛡️ (v1.2.1)
+Agy-Context-Saver 🛡️ (v1.6.0)
 Universal MCP Server & Lifecycle Governor for Google Antigravity (Powered by RTK)
 
 Usage:
@@ -98,7 +119,7 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const rulesPath = path.resolve(__dirname, "../rules/AGENTS.md");
 
 const SERVER_NAME = "agy-context-saver";
-const SERVER_VERSION = "1.5.0";
+const SERVER_VERSION = "1.6.0";
 
 // --- Tools Specification ---
 const TOOLS = [
@@ -121,13 +142,21 @@ const TOOLS = [
   },
   {
     name: "subagent_brief",
-    description: "Generates a scope-isolated, anti-bloat prompt for invoking a subagent. Instructs the subagent to absorb all intermediate file reads/searches and return only high-signal findings.",
+    description: "Generates scope-isolated, anti-bloat prompts and ready-to-use invoke_subagent JSON payloads for single or multiple delegated subagents. Instructs subagents to absorb intermediate file reads/searches and return only high-signal findings.",
     inputSchema: {
       type: "object",
       properties: {
         objective: {
           type: "string",
-          description: "The core research or investigative objective."
+          description: "The core research or investigative objective (for single subagent)."
+        },
+        role: {
+          type: "string",
+          description: "2-5 word role description (e.g. 'Comprehensive Test Engineer', 'Codebase Security Auditor'). Defaults to 'Scope-Isolated Deep Research Subagent'."
+        },
+        instructions: {
+          type: "string",
+          description: "Optional step-by-step instructions or specialized directives."
         },
         scopeFiles: {
           type: "array",
@@ -137,9 +166,40 @@ const TOOLS = [
         expectedDeliverable: {
           type: "string",
           description: "The concise format expected back by the parent agent."
+        },
+        typeName: {
+          type: "string",
+          description: "Subagent type name: 'self' (default, inherits parent tools/prompt/model) or 'research' (read-only)."
+        },
+        model: {
+          type: "string",
+          enum: ["inherit", "flash_lite", "flash", "pro"],
+          description: "Model tier: 'inherit' (default), 'flash_lite', 'flash', or 'pro'."
+        },
+        workspace: {
+          type: "string",
+          enum: ["inherit", "branch", "share"],
+          description: "Workspace isolation: 'inherit' (default), 'branch', or 'share'."
+        },
+        subagents: {
+          type: "array",
+          description: "Optional array of subagent configurations to formulate multiple subagents at once.",
+          items: {
+            type: "object",
+            properties: {
+              role: { type: "string", description: "2-5 word role description." },
+              objective: { type: "string", description: "The core objective for this subagent." },
+              instructions: { type: "string", description: "Optional step-by-step instructions." },
+              scopeFiles: { type: "array", items: { type: "string" }, description: "Files/directories to investigate." },
+              expectedDeliverable: { type: "string", description: "Expected deliverable format." },
+              typeName: { type: "string", description: "Subagent type name: 'self' or 'research'." },
+              model: { type: "string", enum: ["inherit", "flash_lite", "flash", "pro"], description: "Model tier." },
+              workspace: { type: "string", enum: ["inherit", "branch", "share"], description: "Workspace isolation." }
+            },
+            required: ["objective"]
+          }
         }
-      },
-      required: ["objective"]
+      }
     }
   },
   {
@@ -365,19 +425,25 @@ async function handleCheckContextHealth(args = {}) {
     const rtkInfo = findExistingRtk();
     const reportLines = [
       `### Context Health Report: ${healthStatus}`,
+      "",
+      "#### [Active Session Metrics]",
       `- Total Steps: ${totalSteps}`,
       `- User Turns: ${userTurns}`,
       `- Assistant Responses: ${modelTurns}`,
       `- Tool Calls: ${toolCalls}`,
       `- Detected Busy-Polling Events: ${pollingEvents}`,
-      `- Approximate Raw Transcript Size: ${kb} KB`,
-      `- RTK Command Optimizer: ${rtkInfo ? `Active (${rtkInfo.version})` : "Missing (run sync_installation)"}`
+      `- Approximate Raw Transcript Size: ${kb} KB`
     ];
 
     if (corruptLines > 0) {
       reportLines.push(`- Corrupted/Unparsed Lines: ${corruptLines}`);
     }
 
+    reportLines.push("");
+    reportLines.push("#### [Local RTK Environment]");
+    reportLines.push(`- RTK Command Optimizer: ${rtkInfo ? `Active (${rtkInfo.version})` : "Missing (run sync_installation)"}`);
+    reportLines.push(`- Note: Lifetime token gains from 'rtk gain' represent cumulative machine-wide host savings, not single-session metrics.`);
+
     reportLines.push("");
     if (pollingEvents > 0) {
       reportLines.push("⚠️ Recommendation: Background polling detected! Cease manage_task(status) calls and yield execution to native Reactive Wakeup.");
@@ -397,11 +463,18 @@ async function handleCheckContextHealth(args = {}) {
   }
 }
 
-function handleSubagentBrief({ objective, scopeFiles = [], expectedDeliverable = "Synthesized factual findings" }) {
-  const scopeStr = scopeFiles.length ? `\n\nTarget files:\n${scopeFiles.map(f => `- ${f}`).join("\n")}` : "";
-  const prompt = [
-    `ROLE: Scope-Isolated Deep Research Subagent`,
-    `OBJECTIVE: ${objective}${scopeStr}`,
+function formatSingleBrief({
+  role = "Scope-Isolated Deep Research Subagent",
+  objective = "",
+  instructions = "",
+  scopeFiles = [],
+  expectedDeliverable = "Synthesized factual findings"
+} = {}) {
+  const scopeStr = scopeFiles && scopeFiles.length ? `\n\nTarget files:\n${scopeFiles.map(f => `- ${f}`).join("\n")}` : "";
+  const instrStr = instructions && instructions.trim() ? `\n\nSPECIFIC INSTRUCTIONS:\n${instructions.trim()}` : "";
+  return [
+    `ROLE: ${role}`,
+    `OBJECTIVE: ${objective}${scopeStr}${instrStr}`,
     ``,
     `CRITICAL CONTEXT GOVERNANCE INSTRUCTIONS (POINTER-OVER-WIRE):`,
     `1. Isolated Workspace: Do all necessary multi-file exploration, searches, and analysis in this subagent sandbox.`,
@@ -415,8 +488,71 @@ function handleSubagentBrief({ objective, scopeFiles = [], expectedDeliverable =
     `4. Format: ${expectedDeliverable}`,
     `5. Citation Mandate: Keep your final response concise, structured, and cite exact file:line references.`
   ].join("\n");
+}
+
+function handleSubagentBrief(args = {}) {
+  let specs = [];
+  if (Array.isArray(args.subagents) && args.subagents.length > 0) {
+    specs = args.subagents;
+  } else if (args.objective || args.role || args.instructions) {
+    specs = [args];
+  } else {
+    return {
+      isError: true,
+      content: [{ type: "text", text: "subagent_brief error: provide either 'objective' (for a single subagent) or 'subagents' array (for multiple subagents)." }]
+    };
+  }
+
+  const subagentsPayload = [];
+  const renderedBriefs = [];
+
+  for (let i = 0; i < specs.length; i++) {
+    const spec = specs[i] || {};
+    const role = spec.role || spec.Role || "Scope-Isolated Deep Research Subagent";
+    const objective = spec.objective || spec.Objective || "";
+    const instructions = spec.instructions || spec.Instructions || "";
+    const scopeFiles = spec.scopeFiles || spec.ScopeFiles || [];
+    const expectedDeliverable = spec.expectedDeliverable || spec.ExpectedDeliverable || "Synthesized factual findings";
+    const typeName = spec.typeName || spec.TypeName || "self";
+    const model = spec.model || spec.Model || "inherit";
+    const workspace = spec.workspace || spec.Workspace || "inherit";
+
+    const promptText = formatSingleBrief({
+      role,
+      objective,
+      instructions,
+      scopeFiles,
+      expectedDeliverable
+    });
 
-  return { content: [{ type: "text", text: prompt }] };
+    subagentsPayload.push({
+      TypeName: typeName,
+      Role: role,
+      Model: model,
+      Workspace: workspace,
+      Prompt: promptText
+    });
+
+    if (specs.length === 1) {
+      renderedBriefs.push(promptText);
+    } else {
+      renderedBriefs.push(`### Subagent ${i + 1}: ${role}\n${promptText}`);
+    }
+  }
+
+  const payloadJson = JSON.stringify({ Subagents: subagentsPayload }, null, 2);
+
+  const fullText = [
+    renderedBriefs.join("\n\n---\n\n"),
+    "",
+    "==================================================",
+    "READY-TO-USE invoke_subagent PAYLOAD:",
+    "```json",
+    payloadJson,
+    "```"
+  ].join("\n");
+
+  return { content: [{ type: "text", text: fullText }] };
 }
 
 function handleGetInstallationStatus() {
@@ -478,6 +614,14 @@ function extractConvId(p) {
 let cachedActiveConv = null;
 let cachedActiveConvTime = 0;
 
+function getProfileHomeDir() {
+  return process.env.AGY_TEST_PROFILE_DIR || os.homedir();
+}
+
+function getBrainDir() {
+  return process.env.AGY_BRAIN_DIR || path.join(getProfileHomeDir(), ".gemini", "antigravity", "brain");
+}
+
 function resolveTranscriptPath(target, mode = "compact") {
   const isFull = mode === "full";
   const fileName = isFull ? "transcript_full.jsonl" : "transcript.jsonl";
@@ -492,7 +636,7 @@ function resolveTranscriptPath(target, mode = "compact") {
       if (cachedActiveConv && (now - cachedActiveConvTime) < 5000) {
         raw = cachedActiveConv;
       } else {
-        const brainDir = path.join(os.homedir(), ".gemini", "antigravity", "brain");
+        const brainDir = getBrainDir();
         try {
           const entries = fs.readdirSync(brainDir, { withFileTypes: true });
           let bestMtime = 0;
@@ -544,14 +688,14 @@ function resolveTranscriptPath(target, mode = "compact") {
     }
   }
 
-  // 4. UUID / Directory resolution under ~/.gemini/antigravity/brain/<id>
-  const homeDir = os.homedir();
-  const brainCandidate = path.join(homeDir, ".gemini", "antigravity", "brain", normalized, ".system_generated", "logs", fileName);
+  // 4. UUID / Directory resolution under <brainDir>/<id>
+  const primaryBrainDir = getBrainDir();
+  const brainCandidate = path.join(primaryBrainDir, normalized, ".system_generated", "logs", fileName);
   if (fs.existsSync(brainCandidate)) {
     return { filePath: brainCandidate, convId: normalized };
   }
   if (isFull) {
-    const compactFallback = path.join(homeDir, ".gemini", "antigravity", "brain", normalized, ".system_generated", "logs", "transcript.jsonl");
+    const compactFallback = path.join(primaryBrainDir, normalized, ".system_generated", "logs", "transcript.jsonl");
     if (fs.existsSync(compactFallback)) {
       return { filePath: compactFallback, convId: normalized };
     }