agy-context-saver 1.4.0 → 1.6.0

package/CHANGELOG.md

@@ -5,6 +5,55 @@ 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
+- **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)
@@ -104,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](LEDGER_OUTPUT_FIXES.md)**: 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.
 
 ---
 
@@ -122,10 +151,10 @@ Build or serve the documentation locally using **Zensical**:
 
 ```bash
 # Build static documentation site
-py -3.11 -m zensical build
+zensical build
 
 # Serve live preview server
-py -3.11 -m zensical serve
+zensical serve
 ```
 
 ---
@@ -146,7 +175,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 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
@@ -156,14 +185,29 @@ 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
 
 # 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/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/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