agy-context-saver 1.8.1 → 2.0.1

package/CHANGELOG.md

@@ -5,6 +5,32 @@ 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).
 
+## [2.0.1] - 2026-11-15
+
+### Added
+- **Pinned `rtk v1.1.0` Release Checksums (`scripts/provision-rtk.mjs`, `tests/test-rtk-ledger-fresh-install.mjs`)**: Pinned verified SHA-256 digests from upstream `rtk v1.1.0` `checksums.txt` across all 5 supported platform archives (`win32-x64`, `darwin-arm64`, `darwin-x64`, `linux-x64`, `linux-arm64`) so clean installs without a pre-installed `rtk` binary can automatically download and verify `rtk v1.1.0` fail-closed.
+
+### Security
+- **Operation-Bound, Single-Invocation Capability Grants (`lib/transcript-core.mjs`, `bin/agy-context.mjs`, `scripts/execution-guard-hook.mjs`)**: Bound `verifyTranscriptCoreAccess()` to canonical subcommand (`read`, `query`, `step`, `health`, `list`) and recorded `targetConvId`, and cleared the in-memory `processVerifiedGrant` synchronously upon path resolution (before async stream I/O begins) and on any early error (`L39`) so grants cannot be reused within the same process, shared across concurrent `Promise.all` calls, or repurposed across mismatched subcommands or conversation targets.
+- **Independent `--file` Brain-Directory Containment (`lib/transcript-core.mjs`, `scripts/execution-guard-hook.mjs`)**: Enforced independent `isContainedInDir()` checks on `--file` (`explicitFile`) inside `resolveTranscriptPath()` (`<brainDir>/<callerConvId>` in `self-only` mode and `<brainDir>` whenever any parent access policy or first-line launch restriction is active) and updated `extractConvId()` to resolve conversation folder IDs relative to `getBrainDir()` (`L38`).
+
+### Changed
+- **Documentation & Release Hygiene (`README.md`, `SECURITY.md`, `docs/installation.md`, `docs/governance.md`, `docs/architecture.md`, `docs/plans/LEDGER.md`, `scripts/release-preflight.mjs`)**: Added a `v1.x` to `v2.0` migration note and explicit `RTK >= 1.1.0` prerequisite details to `README.md` (`L37`), clarified application-layer `PreToolUse`/CLI defense-in-depth boundaries vs. OS-kernel sandboxing and `--id` vs. `--file` containment rules (`L40`), and enforced `plugin.json` / `package.json` / `CHANGELOG.md` version parity in `scripts/release-preflight.mjs`.
+
+## [2.0.0] - 2026-11-14
+
+### Added
+- **CLI-First Transcript & Health Engine (`lib/transcript-core.mjs`, `bin/agy-context.mjs`)**: Extracted the streaming JSONL transcript engine into `lib/transcript-core.mjs` and exposed `agy-context` (`bin/agy-context.mjs`) with `transcript read|query|step|health|list|access` (plus intuitive aliases `outline`, `summary`, `grep`, `search`, `find`, `tools`, `stats`, `info`, `ls`, and `policy`) and `status|setup|uninstall|restore-backups` subcommands. Includes positional arguments (`read [<id>]`, `query <pattern> [<id>]`, `step <N|N,M|N-M|N..M> [<id>]`, `health [<id>]`), step head/tail slicing (`step --tail <N>`, `--head <N>`, `--full`), `read --outline`, `query --tools`, `query --full-args`, `--field <content|thinking|tool_calls|tool_args|tool_args:Key|all>`, $O(1)$ `CircularRingBuffer` bounded `lastTurns: 0` streaming, `mode: "auto"` full-log dereferencing for truncated search misses, structured `error` role telemetry, active swarm conversation disambiguation, and `fs.realpathSync` containment checks.
+- **On-Demand Parent Transcript Access Governance (`lib/transcript-core.mjs`, `scripts/execution-guard-hook.mjs`, `bin/agy-context.mjs`)**: Added parent transcript access control via `agy-context transcript access --status | --off (--deny-children) | --on (--reset) | --self-only | --mode <open|allowlist|self-only|deny> | --allow <id,@roster*...> | --deny <id,@roster*...> | --ttl <sec> | --json` (with `policy` alias and positional shorthands `status`, `off`, `on`, `reset`, `self-only`), first-line launch directives (`[agy-transcript-access: deny|self-only|allow]`) on `define_subagent` `SystemPrompt`, `invoke_subagent` `Prompt`, and `/swarm` worker `brief` with prompt-echo immunity in prose and code blocks, 5-tier precedence (`1. Policy Owner` -> `2. Explicit CLI --deny` -> `3. Explicit CLI --allow` supporting `@roster*` prefix globs -> `4. First-Line Launch Directive` -> `5. Cohort Default Mode`), and stale-lock protection (parent-keyed `policies[ownerId]` with 1h TTL, Step 0 `USER_INPUT` top-level session bypass, Step 0/1 `sender=<parentConvId>` child binding, and `Transcript Access Policy` visibility in `agy-context status`).
+- **Transcript Access & State Directory Security Hardening (`scripts/execution-guard-hook.mjs`, `lib/transcript-core.mjs`)**: Added single-use `PreToolUse` capability grants (`lastHookGrant` and `lastAccessMutationGrant`, 10s TTL) verified in `lib/transcript-core.mjs` to block direct `node bin/agy-context.mjs` or library-import bypasses, protected `getStateDir()` against file and shell reads/writes, added executable script and heredoc scanning (`node -e`, `python -c`, subshells), added context-aware `.system_generated` denials when transcript access is restricted, and wired blocked transcript probes into the 5-strike `force_ask` circuit breaker.
+- **RTK `>= 1.1.0` Contract Tests & Transcript Test Suite**: Added `tests/test-transcript.mjs` and `tests/test-rtk-integration.mjs` (11 total automated suites in `npm test`).
+
+### Changed
+- **RTK `>= 1.1.0` Native Hook Delegation (`scripts/provision-rtk.mjs`, `scripts/execution-guard-hook.mjs`)**: Upgraded minimum RTK version to `1.1.0`, delegated shell command rewriting to `rtk hook antigravity`, guarded absent `rg` and lossy implicit `wc`/`ls`/`diff` rewrites, removed legacy bespoke rewrite caches and `bash -c` regex wrappers, and applied `WaitMsBeforeAsync: 10000` only when `!isDaemon && waitMs === undefined`.
+- **Antigravity 2.0 Hook Policy & Shell Segment Isolation (`hooks.json`, `scripts/execution-guard-hook.mjs`)**: Standardized on single hook key `agy-context-saver` with relative CWD-safe `node ./scripts/execution-guard-hook.mjs`, added `edit_file` and `write_file` (`args.Path`) to `GOVERNED_TOOLS` and `LH-09` benchmark protection, applied `args.Path` Safe Harbor + Hybrid Slice symmetrically across `read_file` and `view_file`, enforced segment/quote/heredoc-aware parsing with strict unchained exemption for `rtk read <spillover>` and `agy-context transcript ...`, and injected canonical `--id <convId>` under `self-only` access policies.
+- **Default MCP Retirement & `mcp/` Removal (`scripts/install-register.mjs`)**: Removed `mcp/index.js` and `mcp/instructions.md` in favor of `bin/agy-context.mjs`, `rules/AGENTS.md`, and `skills/context-governance/SKILL.md`, retired default `mcp_config.json` registration, swept legacy `agy-context-saver*` MCP entries and duplicate `~/.gemini/antigravity/mcp/agy-context-saver*` schema folders during `setup`/`uninstall`, pruned global `hooks.json` duplicates, and installed `~/.gemini/antigravity/bin/agy-context` shims.
+- **Documentation & Governance Sync (`rules/AGENTS.md`, `skills/context-governance/SKILL.md`, `README.md`, `plugin.json`)**: Updated rules, skills, and README to Antigravity 2.0 `read_file` / `edit_file` / `write_file` tools and `agy-context` CLI commands, removing `waymark_ask` and `view_file` ghost instructions.
+
 ## [1.8.1] - 2026-10-16
 
 ### Added
@@ -43,7 +69,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 - **Subagent Artifact Directory Write Guard (`subagent_brief`)**: Added automated path analysis in `formatSingleBrief` that detects when an objective or instruction references a foreign `brain/<uuid>/` directory. Warns subagents proactively to prevent Antigravity's fatal `write_to_file` error ("files must reside within the designated artifact directory").
 - **Pointer-Over-Wire (POW) File Delivery Clarification**: Codified explicit two-option guidance for subagent deliverables:
-  - *Option A (Workspace `scratch/` — Recommended)*: Write to `<workspace>/scratch/<task>_findings.md` and omit `ArtifactMetadata`.
+  - *Option A (Workspace `scratch/`, Recommended)*: Write to `<workspace>/scratch/<task>_findings.md` and omit `ArtifactMetadata`.
   - *Option B (Own Brain `scratch/`)*: Write to `<your-Artifact-Directory-Path>/scratch/...` using the subagent's own `<user_information>` block and include `ArtifactMetadata: { Summary, UserFacing: false, RequestFeedback: false }`.
 - **Bounded Slice Reading Safe Harbor (`view_file`)**: Prioritized `view_file` with bounded slices (`StartLine` and `EndLine`, max 150 lines) over `rtk read` across `rules/AGENTS.md`, `skills/context-governance/SKILL.md`, and `mcp/instructions.md` to preserve exact 1-indexed line numbers without stdout buffer truncation.
 - **Subagent Delegation Trial 4 (`tests/test-subagent-trials.mjs`)**: Added automated trial verifying `subagent_brief` emits the artifact directory write guard, bounded slice guidance, and Option A/Option B file delivery rules.

package/README.md

@@ -1,249 +1,81 @@
-# Agy-Context-Saver 🛡️
-
-**Model Context Protocol (MCP) Server & Lifecycle Governor for Google Antigravity (Powered by RTK)**
+# Agy-Context-Saver
 
 [![npm version](https://img.shields.io/npm/v/agy-context-saver.svg)](https://www.npmjs.com/package/agy-context-saver)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Docs](https://img.shields.io/badge/docs-Zensical-purple.svg)](https://paragon-ux.github.io/agy-context-saver/)
 [![Tests](https://img.shields.io/badge/tests-100%25%20passing-brightgreen.svg)](https://github.com/paragon-ux/agy-context-saver/actions)
 
-`Agy-Context-Saver` is a high-performance lifecycle governor and zero-dependency MCP server purpose-built for **Google Antigravity** (`agy`), paired with **RTK (Rust Token Killer)** for transparent CLI output reduction.
-
-It permanently eliminates session degradation, memory bloat, and context window exhaustion caused by **background task busy-wait polling**, **uncompressed terminal outputs**, and **raw JSON transcript reading**.
+`Agy-Context-Saver` is a `PreToolUse` execution hook and transcript CLI (`agy-context`) for **Google Antigravity** (`agy`) on Linux, macOS, and Windows (`Node.js >= 22`, zero external npm dependencies). It pairs with **RTK (`>= 1.1.0`)** to compress shell output, bound workspace file reads, stop background-task busy-polling, and govern transcript inspection across parent sessions, subagents, and `/swarm` workers.
 
----
+![Agy-Context-Saver and RTK execution topology](assets/architecture-overview.svg)
 
-## 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 | `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 |
-| **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 |
+The repository ships four components:
 
----
+- **`PreToolUse` execution hook ([`hooks.json`](hooks.json), [`scripts/execution-guard-hook.mjs`](scripts/execution-guard-hook.mjs)):** Delegates `run_command` rewriting to `rtk hook antigravity`, requires bounded `read_file` line slices (`<= 150` lines, or explicit `1..TotalLines` reads on files `<= 800` lines and `<= 45 KiB`), upgrades unset `WaitMsBeforeAsync` to `10s`, enforces exponential backoff on `manage_task` and `schedule` with a 5-strike `force_ask` circuit breaker, and blocks direct file or shell access to `.system_generated/` and the state directory.
+- **Transcript forensics CLI ([`bin/agy-context.mjs`](bin/agy-context.mjs), [`lib/transcript-core.mjs`](lib/transcript-core.mjs)):** Streams conversation turns in Markdown, searches compact and full logs by regex or role, extracts single steps or step ranges with `--head`/`--tail` slicing, and audits session turn budgets (`read`, `query`, `step`, `health`, `list`, `access`).
+- **Parent transcript access control (`agy-context transcript access`):** Lets parent sessions restrict or scope child subagent and `/swarm` worker transcript access on demand (`open`, `allowlist`, `self-only`, `deny`) via CLI flags (`--off`, `--self-only`, `--allow @audit-squad*`) or first-line launch directives (`[agy-transcript-access: deny|self-only|allow]`), backed by 10-second single-use capability grants.
+- **Agent rules and skill ([`rules/AGENTS.md`](rules/AGENTS.md), [`skills/context-governance/SKILL.md`](skills/context-governance/SKILL.md)):** Installed into `~/.gemini/config/plugins/agy-context-saver` so Antigravity sessions inherit the inspection and Reactive Wakeup rules automatically. Multi-agent cohort planning and SHA-256 evidence bundling live in the companion [Agy-Squad](https://github.com/paragon-ux/agy-squad) repository.
 
-## Canonical 3-Layer Governance Architecture
+## Quickstart
 
-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`), 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.
+### Prerequisites
 
-> **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.
+- **Node.js:** `>= 22.0.0`
+- **Google Antigravity:** Antigravity 2.0+ (Desktop IDE or `agy` CLI)
+- **RTK:** `>= 1.1.0` (`brew install rtk`, `cargo install --locked rtk`, or downloaded automatically into `bin/` during `agy-context setup` with pinned SHA-256 verification)
 
----
-
-## Quickstart (Instant Install)
-
-Install and synchronize the governor and RTK across your Antigravity environment:
+### Install and verify
 
 ```bash
-# Fastest: one-line registration via npx
-npx agy-context-saver install
+# Install via npx
+npx --package=agy-context-saver agy-context setup
 
-# Or locally from this repository
+# Or from a local checkout
 npm run setup
 
-# Audit health across all layers at any time
-npm run status
+# Check installation and active policy status
+agy-context 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
-
-```text
-                         Antigravity Agent
-                                |
-             +------------------+------------------+
-             |                                     |
-        run_command                         native inspection /
-             |                              lifecycle tools
-             v                                     |
-        RTK hook                                    |
-             |                             +---------+----------+
-             v                             |                    |
-        RTK execution                  inspection tools      lifecycle
-             |                             |                    |
-             v                             v                    v
-     compact command output          Agy DENY + route      Agy governance
-                                           |                    |
-                                           v                    v
-                                      RTK read/grep/find     Agy MCP
-                                           |                    |
-                                           +---------+----------+
-                                                     |
-                                                     v
-                                              useful context
-```
-
-### RTK Owns:
-- Transparent `run_command` rewriting (`rtk rewrite`)
-- Shell command output reduction (`git`, `pytest`, `cargo`, `npm`, `docker`, etc.)
-- Canonical codebase inspection CLI (`rtk read`, `rtk grep`, `rtk find`, `rtk ls`, `rtk tree`)
-- Focused diagnostic utilities (`rtk err`, `rtk summary`)
-
-### Agy Owns:
-- Antigravity lifecycle management & Reactive Wakeup enforcement
-- Background task polling governance & 5-strike circuit breaker
-- Antigravity internal state protection (`.system_generated/`)
-- Zero-JSON Markdown transcript extraction (`read_transcript`, `query_transcript`)
-- Benchmark and evaluation artifact mutation protection
-
----
-
-## The Core Problems Solved
-
-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**: 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`).
-
----
+> **Upgrading from v1.x:** Running `agy-context setup` automatically removes legacy `mcp_config.json` entries, sweeps stale `~/.gemini/antigravity/mcp/agy-context-saver*` schema caches, and replaces the retired v1.x MCP server with the on-demand `agy-context` CLI and updated `PreToolUse` hook.
 
-## Key Capabilities
-
-- **Transparent RTK Rewriting**: Native `run_command` calls are automatically rewritten (e.g. `pytest` $\to$ `rtk pytest`) via Antigravity PreToolUse hooks.
-- **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.
-- **Zero-JSON Transcript Streaming**: Stream conversation turns without raw JSON syntax using `read_transcript` and `query_transcript`.
-
----
-
-## Comprehensive Documentation
-
-For complete technical references, architectural specifications, and governance rules, visit our **[Zensical Documentation Site](https://paragon-ux.github.io/agy-context-saver/)**:
-
-- 📖 **[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 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.
-
----
-
-## Local Documentation Server
-
-Build or serve the documentation locally using **Zensical**:
+To remove the plugin link, hook entries, and CLI shims:
 
 ```bash
-# Build static documentation site
-zensical build
-
-# Serve live preview server
-zensical serve
+agy-context uninstall
+# Or restore pre-install .bak configuration files:
+agy-context uninstall --restore-backups
 ```
 
----
+## CLI and hook summary
 
-## Zero-Guesswork Testing & Verification Playbook
-
-To cleanly test every layer of the framework without guesswork or interactive stalls:
-
-### 1. Audit Live Registration
-```bash
-npm run status
-# or
-node mcp/index.js status
-```
-*Confirms that all 4 integration layers (Plugin link, Lifecycle Hook, MCP Server, Schemas) and RTK are active.*
-
-### 2. Run Complete Automated Test Suite
-```bash
-npm test
-```
-*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 (27 closed-topology tests)
-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
-
-# 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
-
-# RTK ledger & fresh install verification test
-node tests/test-rtk-ledger-fresh-install.mjs
-```
-
-### 4. Test MCP Tools from Antigravity Agent
-- `get_installation_status`: Call with `{}` to audit all 4 layers + RTK.
-- `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 }`.
-
-### 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`.
-- ❌ **Do NOT loop on `manage_task(Action='status')`**: Polling triggers the session ledger circuit breaker at 5 cumulative denials. Rely on native Reactive Wakeup (`<SYSTEM_MESSAGE>`).
-- ❌ **Do NOT run `npm run uninstall` as a standalone check**: It unregisters the live hook. If run, immediately re-run `npm run setup`.
-- ❌ **On Windows, do NOT omit the directory in `rtk rg`**: Always run `rtk rg "<pattern>" .` to avoid stdin pipe blocking.
-
----
-
-## MCP Tools & Slash Commands
-
-* **User Slash Command (`/mcp:...`)**:
-  - `/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. `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`).
-  - **Completed Background Task Logs**: Inspected via `rtk read tasks/<taskId>.log` (lifecycle-gated in the PreToolUse hook; strictly blocked under Proportional Backoff while running, allowed once completed).
-
----
+| Surface | Purpose | Common usage |
+| :--- | :--- | :--- |
+| `agy-context transcript health` (`stats`, `info`) | Check turn counts, transcript byte size, RTK status, and polling events | `agy-context transcript health [<id>] [--json]` |
+| `agy-context transcript read` (`outline`, `summary`) | Read recent turns in Markdown or print a 1-line-per-step tool outline | `agy-context transcript read [<id>] --last-turns 3` / `agy-context transcript outline [<id>]` |
+| `agy-context transcript query` (`grep`, `search`, `find`, `tools`) | Search compact and truncated full steps by regex, role, or tool call arguments | `agy-context transcript grep "<pattern>" [<id>] --summary` / `agy-context transcript tools [<id>]` |
+| `agy-context transcript step` | Extract untruncated fields for a step, comma list, or range (`N..M`) | `agy-context transcript step 10..15 [<id>] --field content --tail 40` |
+| `agy-context transcript list` (`ls`) | List recent conversation transcripts in the Antigravity brain directory | `agy-context transcript ls --limit 5` |
+| `agy-context transcript access` (`policy`) | View or update child subagent and `/swarm` worker transcript access | `agy-context transcript access --status` / `--off` / `--self-only` / `--allow @audit-squad*` / `--on` |
+| `agy-context status` / `setup` / `uninstall` | Audit, synchronize, or remove plugin link, hook, CLI shims, and RTK config | `agy-context status` / `agy-context setup --check` |
+
+## Documentation
+
+Full documentation is hosted at [paragon-ux.github.io/agy-context-saver](https://paragon-ux.github.io/agy-context-saver/) and in [`docs/`](docs/):
+
+- [Overview](docs/index.md)
+- [Installation and setup](docs/installation.md)
+- [CLI and hook reference](docs/tools.md)
+- [Lifecycle governance and transcript access control](docs/governance.md)
+- [Architecture and internals](docs/architecture.md)
+- [Installer hardening policy](docs/INSTALLER-HARDENING.md)
+- [RTK support matrix](docs/RTK-SUPPORT-MATRIX.md)
+- [Publishing and verification](docs/publishing.md)
+- [Product roadmap](docs/roadmap.md)
+
+## Development
+
+Run `node scripts/release-preflight.mjs` and `npm test` with Node.js `>= 22`. Runs all 11 test suites (`tests/test-hook.mjs`, `tests/test-transcript.mjs`, `tests/test-rtk-integration.mjs`, `tests/test-output-governance.mjs`, `tests/test-e2e-probes.mjs`, `tests/test-performance-probes.mjs`, `tests/test-installed-verification.mjs`, `tests/test-lifecycle-rollback.mjs`, `tests/test-check-only-readonly.mjs`, `tests/test-malformed-config-preservation.mjs`, and `tests/test-rtk-ledger-fresh-install.mjs`) in isolated temporary profiles without mutating your live `~/.gemini` directory.
 
 ## License
 

package/assets/architecture-overview.svg

@@ -0,0 +1,39 @@
+<svg xmlns="http://www.w3.org/2000/svg" class="pele pele-flowchart" viewBox="0 0 793 582" width="793" height="582" style="max-width:100%;height:auto;--_bg:var(--pele-bg,#fff);--_fg:var(--pele-fg,#1f1f1f);--_m:var(--pele-muted,#6e6e6e);--_l:var(--pele-line,#1f1f1f);--_s:var(--pele-surface,#f3f3f3);--_a:var(--pele-surface-alt,#e6e6e6);--_b:var(--pele-border,#8a8a8a);--_c:var(--pele-accent,#5b7bd5);color:var(--_fg);--_r:var(--pele-radius,4px);--_fm:var(--pele-font-mono,monospace);font:16px sans-serif;letter-spacing:normal;word-spacing:normal;text-transform:none;direction:ltr;font-family:var(--pele-font,sans-serif)" fill="var(--_fg)" role="graphics-document document" aria-roledescription="flowchart">
+  <style>
+    :root {
+      --pele-font: -apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans", Helvetica, Arial, sans-serif;
+      --pele-bg: #ffffff;
+      --pele-fg: #1f2328;
+      --pele-muted: #656d76;
+      --pele-line: #57606a;
+      --pele-surface: #f6f8fa;
+      --pele-surface-alt: #eaeef2;
+      --pele-border: #d0d7de;
+      --pele-accent: #0969da;
+      --pele-series-1: #0969da;
+      --pele-series-2: #1a7f37;
+      --pele-series-3: #9a6700;
+      --pele-series-4: #8250df;
+      --pele-series-5: #cf222e;
+      --pele-series-6: #bf3989;
+    }
+    @media (prefers-color-scheme: dark) {
+      :root {
+        --pele-bg: #0d1117;
+        --pele-fg: #e6edf3;
+        --pele-muted: #8b949e;
+        --pele-line: #8b949e;
+        --pele-surface: #161b22;
+        --pele-surface-alt: #21262d;
+        --pele-border: #30363d;
+        --pele-accent: #2f81f7;
+        --pele-series-1: #2f81f7;
+        --pele-series-2: #3fb950;
+        --pele-series-3: #d29922;
+        --pele-series-4: #a371f7;
+        --pele-series-5: #f85149;
+        --pele-series-6: #db61a2;
+      }
+    }
+  </style>
+<g class="pele-clusters"><g class="pele-cluster" data-id="L3"><rect x="8" y="427" width="776.45" height="147" fill="var(--_a)" fill-opacity="0.5" stroke="var(--_b)" style="rx:var(--_r)"/><text class="pele-cluster-label" fill="var(--_m)" x="193.18" y="452.6" text-anchor="middle">RTK (&gt;= 1.1.0), agy-context CLI &amp; Host Wakeup</text></g><g class="pele-cluster" data-id="L2"><rect x="59.9" y="228" width="672.64" height="126" fill="var(--_a)" fill-opacity="0.5" stroke="var(--_b)" style="rx:var(--_r)"/></g><g class="pele-cluster" data-id="L1"><rect x="25.72" y="8" width="741.01" height="147" fill="var(--_a)" fill-opacity="0.5" stroke="var(--_b)" style="rx:var(--_r)"/><text class="pele-cluster-label" fill="var(--_m)" x="109.07" y="33.6" text-anchor="middle">Antigravity Runtime</text></g></g><g class="pele-edges" fill="none" stroke="var(--_l)" stroke-linecap="round"><g class="pele-edge" data-id="L_L1_L2_0"><path d="M396.22,155L396.22,221"/><path class="pele-marker" d="M396.22,228L392.86,220L399.58,220Z" fill="var(--_l)" stroke="none"/></g><g class="pele-edge" data-id="L_L2_L3_0"><path d="M396.22,354L396.22,420"/><path class="pele-marker" d="M396.22,427L392.86,419L399.58,419Z" fill="var(--_l)" stroke="none"/></g></g><g class="pele-cluster-titles"><g class="pele-cluster-title" data-id="L2"><text fill="none" stroke="color-mix(in srgb,var(--_a) 50%,var(--_bg))" stroke-width="5" stroke-linejoin="round" x="254.85" y="253.6" text-anchor="middle">Agy-Context-Saver: PreToolUse Hook (hooks.json)</text><text class="pele-cluster-label" fill="var(--_m)" x="254.85" y="253.6" text-anchor="middle">Agy-Context-Saver: PreToolUse Hook (hooks.json)</text></g></g><g class="pele-edge-labels" font-size="14"><g class="pele-edge-label" data-id="L_L1_L2_0"><rect x="328.81" y="177.5" width="134.83" height="21" rx="3" fill="var(--_bg)"/><text x="396.22" y="192.9" text-anchor="middle">PreToolUse payload</text></g><g class="pele-edge-label" data-id="L_L2_L3_0"><rect x="312.09" y="376.5" width="168.27" height="21" rx="3" fill="var(--_bg)"/><text x="396.22" y="391.9" text-anchor="middle">rewrite, slice, or 10s grant</text></g></g><g class="pele-nodes"><g class="pele-node pele-shape-rect" data-id="A1" transform="translate(125.95,91.5)"><rect x="-80.23" y="-33" width="160.46" height="66" fill="var(--_s)" stroke="var(--_b)" style="rx:var(--_r)"/><text class="pele-label" text-anchor="middle" xml:space="preserve"><tspan x="0" y="-4.9">run_command</tspan><tspan x="0" y="16.1">(shell &amp; CLI calls)</tspan></text></g><g class="pele-node pele-shape-rect" data-id="A2" transform="translate(358.87,91.5)"><rect x="-112.69" y="-43.5" width="225.38" height="87" fill="var(--_s)" stroke="var(--_b)" style="rx:var(--_r)"/><text class="pele-label" text-anchor="middle" xml:space="preserve"><tspan x="0" y="-15.4">read_file / edit_file /</tspan><tspan x="0" y="5.6">write_file</tspan><tspan x="0" y="26.6">(workspace &amp; special files)</tspan></text></g><g class="pele-node pele-shape-rect" data-id="A3" transform="translate(629.14,91.5)"><rect x="-117.58" y="-33" width="235.17" height="66" fill="var(--_s)" stroke="var(--_b)" style="rx:var(--_r)"/><text class="pele-label" text-anchor="middle" xml:space="preserve"><tspan x="0" y="-4.9">manage_task / schedule</tspan><tspan x="0" y="16.1">(background tasks &amp; timers)</tspan></text></g><g class="pele-node pele-shape-rect" data-id="B1" transform="translate(168.61,301)"><rect x="-88.7" y="-33" width="177.41" height="66" fill="var(--_s)" stroke="var(--_b)" style="rx:var(--_r)"/><text class="pele-label" text-anchor="middle" xml:space="preserve"><tspan x="0" y="-4.9">Shell &amp; State Guard</tspan><tspan x="0" y="16.1">+ 10s Sync Window</tspan></text></g><g class="pele-node pele-shape-rect" data-id="B2" transform="translate(394.9,301)"><rect x="-97.58" y="-33" width="195.17" height="66" fill="var(--_s)" stroke="var(--_b)" style="rx:var(--_r)"/><text class="pele-label" text-anchor="middle" xml:space="preserve"><tspan x="0" y="-4.9">Hybrid Slice (&lt;= 150L)</tspan><tspan x="0" y="16.1">&amp; Safe Harbor</tspan></text></g><g class="pele-node pele-shape-rect" data-id="B3" transform="translate(622.51,301)"><rect x="-90.03" y="-33" width="180.06" height="66" fill="var(--_s)" stroke="var(--_b)" style="rx:var(--_r)"/><text class="pele-label" text-anchor="middle" xml:space="preserve"><tspan x="0" y="-4.9">Proportional Backoff</tspan><tspan x="0" y="16.1">&amp; 5-Strike Breaker</tspan></text></g><g class="pele-node pele-shape-rect" data-id="C1" transform="translate(135.38,510.5)"><rect x="-107.38" y="-33" width="214.75" height="66" fill="var(--_s)" stroke="var(--_b)" style="rx:var(--_r)"/><text class="pele-label" text-anchor="middle" xml:space="preserve"><tspan x="0" y="-4.9">rtk hook antigravity</tspan><tspan x="0" y="16.1">&amp; rtk grep / find / ls / read</tspan></text></g><g class="pele-node pele-shape-rect" data-id="C2" transform="translate(397.57,510.5)"><rect x="-114.82" y="-43.5" width="229.63" height="87" fill="var(--_s)" stroke="var(--_b)" style="rx:var(--_r)"/><text class="pele-label" text-anchor="middle" xml:space="preserve"><tspan x="0" y="-15.4">agy-context transcript</tspan><tspan x="0" y="5.6">read | query | step | health |</tspan><tspan x="0" y="26.6">list | access</tspan></text></g><g class="pele-node pele-shape-rect" data-id="C3" transform="translate(658.42,510.5)"><rect x="-106.03" y="-33" width="212.06" height="66" fill="var(--_s)" stroke="var(--_b)" style="rx:var(--_r)"/><text class="pele-label" text-anchor="middle" xml:space="preserve"><tspan x="0" y="-4.9">Reactive Wakeup</tspan><tspan x="0" y="16.1">&amp; 10s Single-Use Grants</tspan></text></g></g></svg>