agy-context-saver 1.7.0 → 1.8.1

package/CHANGELOG.md

@@ -5,6 +5,39 @@ 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.8.1] - 2026-10-16
+
+### Added
+- **Hybrid `view_file` Slice Governance (`scripts/execution-guard-hook.mjs`)**: Retains the 150-line default slice ceiling (`1–150` lines allowed; partial slices of `151–800` lines denied) while adding a guarded full-file audit exception: explicit `StartLine: 1, EndLine: <TotalFileLines>` reads are permitted when the file on disk is $\le 800$ lines and $\le 45\text{ KiB}$ (`46,080` bytes). `.system_generated/` protections continue to take unconditional precedence.
+- **Waymark-First Denial Routing**: When `waymark-engine` is installed, `view_file` hook denials now recommend `waymark_ask(..., plain: true)` across all 23 supported formats followed by a bounded `view_file(StartLine, EndLine)` slice, falling back to `rtk read` when Waymark is unavailable.
+
+### Changed
+- **Single-Source-of-Truth MCP Instructions (`scripts/install-register.mjs`)**: Replaced the hardcoded pre-v1.7 `instructions.md` template in `install-register.mjs` with a direct read of `mcp/instructions.md`, eliminating the split-brain discrepancy between repository docs and `~/.gemini/antigravity/mcp/agy-context-saver/instructions.md`.
+- **Unified 3-Tier Inspection Documentation**: Reconciled `README.md`, `mcp/instructions.md`, `rules/AGENTS.md`, `skills/context-governance/SKILL.md`, `mcp/index.js`, and `docs/*.md` around the 3-tier hierarchy (`waymark_ask(..., plain: true)` $\to$ hybrid `view_file` $\to$ `rtk` for spillovers, task logs, and directory/prose search) and standardized references to all 10 automated test files.
+
+### Fixed
+- **Inline `read_transcript` Payload Cap (`mcp/index.js`)**: Bounded `compact` mode transcript output to `3,800` characters (`< 4 KB`) and clamped intermediate non-dialogue step bodies so `read_transcript(mode: "compact")` never triggers an Antigravity host spillover file.
+- **Complete `query_transcript` Role Schema**: Documented `'subagent'` in the `roles` filter description across `mcp/index.js`, `scripts/install-register.mjs`, `skills/context-governance/SKILL.md`, and `docs/tools.md`.
+
+---
+
+## [1.8.0] - 2026-10-15
+
+### Removed
+- **`subagent_brief` moved to the separate [Agy-Squad](https://github.com/paragon-ux/agy-squad) package.** Agy-Context-Saver now exposes 5 MCP tools. Agy-Squad is under construction, and the two will install side by side. Removed with it: the tool schema, `tests/test-subagent-trials.mjs`, and the subagent delegation and Pointer-Over-Wire guidance in `rules/AGENTS.md`, `skills/context-governance/SKILL.md`, `mcp/instructions.md` and the docs.
+
+### Changed
+- **Hook state moved out of the shared temp folder.** The polling ledger and RTK rewrite cache now live in a per-user folder: `%LOCALAPPDATA%\agy-context-saver` on Windows, `$XDG_STATE_HOME/agy-context-saver` (default `~/.local/state/agy-context-saver`) elsewhere. Other users and processes on the machine can no longer read or tamper with them.
+- **Uninstall removes all hook state.** It deletes the state folder and any files older versions left in the temp folder (`agy-session-*.json`, `agy-rtk-rewrite-cache.json` and their temp files). Install removes those legacy temp files too. `test-lifecycle-rollback` seeds all of them and checks that they're removed, and that unrelated temp files are left alone.
+- **The installer retires stale subagent schemas.** Re-installing removes `subagent_brief.json` and `dispatch_squad.json` from `~/.gemini/antigravity/mcp/agy-context-saver/`. `test-lifecycle-rollback` seeds both and checks that they're removed.
+- **The `check_context_health` turn-budget warning** now recommends summarizing and continuing in a fresh conversation instead of delegating to subagents.
+
+### Fixed
+- **The MCP server exits when its parent goes away.** It exits on stdin end/close, on stdout `EPIPE`, and when its parent process is gone (15 s watchdog), so no orphaned server processes are left behind.
+- **`mcp/index.js` can be imported without side effects.** The CLI and the stdio loop run only when it's the entry point, and it exports `handleRequest`.
+
+---
+
 ## [1.7.0] - 2026-10-13
 
 ### Added

package/README.md

@@ -18,10 +18,9 @@ It permanently eliminates session degradation, memory bloat, and context window
 | 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` |
+| **Workspace File Inspection** | Massive uncompressed `view_file` dumps | `waymark_ask(..., plain: true)` $\to$ bounded `view_file` slices ($\le 150$ lines) + `rtk find` / `rtk rg` |
 | **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 |
@@ -31,8 +30,10 @@ It permanently eliminates session degradation, memory bloat, and context window
 ## 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`).
+2. **Layer 2: Transparent CLI & Codebase Streamlining**: Intercepts shell execution via PreToolUse hooks, transparently rewriting commands to RTK (`rtk git`, `rtk pytest`), enforcing bounded `view_file` slices paired with `waymark_ask(..., plain: true)`, routing spillovers/task logs to `rtk read` and directory/prose searches to `rtk find`/`rg`, and shielding internal `.system_generated` state.
+3. **Layer 3: Synchronous Execution**: Expands synchronous execution windows to 10s so routine commands finish in-turn instead of detaching.
+
+> **Subagent tools moved.** `subagent_brief` and squad dispatch now live in the separate [Agy-Squad](https://github.com/paragon-ux/agy-squad) package (under construction). Agy-Context-Saver is complete without them, and the two will install side by side.
 
 ---
 
@@ -54,6 +55,9 @@ 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.
 
+> [!NOTE]
+> **RTK Default Configuration Notice**: To protect agent context and command execution from unprompted marketing banners (`[rtk] /!\ No hook installed...`), `Agy-Context-Saver` standardizes `suppress_hook_warning = true` in RTK's user configuration (`%APPDATA%\rtk\config.toml` on Windows / `~/.config/rtk/config.toml` on POSIX) during installation. Existing user configurations are safely preserved. See [RTK Support Matrix](docs/RTK-SUPPORT-MATRIX.md#rtk-configuration-standardization--default-modifications).
+
 ---
 
 ## Architectural Division of Responsibilities
@@ -94,7 +98,6 @@ npm run status
 - Background task polling governance & 5-strike circuit breaker
 - Antigravity internal state protection (`.system_generated/`)
 - Zero-JSON Markdown transcript extraction (`read_transcript`, `query_transcript`)
-- Subagent delegation formulation (`subagent_brief`)
 - Benchmark and evaluation artifact mutation protection
 
 ---
@@ -104,26 +107,27 @@ npm run status
 1. **The Polling Trap**: When shell tasks detach to background jobs (`task-XYZ`), agents waste tokens repeatedly polling `manage_task(Action='status')` or scheduling artificial timers. Agy enforces native **Reactive Wakeup** (`<SYSTEM_MESSAGE>`).
 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.
+4. **Native Inspection Bypass**: Unbounded native inspection tools (`view_file` without slices, `grep_search`, `find_by_name`, `list_dir`) bypass token reduction. Agy enforces bounded `view_file` slices (`StartLine` / `EndLine <= 150`, paired with `waymark_ask(..., plain: true)`) and routes directory/prose search and spillover reads to RTK's canonical CLI (`rtk find`, `rtk rg`, `rtk grep`, `rtk read`).
 
 ---
 
 ## 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).
-  - Search by platform:
-    - **Windows**: `rtk rg "<pattern>" .` (explicit target `.` prevents child process stdin stalls) or `rg "<pattern>" .`.
-    - **POSIX / Linux / macOS**: `rtk grep "<pattern>"` or `rtk rg "<pattern>"`.
-  - Directory listing by platform:
-    - **Windows**: `rtk find <path>` or PowerShell `dir` / `Get-ChildItem`. (Avoid `rtk ls` / `rtk tree` on Windows as they rely on POSIX binaries/flags).
-    - **POSIX / Linux / macOS**: `rtk ls <path>` or `rtk tree`.
-  - `rtk err <cmd>`: Run command and show only errors/warnings.
-  - `rtk summary <cmd>`: Run command and produce a 2-line heuristic summary.
+- **Unified 3-Tier Codebase & File Inspection**:
+  1. **Tier 1 — Structural Discovery (`waymark_ask(..., plain: true)`)**: Locate exact `[StartLine, EndLine]` coordinates across all 23 supported formats (code ASTs + `markdown`, `yaml`, `json`, `toml`, `bash`) in ~19–466 tokens.
+  2. **Tier 2 — Precision Workspace Reading (`view_file` Hybrid Slice Policy)**: Pass `StartLine` and `EndLine` (`1–150` lines default; or explicit `StartLine: 1, EndLine: <TotalLines>` full-file audit when $\le 800$ lines and $\le 45\text{ KiB}$) into `view_file` to preserve 1-indexed line numbers for `replace_file_content` without terminal stdout truncation.
+  3. **Tier 3 — RTK CLI Boundaries**:
+     - `rtk read <path>`: Inspect runtime step spillovers (`.system_generated/steps/<step>/output.txt`) and completed background task logs (`tasks/<taskId>.log`) with `--head-lines` / `--tail-lines`.
+     - `rtk find <path>`: Compact file search tree and directory listing (cross-platform, works on Windows & POSIX).
+     - Prose / Regex Search (when symbol, heading, or config key is unknown):
+       - **Windows**: `rtk rg "<pattern>" .` (explicit target `.` prevents child process stdin stalls) or `rg "<pattern>" .`.
+       - **POSIX / Linux / macOS**: `rtk grep "<pattern>"` or `rtk rg "<pattern>"`.
+     - Directory listing by platform:
+       - **Windows**: `rtk find <path>` or PowerShell `dir` / `Get-ChildItem`. (Avoid `rtk ls` / `rtk tree` on Windows as they rely on POSIX binaries/flags).
+       - **POSIX / Linux / macOS**: `rtk ls <path>` or `rtk tree`.
+     - `rtk err <cmd>`: Run command and show only errors/warnings.
+     - `rtk summary <cmd>`: Run command and produce a 2-line heuristic summary.
 - **Antigravity Special Files Safe Harbor**: Direct `view_file` access to `SKILL.md`, brain artifacts, and config files is preserved.
 - **Protected Internal State**: Root-based guard prevents reading `.system_generated/` (transcripts, task logs, progress).
 - **Session-Wide Lifecycle Ledger**: Polling checks are tracked globally per session; changing task IDs or waiting does not reset governance.
@@ -138,8 +142,8 @@ For complete technical references, architectural specifications, and governance
 - 📖 **[Getting Started & Installation](docs/installation.md)**: Zero-delay setup, native plugin linking, hooks registration, and verification matrix.
 - 🏗️ **[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.
+- 🧰 **[MCP Tools & CLI Reference](docs/tools.md)**: Complete specifications for all 5 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, and post-mortem task retrieval.
 - 🚀 **[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.
 
@@ -175,11 +179,11 @@ node mcp/index.js status
 ```bash
 npm test
 ```
-*Runs all 11 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, malformed configuration preservation, and Waymark dual-MCP synergy).*
+*Runs all 10 test suites (hook governance, MCP protocol, output inspection governance, E2E probes, performance probes, installed verification, lifecycle rollback, check-only read-only safety, malformed configuration preservation, and RTK ledger fresh install verification).*
 
 ### 3. Run Targeted Tests Individually
 ```bash
-# Governance hook unit tests (28 closed-topology tests)
+# Governance hook unit tests (27 closed-topology tests)
 node tests/test-hook.mjs
 
 # MCP server protocol & method tests
@@ -200,17 +204,14 @@ 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
 
-# Dual-MCP Waymark code intelligence + subagent synergy suite
-node tests/test-waymark-synergy.mjs
+# RTK ledger & fresh install verification test
+node tests/test-rtk-ledger-fresh-install.mjs
 ```
 
 ### 4. Test MCP Tools from Antigravity Agent
@@ -218,7 +219,6 @@ node tests/test-waymark-synergy.mjs
 - `check_context_health`: Call with `{ "transcriptPath": "<path-to-transcript.jsonl>" }`.
 - `read_transcript`: Call with `{ "conversationId": "<uuid>", "lastTurns": 3, "mode": "compact" }`.
 - `query_transcript`: Call with `{ "conversationId": "<uuid>", "query": "<term>", "summaryOnly": true }`.
-- `subagent_brief`: Call with `{ "objective": "<goal>", "scopeFiles": ["..."] }`.
 
 ### 5. Testing Pitfalls & Anti-Patterns to Avoid
 - ❌ **Do NOT run `npm start` or `node mcp/index.js` interactively**: It starts the stdio JSON-RPC daemon and waits indefinitely on `stdin`.
@@ -234,11 +234,10 @@ node tests/test-waymark-synergy.mjs
   - `/mcp:agy-context-saver:context_shield`: Injects 3-layer governance rules and RTK standards into any session with one click. *(MCP Prompts appear in your chat autocomplete menu; MCP Tools are called autonomously by the agent).*
 * **Agent MCP Tools**:
   1. `check_context_health`: Diagnoses conversation transcript turn budgets, payload size, RTK status, and polling loops.
-  2. `subagent_brief`: Formulates scope-isolated prompts for delegated subagents with Pointer-Over-Wire (POW) delivery contract.
-  3. `read_transcript`: Reads recent conversation history in clean Markdown format (compact/full).
-  4. `query_transcript`: Forensic filtering, regex search engine, and surgical single-step dereferencing (`stepIndex`, `field`) from full transcripts.
-  5. `get_installation_status`: Inspects live Antigravity plugin link, hook, MCP server, tool schemas, and RTK binary.
-  6. `sync_installation`: Re-verifies and repairs all integration layers in ~25ms.
+  2. `read_transcript`: Reads recent conversation history in clean Markdown format (compact/full).
+  3. `query_transcript`: Forensic filtering, regex search engine, and surgical single-step dereferencing (`stepIndex`, `field`) from full transcripts.
+  4. `get_installation_status`: Inspects live Antigravity plugin link, hook, MCP server, tool schemas, and RTK binary.
+  5. `sync_installation`: Re-verifies and repairs all integration layers in ~25ms.
 
 * **Streamlined Output Inspection (0 New Tools)**:
   - **Runtime Step Spillovers** (`.system_generated/steps/<step>/output.txt`): Inspected via canonical `rtk read <path>` (safe-harbored in the PreToolUse hook; native `view_file` calls automatically route to `rtk read`).