agy-context-saver 1.8.1 → 2.0.1

package/scripts/provision-rtk.mjs

@@ -9,16 +9,18 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const repoRoot = path.resolve(__dirname, "..");
 const binDir = path.join(repoRoot, "bin");
 
-export const RTK_VERSION = "v0.51.0";
-export const MIN_COMPATIBLE_RTK_VERSION = "0.50.0";
-export const MAX_COMPATIBLE_RTK_VERSION = "0.52.0";
+export const RTK_VERSION = "v1.1.0";
+export const MIN_RTK_VERSION = "1.1.0";
+export const MIN_COMPATIBLE_RTK_VERSION = MIN_RTK_VERSION;
 
+// Pinned SHA-256 checksums per release asset from https://github.com/rtk-ai/rtk/releases/download/v1.1.0/checksums.txt;
+// ensureRtkInstalled verifies the downloaded archive before extraction and fails closed on any mismatch.
 export const RTK_CHECKSUMS = {
-  "rtk-x86_64-pc-windows-msvc.zip": "1623e9b45d28b15122d69e7314776e1123a804224885ce07e7182fb40080f05c",
-  "rtk-aarch64-apple-darwin.tar.gz": "8817d8b71afc02ac8bf06eb24bcc41c306592ab735b68e8fee9db1ba0de7cb59",
-  "rtk-x86_64-apple-darwin.tar.gz": "bd39c8153f4147358360c7dc51665a8131cc9ee16f81f69a9402ffa500be3cc2",
-  "rtk-x86_64-unknown-linux-musl.tar.gz": "5028d3b19a8f0990d30fec9fbb07e32782bc5698e618fb1861aad8a9ccba4eb5",
-  "rtk-aarch64-unknown-linux-gnu.tar.gz": "8d6d1aad9e69b42481eda7039507d1f7ee93698f87713cecd873d287c1931632"
+  "rtk-x86_64-pc-windows-msvc.zip": "c9a8f7a8bad471e64a343314168f38d2399a06fa327cdf5772fb0e645d99ea6f",
+  "rtk-aarch64-apple-darwin.tar.gz": "8da773b0954cf90b115ec95c4e4eb420f04c39de233c5db102246a6caf073ba7",
+  "rtk-x86_64-apple-darwin.tar.gz": "1e23e8b9542b58428e6409c49b1c3fb92c4c0d5125da72e80f002a46086a6c20",
+  "rtk-x86_64-unknown-linux-musl.tar.gz": "9454ad1b9489daa57ab0a9f4ebe2faaf4dc82b8a0f26c9e5135151abd7c9378d",
+  "rtk-aarch64-unknown-linux-gnu.tar.gz": "a5c00c3ab0129884bcb757d348afc1a650efa0f4f0769da97c341f28f89719ed"
 };
 
 export function isCompatibleRtkVersion(versionStr) {
@@ -27,8 +29,7 @@ export function isCompatibleRtkVersion(versionStr) {
   if (!match) return false;
   const major = parseInt(match[1], 10);
   const minor = parseInt(match[2], 10);
-  // Compatible if 0.50.x or 0.51.x (>= 0.50.0 and < 0.52.0)
-  return major === 0 && (minor === 50 || minor === 51);
+  return major > 1 || (major === 1 && minor >= 1);
 }
 
 export function getRtkPlatformAsset() {
@@ -59,6 +60,17 @@ export function findExistingRtk(options = {}) {
   const pluginBinDir = path.join(profileHome, ".gemini", "config", "plugins", "agy-context-saver", "bin");
   const candidateDirs = [binDir, pluginBinDir];
 
+  // Check PATH first so a system rtk >= 1.1.0 is preferred over bundled binaries
+  try {
+    const out = execSync("rtk --version", { encoding: "utf-8", timeout: 5000, stdio: ["ignore", "pipe", "ignore"] }).trim();
+    if (isCompatibleRtkVersion(out)) {
+      return { path: "rtk", version: out, isLocal: false };
+    }
+    if (!options.silent) {
+      console.warn(`[WARN] System RTK version '${out}' is below minimum supported version >=${MIN_RTK_VERSION}. Local or manual ${RTK_VERSION} installation is required.`);
+    }
+  } catch {}
+
   for (const dir of candidateDirs) {
     for (const exeName of names) {
       const localExe = path.join(dir, exeName);
@@ -73,18 +85,6 @@ export function findExistingRtk(options = {}) {
     }
   }
 
-  // Check PATH
-  try {
-    const out = execSync("rtk --version", { encoding: "utf-8", timeout: 5000, stdio: ["ignore", "pipe", "ignore"] }).trim();
-    if (isCompatibleRtkVersion(out)) {
-      return { path: "rtk", version: out, isLocal: false };
-    } else {
-      if (!options.silent) {
-        console.warn(`[WARN] System RTK version '${out}' is outside supported range [>=${MIN_COMPATIBLE_RTK_VERSION} <${MAX_COMPATIBLE_RTK_VERSION}]. Local pinned ${RTK_VERSION} will be required.`);
-      }
-    }
-  } catch {}
-
   return null;
 }
 
@@ -102,6 +102,19 @@ export async function ensureRtkInstalled(options = {}) {
     throw new Error(`Unsupported platform/architecture for prebuilt RTK: ${os.platform()} ${os.arch()}`);
   }
 
+  // Fail closed when the target release asset checksum is unpinned/missing instead of trusting stale hashes
+  const expectedHash = RTK_CHECKSUMS[assetInfo.asset];
+  if (!expectedHash) {
+    throw new Error(
+      `Integrity error: No pinned SHA-256 checksum configured for RTK ${RTK_VERSION} asset '${assetInfo.asset}'.\n` +
+      `Automated download aborted (fail-closed). Please install RTK >= ${MIN_RTK_VERSION} manually and ensure 'rtk' is on your PATH:\n` +
+      `  - macOS (Homebrew): brew install rtk\n` +
+      `  - Cargo:            cargo install --locked rtk\n` +
+      `  - Official script:  curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh\n` +
+      `  - GitHub Releases:  https://github.com/rtk-ai/rtk/releases/tag/${RTK_VERSION}`
+    );
+  }
+
   if (!fs.existsSync(binDir)) {
     fs.mkdirSync(binDir, { recursive: true });
   }
@@ -118,10 +131,6 @@ export async function ensureRtkInstalled(options = {}) {
   const buffer = Buffer.from(await response.arrayBuffer());
 
   // Fail-closed SHA-256 verification before writing archive to disk or extracting
-  const expectedHash = RTK_CHECKSUMS[assetInfo.asset];
-  if (!expectedHash) {
-    throw new Error(`Integrity error: No pinned SHA-256 checksum found for asset '${assetInfo.asset}'`);
-  }
   const actualHash = crypto.createHash("sha256").update(buffer).digest("hex");
   if (actualHash !== expectedHash) {
     throw new Error(

package/scripts/release-preflight.mjs

@@ -27,10 +27,13 @@ function exists(relativePath) {
 }
 
 let pkg;
-try {
-  pkg = JSON.parse(readText('package.json'));
-} catch (error) {
-  errors.push(`package.json is not valid JSON: ${error.message}`);
+const pkgText = readText('package.json');
+if (pkgText) {
+  try {
+    pkg = JSON.parse(pkgText);
+  } catch (error) {
+    errors.push(`package.json is not valid JSON: ${error.message}`);
+  }
 }
 
 if (pkg) {
@@ -41,6 +44,26 @@ if (pkg) {
     errors.push(`package.json version is not a valid semver release version: ${JSON.stringify(pkg.version)}.`);
   }
 
+  const pluginText = readText('plugin.json');
+  if (pluginText) {
+    try {
+      const pluginManifest = JSON.parse(pluginText);
+      if (pluginManifest.name !== pkg.name) {
+        errors.push(`plugin.json name ${JSON.stringify(pluginManifest.name)} does not match package.json name ${JSON.stringify(pkg.name)}.`);
+      }
+      if (pluginManifest.version !== pkg.version) {
+        errors.push(`plugin.json version ${JSON.stringify(pluginManifest.version)} does not match package.json version ${JSON.stringify(pkg.version)}.`);
+      }
+    } catch (error) {
+      errors.push(`plugin.json is not valid JSON: ${error.message}`);
+    }
+  }
+
+  const changelogText = readText('CHANGELOG.md');
+  if (changelogText && pkg.version && !changelogText.includes(`## [${pkg.version}]`)) {
+    errors.push(`CHANGELOG.md is missing a release heading for current version "## [${pkg.version}]".`);
+  }
+
   const requiredMetadata = [
     ['repository.url', pkg.repository?.url],
     ['homepage', pkg.homepage],
@@ -57,17 +80,45 @@ if (pkg) {
   }
 
   const requiredPackageFiles = [
-    'mcp/index.js',
+    'lib/transcript-core.mjs',
+    'bin/agy-context.mjs',
     'scripts/install-register.mjs',
     'scripts/provision-rtk.mjs',
     'plugin.json',
     'hooks.json',
-    'mcp_config.json',
     'README.md',
     'CHANGELOG.md',
     'LICENSE',
   ];
 
+  if (exists('mcp_config.json')) {
+    errors.push('Legacy mcp_config.json is still present at repository root; remove it for 2.0 CLI-first release.');
+  }
+  if (exists('mcp')) {
+    errors.push('Legacy mcp/ directory is still present at repository root; remove it for 2.0 CLI-first release.');
+  }
+
+  const hooksText = readText('hooks.json');
+  if (hooksText) {
+    try {
+      const pluginHooks = JSON.parse(hooksText);
+      const hookCmd = pluginHooks?.['agy-context-saver']?.PreToolUse?.[0]?.hooks?.[0]?.command ?? '';
+      const hookMatcher = pluginHooks?.['agy-context-saver']?.PreToolUse?.[0]?.matcher ?? '';
+      if (!hookCmd) {
+        errors.push('hooks.json must define "agy-context-saver".PreToolUse[0].hooks[0].command.');
+      } else if (hookCmd.includes('ANTIGRAVITY_PLUGIN_ROOT')) {
+        errors.push('hooks.json command must not use unexpanded ${ANTIGRAVITY_PLUGIN_ROOT}; use ./scripts/execution-guard-hook.mjs (cwd is plugin root).');
+      }
+      for (const tool of ['read_file', 'edit_file', 'write_file', 'run_command']) {
+        if (!hookMatcher.includes(tool)) {
+          errors.push(`hooks.json PreToolUse matcher must include ${tool}.`);
+        }
+      }
+    } catch (error) {
+      errors.push(`hooks.json is not valid JSON: ${error.message}`);
+    }
+  }
+
   for (const relativePath of requiredPackageFiles) {
     if (!exists(relativePath)) errors.push(`Required runtime/release file is missing: ${relativePath}`);
     const coveredByFiles = (pkg.files ?? []).some((entry) => {
@@ -105,7 +156,7 @@ if (pkg) {
     const readme = readText('README.md');
     const countMatch = readme.match(/Runs all\s+(\d+)\s+test suites?/i);
     if (!countMatch) {
-      errors.push('README.md must state the exact suite count using a sentence such as "Runs all 8 test suites".');
+      errors.push('README.md must state the exact suite count using a sentence such as "Runs all 11 test suites".');
     } else if (Number(countMatch[1]) !== suitePaths.length) {
       errors.push(`README.md says ${countMatch[1]} test suites, but package.json scripts.test runs ${suitePaths.length}.`);
     }
@@ -121,11 +172,24 @@ if (pkg) {
   }
 
   const rtkProvisioner = readText('scripts/provision-rtk.mjs');
-  const rtkVersionMatch = rtkProvisioner.match(/RTK_VERSION\s*=\s*['"]([^'"]+)['"]/);
-  if (!rtkVersionMatch) {
-    errors.push('Could not locate a pinned RTK_VERSION in scripts/provision-rtk.mjs.');
+  const minRtkMatch = rtkProvisioner.match(/MIN_(?:COMPATIBLE_)?RTK_VERSION\s*=\s*['"]v?([^'"]+)['"]/);
+  const rtkVersionMatch = rtkProvisioner.match(/RTK_VERSION\s*=\s*['"]v?([^'"]+)['"]/);
+  const detectedRtkVersion = minRtkMatch?.[1] || rtkVersionMatch?.[1];
+  if (!detectedRtkVersion) {
+    errors.push('Could not locate MIN_RTK_VERSION or RTK_VERSION in scripts/provision-rtk.mjs.');
   } else {
-    console.log(`RTK provisioner pin found: ${rtkVersionMatch[1]}`);
+    const semverMatch = detectedRtkVersion.match(/^(\d+)\.(\d+)\.(\d+)/);
+    if (!semverMatch) {
+      errors.push(`Invalid RTK version format in scripts/provision-rtk.mjs: ${detectedRtkVersion}`);
+    } else {
+      const major = Number(semverMatch[1]);
+      const minor = Number(semverMatch[2]);
+      if (major < 1 || (major === 1 && minor < 1)) {
+        errors.push(`RTK version requirement must be >= 1.1.0; found ${detectedRtkVersion} in scripts/provision-rtk.mjs.`);
+      } else {
+        console.log(`RTK provisioner requirement found: ${detectedRtkVersion} (>= 1.1.0)`);
+      }
+    }
   }
 
   if (!pkg.scripts?.setup || !pkg.scripts?.status || !pkg.scripts?.test) {

package/scripts/state-dir.mjs

@@ -4,6 +4,7 @@
  * State lives in a folder owned by this user, never in the shared os.tmpdir():
  *   Windows: %LOCALAPPDATA%\agy-context-saver
  *   POSIX:   $XDG_STATE_HOME/agy-context-saver (default ~/.local/state/agy-context-saver)
+ *   Legacy versions (<= 1.7.0) left session JSON files in os.tmpdir(); cleaned on setup/uninstall.
  * Under AGY_TEST_PROFILE_DIR the same layout is rooted in the test profile.
  *
  * The hook is mirrored into ~/.gemini/config/scripts as a standalone file, so it keeps an

package/skills/context-governance/SKILL.md

@@ -1,100 +1,106 @@
 ---
 name: context-governance
 description: >-
-  Use when running shell commands with large outputs, inspecting session transcript health,
-  preventing repetitive background polling loops, or inspecting codebases with RTK.
+  Use when running shell commands with large outputs, inspecting session transcript health
+  via agy-context, preventing repetitive background polling loops, or inspecting codebases with RTK.
 ---
 
 # Context Governance & Execution Guard (Agy-Context-Saver + RTK)
 
-Agy-Context-Saver and RTK protect session transcript health and LLM attention by transparently compressing command outputs, preventing repetitive background polling loops, and routing native inspection to compact CLI interfaces.
+`Agy-Context-Saver` and `RTK` compress shell output, enforce bounded workspace file reads, stop background-task busy-polling, and provide CLI commands for conversation transcript inspection and access control.
 
-## Architectural Boundaries
+## Architectural Boundary
 
-- **RTK (Rust Token Killer)**: Owns shell command rewriting, terminal output compression, and canonical codebase inspection (`rtk read`, `rtk grep`, `rtk find`, `rtk ls`, `rtk err`, `rtk summary`).
-- **Agy-Context-Saver**: Owns Antigravity lifecycle governance, Reactive Wakeup enforcement, transcript forensics, and session integrity.
+- **RTK (`>= 1.1.0`)**: Rewrites shell commands (`rtk hook antigravity`), compresses command output, and provides workspace search and file listing (`rtk grep`, `rtk find`, `rtk ls`, `rtk read`, `rtk err`, `rtk summary`).
+- **Agy-Context-Saver (`v2.0.0`)**: Enforces Reactive Wakeup backoff, bounds `read_file` slices, protects `.system_generated/` and the state directory, and exposes `agy-context transcript`.
 
 ---
 
-## Unified 3-Tier Codebase & File Inspection
+## Workspace File & Codebase Inspection
 
-Unbounded full-file `view_file` calls and unoptimized search tools (`grep_search`, `find_by_name`, `list_dir`) bypass token compression and are guarded:
+Unbounded full-file `read_file` calls on workspace files are blocked by the `PreToolUse` hook:
 
-1. **Tier 1 — Structural Discovery (`waymark_ask` with `plain: true`)**:
-   - Locate exact `[StartLine, EndLine]` coordinates via `waymark_ask(..., plain: true)` across all 23 supported formats (code ASTs + `markdown`, `yaml`, `json`, `toml`, `bash`). Always set `plain: true` (~19–466 tokens, zero shell quoting or stdin hazards).
-2. **Tier 2 — Precision Workspace File Reading (`view_file` Hybrid Slice Policy)**:
-   - Pass `StartLine` and `EndLine` from `waymark_ask` into `view_file` (bounded slices of `1–150` lines) to preserve exact 1-indexed line numbers for `replace_file_content` without terminal stdout truncation. Partial slices of `151–800` lines are denied; an explicit one-pass full-file audit (`StartLine: 1, EndLine: <TotalLines>`) is permitted only when the file on disk is $\le 800$ lines and $\le 45\text{ KiB}$ (`46,080` bytes).
-3. **Tier 3 — RTK Boundaries (`rtk read`, `rtk find`, `rtk rg`, `rtk err`, `rtk summary`)**:
-   - **Spillovers & Task Logs**: Read `.system_generated/steps/<step>/output.txt` spillovers and completed `tasks/<taskId>.log` files via `rtk read <path>` (`--head-lines` / `--tail-lines`). Never use `rtk read -l minimal|aggressive` or `-m` to derive line numbers for edits.
-   - **Directory / File Discovery**:
-     - **Windows**: Use `rtk find <path>` or PowerShell `dir` / `Get-ChildItem`. (Avoid `rtk ls` or `rtk tree` on Windows as they rely on POSIX binaries/flags).
-     - **POSIX / Linux / macOS**: Use `rtk find <path>`, `rtk ls <path>`, or `rtk tree`.
-   - **Prose / Regex Search (when symbol, heading, or config key is unknown)**:
-     - **Windows**: Use `rtk rg "<pattern>" .` (explicit target `.` is required to avoid child process stdin pipe stalls) or `rg "<pattern>" .`.
-     - **POSIX / Linux / macOS**: Use `rtk grep "<pattern>"` or `rtk rg "<pattern>"`.
-   - `rtk err <cmd>`: Runs command and displays only errors/warnings.
-   - `rtk summary <cmd>`: Runs command and produces a 2-line technical summary.
+1. **Tier 1 (Search and discovery: `rtk grep`, `rtk find`, `rtk ls`)**:
+   - **Pattern and symbol search**: Run `rtk grep -rnE "<pattern>" <path>` via `run_command` to locate `[StartLine, EndLine]` coordinates. Always pass an explicit target path (such as `.` or `src/`) so `rtk grep` does not wait on stdin.
+   - **Directory and file listing**: Run `rtk find <path>`, `rtk ls <path>`, or `rtk tree` (or PowerShell `dir` / `Get-ChildItem` on Windows).
+2. **Tier 2 (Workspace file reading: `read_file` slice policy)**:
+   - Pass `StartLine` and `EndLine` into `read_file` in bounded slices of `1-150` lines to preserve 1-indexed line numbers for `edit_file` and `write_file`.
+   - Partial slices of `151-800` lines and `ByteOffset`-only unbounded reads are denied. An explicit full-file read (`StartLine: 1, EndLine: <TotalLines>`) is allowed when the file on disk is $\le 800$ lines and $\le 45\text{ KiB}$ (`46,080` bytes).
+3. **Tier 3 (Spillovers and diagnostics: `rtk read`, `rtk err`, `rtk summary`)**:
+   - **Spillovers and task logs**: Read `.system_generated/steps/<step>/output.txt` spillovers (via bounded `read_file` $\le 150$ lines or `rtk read <path>`) and completed `tasks/<taskId>.log` files via `rtk read <path>` (`--head-lines` / `--tail-lines`). Never use `rtk read -l minimal|aggressive` or `-m` to derive line numbers for `edit_file` or `write_file`.
+   - `rtk err <cmd>`: Runs a command and prints only errors and warnings.
+   - `rtk summary <cmd>`: Runs a command and prints a 2-line summary.
 
-*Safe Harbor*: Documented Antigravity special files (`SKILL.md`, brain artifacts, `.gemini/config/`) may be viewed directly via `view_file` without slice bounds.
+*Safe harbor*: Antigravity special files (`SKILL.md`, `AGENTS.md`, brain artifacts, `.gemini/config/`) may be read via `read_file` without slice bounds, and `.system_generated/steps/<n>/output.txt` supports bounded `read_file` ($\le 150$ lines).
 
 ---
 
-## Available Agy MCP Tools
-
-### 1. `check_context_health`
-Performs streaming inspection of `transcript.jsonl` to calculate turn budgets, step counts, raw payload size, RTK status, and detect busy-polling loops.
-- **Parameters**:
-  - `transcriptPath` (string, required): Absolute path to `transcript.jsonl`.
-
-### 2. `read_transcript`
-Quickly reads recent conversation turns from an Antigravity transcript in clean Markdown format with zero JSON noise.
-- **Parameters**:
-  - `conversationId` (string, required): Conversation UUID or path.
-  - `mode` (string, default: "compact"): "compact" or "full".
-  - `lastTurns` (number, default: 3): Number of turns to display.
-
-### 3. `query_transcript`
-Granular query and forensic filtering engine for transcripts with keyword/regex search, auto-dereferencing of truncated payloads, and surgical step projection.
-- **Parameters**:
-  - `conversationId` (string, required): Conversation UUID or path.
-  - `query` (string, optional): Search keyword or regex.
-  - `roles` (array, default: ["user", "assistant"]): Filter by role (`"user"`, `"assistant"`, `"subagent"`, `"tool"`, `"error"`, `"all"`).
-  - `stepIndex` (number, optional): Specific step to dereference from `transcript_full.jsonl`.
-  - `field` (string, optional): Field projection (`"content"`, `"thinking"`, `"tool_calls"`).
-
-### 4. `get_installation_status`
-Audits the Antigravity integration layers (Native Plugin Link, Lifecycle Hook in `hooks.json`, MCP Server in `mcp_config.json`, Tool Schemas, and RTK binary/hook).
-
-### 5. `sync_installation`
-Re-verifies, repairs, and synchronizes the installation and tool schemas in ~25ms.
-- **Parameters**:
-  - `checkOnly` (boolean, default: false): Dry-run audit mode.
+## `agy-context` CLI Commands
+
+Run `agy-context` via `run_command` (`~/.gemini/antigravity/bin/agy-context`). Invoke `agy-context transcript ...` as a single unchained command without `&&`, `||`, `;`, `|`, or redirects:
+
+### 1. `agy-context transcript health` (aliases: `stats`, `info`)
+Checks turn counts, step counts, raw transcript size, RTK status, and busy-polling events.
+```bash
+agy-context transcript health [<id>] [--id <conv>] [--json] [--file <path>]
+```
+
+### 2. `agy-context transcript read` (aliases: `outline`, `summary`)
+Streams recent conversation turns in Markdown, or prints a 1-line-per-step outline when `--outline` (or `outline` / `summary`) is used.
+```bash
+agy-context transcript read [<id>] [--id <conv>] [--mode compact|full] [--last-turns N] [--offset N] [--limit N] [--outline] [--include-thinking] [--json] [--file <path>]
+```
+
+### 3. `agy-context transcript query` (aliases: `grep`, `search`, `find`, `tools`)
+Searches transcripts by regex or substring with automatic dereferencing of truncated fields, role filtering (`user`, `assistant`, `subagent`, `tool`, `generic`, `system`, `error`, `all`), and `--full-args` / `--field` projection. The `tools` alias defaults to `--roles assistant --field tool_args --include-tools`.
+- **Multi-step forensic workflow**:
+  1. `agy-context transcript outline [<conv>] --start 0 --end 100` (1-line-per-step index with `[ERROR]` and `[tools: ...]` tags)
+  2. `agy-context transcript tools [<conv>] --start 0 --end 100` (all untruncated tool call arguments in one call)
+  3. `agy-context transcript step <N,M,K|N-M> [<conv>] --field content` (batch-extract specific step outputs without 1-by-1 `--step <N>` loops)
+```bash
+agy-context transcript query [<pattern>] [<id>] [--id <conv>] [--query <regex>] [--roles csv] [--mode auto|compact|full] [--start N] [--end N] [--last-turns N] [--limit N] [--summary] [--include-tools] [--full-args] [--field content|thinking|tool_calls|tool_args|tool_args:Key|all] [--include-thinking] [--json] [--file <path>]
+```
+
+### 4. `agy-context transcript step`
+Extracts untruncated content or specific fields (`content`, `thinking`, `tool_calls`, `tool_args`, `tool_args:<Key>`, `all`) for one step or a batch/range of steps (`2,8,14`, `2-10`, `2..10`, or `--start 2 --end 10`) from `transcript_full.jsonl`, with optional `--head <N>`, `--tail <N>`, and `--full` slicing.
+```bash
+agy-context transcript step [<N|N,M|N-M|N..M>] [<id>] [--id <conv>] (--step <N|N,M|N-M|N..M> | --start N --end M) [--field content|thinking|tool_calls|tool_args|tool_args:Key|all] [--head N] [--tail N] [--full] [--json] [--file <path>]
+```
+
+### 5. `agy-context transcript list` (alias: `ls`)
+Lists recent conversations in the Antigravity brain directory sorted by modification time.
+```bash
+agy-context transcript list [--limit N] [--json]
+```
+
+### 6. `agy-context transcript access` (alias: `policy`)
+Controls parent transcript access policies for child subagents and `/swarm` workers.
+```bash
+agy-context transcript access [status|off|on|reset|self-only] [--status | --off (--deny-children) | --on (--reset) | --self-only | --mode <open|allowlist|self-only|deny> | --allow <id,@roster*...> | --deny <id,@roster*...> | --ttl <sec>] [--json]
+```
+- **First-line launch directives**: Place `[agy-transcript-access: deny]`, `[agy-transcript-access: self-only]`, or `[agy-transcript-access: allow]` on the first non-empty line of a `define_subagent` `SystemPrompt`, `invoke_subagent` `Prompt`, or `/swarm` worker `brief` (later lines and code blocks are ignored).
+- **5-tier precedence**: `1. Policy Owner` -> `2. Explicit CLI --deny` -> `3. Explicit CLI --allow` (supports `@roster*` prefix globs such as `@audit-squad*`) -> `4. First-Line Launch Directive` -> `5. Cohort Default Mode`.
+- **Stale-lock protection**: Policies (`policies[ownerId]`) expire after a 1-hour default TTL, Step 0 `USER_INPUT` top-level user sessions bypass child locks automatically, Step 0/1 `sender=<parentConvId>` binds child agents to their parent policy, and `agy-context status` displays the active `Transcript Access Policy`.
+
+### 7. `agy-context status` & `agy-context setup`
+Audits or synchronizes the plugin link, `PreToolUse` hook, CLI shims, RTK (`>= 1.1.0`), and `Transcript Access Policy`.
+```bash
+agy-context status [--json]
+agy-context setup [--check] [--allow-degraded]
+agy-context uninstall [--restore-backups]
+```
 
 ---
 
-## 3-Layer Governance Invariants
-
-1. **Layer 1: Reactive Lifecycle & Polling Immunity**:
-   - Never busy-wait on `manage_task(Action='status')` or rapid polling timers.
-   - Stop calling tools and yield the turn for native Reactive Wakeup (`<SYSTEM_MESSAGE>`).
-   - Diagnostic status inspections follow exponential backoff: $\min(600, \text{round}(30 \times 2.5^{\text{pollCount}-1}))$.
-   - 5 cumulative denials trigger the `force_ask` circuit breaker.
-   - For operations $>15\text{s}$, schedule coordinated watchdog timers: `schedule(DurationSeconds=45, TimerCondition="task-X")` and output a structured Pre-Yield Status Card.
-
-2. **Layer 2: Transparent CLI & Codebase Streamlining**:
-   - Shell commands transparently rewrite via RTK (`rtk git`, `rtk pytest`, `rtk cargo`, etc.).
-   - Workspace file inspection follows `waymark_ask(..., plain: true)` $\to$ bounded `view_file(StartLine, EndLine)`, while `rtk read` handles step spillovers and completed task logs, and `rtk find` / `rtk rg "<pattern>" .` handle directory and free-text search.
-   - Direct access to `.system_generated/` is strictly denied; use `read_transcript` and `query_transcript`.
-   - **Log Hygiene (Git CRLF/LF Notice Stripping)**: Repetitive Git line-ending notices (`warning: LF will be replaced by CRLF` / `warning: CRLF will be replaced by LF...`) are non-actionable environment noise. Agy-Context-Saver automatically strips these warning lines across forensic transcript parsers, and agents suppress them at the source (`git -c core.safecrlf=false`) to protect context window tokens.
-
-3. **Layer 3: Synchronous Execution**:
-   - Synchronous wait window expands to 10,000ms to eliminate unnecessary detachment.
-
----
-
-## Quick Verification & Health Check
-
-To verify installation health and run test validation:
-- **Health Check**: `npm run status` (verifies plugin link, hook, MCP config, schemas, RTK).
-- **Test Suite**: `npm test` (runs all 10 test suites).
-- Detailed verification playbooks and release steps reside in `docs/publishing.md`.
+## Governance Summary
+
+1. **Layer 1 (Reactive lifecycle and backoff)**:
+   - Do not busy-wait on `manage_task(Action='status')` or short polling timers; end the turn and wait for Reactive Wakeup (`<SYSTEM_MESSAGE>`).
+   - Status checks follow exponential backoff: $\min(600, \text{round}(30 \times 2.5^{\text{pollCount}-1}))$. 5 cumulative denials trigger the `force_ask` circuit breaker.
+   - For background shell tasks $>15\text{s}$, schedule `schedule(DurationSeconds=45, TimerCondition="task-X")` and output a Pre-Yield Status Card. Never pair `swarm_wait` or subagents with a one-shot `schedule` timer.
+2. **Layer 2 (Shell rewriting, file slices, and transcript access)**:
+   - Shell commands rewrite via `rtk hook antigravity`.
+   - Workspace inspection uses `rtk grep` / `rtk find` -> bounded `read_file(StartLine, EndLine)` -> `edit_file` / `write_file`, while `rtk read` reads step spillovers and completed task logs.
+   - Direct access to `.system_generated/` or `getStateDir()` is denied; use `agy-context transcript` when permitted by the parent's access policy.
+3. **Layer 3 (Synchronous window)**:
+   - Non-daemon `run_command` calls without an explicit `WaitMsBeforeAsync` default to 10,000ms.