agy-context-saver 2.0.0 → 2.0.1

package/CHANGELOG.md

@@ -5,6 +5,18 @@ 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

package/README.md

@@ -22,7 +22,7 @@ The repository ships four components:
 
 - **Node.js:** `>= 22.0.0`
 - **Google Antigravity:** Antigravity 2.0+ (Desktop IDE or `agy` CLI)
-- **RTK:** `>= 1.1.0` on `PATH` (or provisioned into the plugin `bin/` directory during setup)
+- **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)
 
 ### Install and verify
 
@@ -37,6 +37,8 @@ npm run setup
 agy-context status
 ```
 
+> **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.
+
 To remove the plugin link, hook entries, and CLI shims:
 
 ```bash

package/bin/agy-context.mjs

@@ -17,7 +17,8 @@ import {
   checkContextHealth,
   getBrainDir,
   manageTranscriptAccessPolicy,
-  verifyTranscriptCoreAccess
+  verifyTranscriptCoreAccess,
+  consumeTranscriptAccessGrant
 } from "../lib/transcript-core.mjs";
 import {
   runInstall,
@@ -165,6 +166,7 @@ function validateExplicitFileFlag(fileArg) {
 }
 
 function emitError(message, asJson = false, extra = {}) {
+  consumeTranscriptAccessGrant();
   if (asJson) {
     console.error(JSON.stringify({ isError: true, error: message, ...extra }, null, 2));
   } else {
@@ -213,7 +215,8 @@ async function handleTranscriptCommand(argv) {
         includeToolCalls: true,
         fullArgs: Boolean(opts["full-args"]),
         includeThinking: Boolean(opts["include-thinking"]),
-        allowExternalPaths: false
+        allowExternalPaths: false,
+        subcommand: sub
       });
       if (res.isError) {
         emitError(res.text, Boolean(opts.json), res.candidates ? { candidates: res.candidates } : {});
@@ -317,7 +320,8 @@ async function handleTranscriptCommand(argv) {
       fullArgs: Boolean(opts["full-args"]),
       field: opts.field,
       includeThinking: Boolean(opts["include-thinking"]),
-      allowExternalPaths: false
+      allowExternalPaths: false,
+      subcommand: sub
     });
 
     if (res.isError) {

package/lib/transcript-core.mjs

@@ -61,8 +61,29 @@ export function getBrainDir() {
   return process.env.AGY_BRAIN_DIR || path.join(getProfileHomeDir(), ".gemini", "antigravity", "brain");
 }
 
-export function extractConvId(p) {
-  const normalized = String(p || "").replace(/\\/g, "/");
+export function extractConvId(p, { strictBrainContainment = false } = {}) {
+  const rawStr = String(p || "");
+  try {
+    const brainRoot = realOrNull(getBrainDir()) || path.resolve(getBrainDir());
+    const targetResolved = realOrNull(rawStr) || path.resolve(rawStr);
+    const norm = (s) => (os.platform() === "win32" ? s.toLowerCase() : s);
+    const rel = path.relative(norm(brainRoot), norm(targetResolved));
+    if (rel && !rel.startsWith("..") && !path.isAbsolute(rel)) {
+      const origRel = path.relative(brainRoot, targetResolved);
+      const segments = origRel.split(path.sep).filter(Boolean);
+      const firstSeg = segments[0];
+      if (firstSeg && firstSeg !== "." && firstSeg !== "..") {
+        if (strictBrainContainment && segments.length === 1 && firstSeg.toLowerCase().endsWith(".jsonl")) {
+          return null;
+        }
+        return firstSeg;
+      }
+    }
+  } catch {}
+  if (strictBrainContainment) {
+    return null;
+  }
+  const normalized = rawStr.replace(/\\/g, "/");
   const brainMatch = normalized.match(/\/brain\/([^/]+)\//);
   if (brainMatch) return brainMatch[1];
   const logsMatch = normalized.match(/\/([^/]+)\/\.system_generated\/logs\//);
@@ -230,19 +251,53 @@ function hasActiveLaunchRestrictedSession() {
   return false;
 }
 
+export function canonicalizeTranscriptSubcommand(sub) {
+  const s = String(sub || "").trim().toLowerCase();
+  if (s === "read" || s === "outline" || s === "summary") return "read";
+  if (s === "query" || s === "grep" || s === "search" || s === "find" || s === "tools") return "query";
+  if (s === "step") return "step";
+  if (s === "health" || s === "stats" || s === "info") return "health";
+  if (s === "list" || s === "ls") return "list";
+  if (s === "resolve") return "resolve";
+  return s;
+}
+
+export function clearProcessTranscriptGrant() {
+  processVerifiedGrant = null;
+}
+
+export function consumeTranscriptAccessGrant() {
+  processVerifiedGrant = null;
+  try {
+    const store = readTranscriptAccessStore();
+    if (store.lastHookGrant) {
+      store.lastHookGrant = null;
+      writeTranscriptAccessStore(store);
+    }
+  } catch {}
+}
+
 /**
  * Defense-in-depth runtime verification inside transcript-core.mjs:
  * When any parent policy restriction or active launch-directive restriction exists,
- * verifies that PreToolUse issued a fresh (< 5s) capability grant for this operation.
+ * verifies that PreToolUse issued a fresh (< 10s), operation-bound single-use capability grant.
  */
-export function verifyTranscriptCoreAccess({ targetConvId = null, subcommand = "read" } = {}) {
+export function verifyTranscriptCoreAccess({
+  targetConvId = null,
+  subcommand = "read",
+  consumeGrant = true,
+  isImplicitCurrent = false
+} = {}) {
   const store = readTranscriptAccessStore();
   const activePolicies = Object.values(store.policies || {}).filter(
     (p) => p.mode !== "open" || (Array.isArray(p.deny) && p.deny.length > 0) || (Array.isArray(p.allow) && p.allow.length > 0)
   );
   const hasRestriction = activePolicies.length > 0 || hasActiveLaunchRestrictedSession();
   if (!hasRestriction) {
-    return { allowed: true, mode: "open" };
+    if (consumeGrant) {
+      processVerifiedGrant = null;
+    }
+    return { allowed: true, mode: "open", hasRestriction: false };
   }
 
   let grant = null;
@@ -257,29 +312,69 @@ export function verifyTranscriptCoreAccess({ targetConvId = null, subcommand = "
   }
 
   if (!grant) {
+    processVerifiedGrant = null;
     return {
       allowed: false,
+      hasRestriction: true,
       error:
         "Antigravity Execution Governance: Transcript access is currently restricted by parent governance policy; direct or unverified transcript-core invocation outside an authorized PreToolUse CLI call is blocked."
     };
   }
 
+  const reqCanon = canonicalizeTranscriptSubcommand(subcommand);
+  const grantCanon = canonicalizeTranscriptSubcommand(grant.subcommand);
+  if (!reqCanon || !grantCanon || reqCanon !== grantCanon) {
+    processVerifiedGrant = null;
+    return {
+      allowed: false,
+      hasRestriction: true,
+      error: `Antigravity Execution Governance: Capability grant subcommand mismatch (grant authorized '${grant.subcommand}', but '${subcommand}' was requested).`
+    };
+  }
+
   if (grant.mode === "self-only") {
-    if (subcommand === "list" || subcommand === "ls") {
+    if (reqCanon === "list") {
+      processVerifiedGrant = null;
       return {
         allowed: false,
+        hasRestriction: true,
         error: `Antigravity Execution Governance: 'agy-context transcript ${subcommand}' is disabled in self-only mode (caller: ${grant.callerConvId}).`
       };
     }
-    if (targetConvId && grant.callerConvId && grant.callerConvId !== "global" && targetConvId !== grant.callerConvId) {
+    if (targetConvId !== null && (!grant.callerConvId || grant.callerConvId === "global" || targetConvId !== grant.callerConvId)) {
+      processVerifiedGrant = null;
       return {
         allowed: false,
+        hasRestriction: true,
         error: `Antigravity Execution Governance: Cross-session transcript inspection of '${targetConvId}' is disabled in self-only mode (caller: ${grant.callerConvId}).`
       };
     }
   }
 
-  return { allowed: true, mode: grant.mode || "open", callerConvId: grant.callerConvId };
+  if (targetConvId !== null && grant.targetConvId) {
+    const isGrantCurrent = String(grant.targetConvId).toLowerCase() === "current";
+    if (isGrantCurrent ? !isImplicitCurrent : targetConvId !== grant.targetConvId) {
+      processVerifiedGrant = null;
+      return {
+        allowed: false,
+        hasRestriction: true,
+        error: `Antigravity Execution Governance: Capability grant target mismatch (grant authorized '${grant.targetConvId}', but '${targetConvId}' was requested).`
+      };
+    }
+  }
+
+  if (consumeGrant) {
+    processVerifiedGrant = null;
+  }
+
+  return {
+    allowed: true,
+    hasRestriction: true,
+    mode: grant.mode || "open",
+    callerConvId: grant.callerConvId,
+    targetConvId: grant.targetConvId || null,
+    subcommand: grant.subcommand || null
+  };
 }
 
 export function formatTranscriptAccessStatus(store = null) {
@@ -452,7 +547,10 @@ function isContainedInDir(targetPath, parentDir) {
   const realTarget = realOrNull(targetPath);
   const realParent = realOrNull(parentDir);
   if (!realTarget || !realParent) return false;
-  return realTarget === realParent || realTarget.startsWith(realParent + path.sep);
+  const norm = (p) => (os.platform() === "win32" ? p.toLowerCase() : p);
+  const nt = norm(realTarget);
+  const np = norm(realParent);
+  return nt === np || nt.startsWith(np.endsWith(path.sep) ? np : np + path.sep);
 }
 
 function siblingModePath(filePath, mode) {
@@ -510,51 +608,109 @@ function scanBrainTranscripts(brainDir) {
  *   inside `realpath(getBrainDir())`.
  */
 export function resolveTranscriptPath(target, mode = "compact", options = {}) {
-  const { explicitFile = null, allowExternalPaths = false } = options;
+  const {
+    explicitFile = null,
+    allowExternalPaths = false,
+    subcommand = "read",
+    retainGrantForFallback = false
+  } = options;
   const isFull = mode === "full";
   const fileName = isFull ? "transcript_full.jsonl" : "transcript.jsonl";
   const brainDir = getBrainDir();
 
-  const preAccess = verifyTranscriptCoreAccess({ subcommand: "resolve" });
+  const hasExplicitFile = explicitFile !== null && explicitFile !== undefined && String(explicitFile).trim() !== "";
+  const rawTargetInput = String(target || "").trim();
+  const isImplicitCurrent = !hasExplicitFile && (!rawTargetInput || rawTargetInput.toLowerCase() === "current");
+
+  const preAccess = verifyTranscriptCoreAccess({ subcommand, consumeGrant: false, isImplicitCurrent });
   if (!preAccess.allowed) {
-    return { error: preAccess.error };
+    return { error: preAccess.error, isGovernanceError: true };
   }
 
+  const failResolution = (errorMsg, extra = {}) => {
+    if (!retainGrantForFallback) {
+      consumeTranscriptAccessGrant();
+    }
+    return { error: errorMsg, ...extra };
+  };
+
+  const enforceResolvedFileContainment = (candidatePath) => {
+    if (preAccess.mode === "self-only") {
+      const selfBrainDir = path.join(brainDir, String(preAccess.callerConvId || ""));
+      if (!preAccess.callerConvId || preAccess.callerConvId === "global" || !isContainedInDir(candidatePath, selfBrainDir)) {
+        return failResolution(
+          `Antigravity Execution Governance: Cross-session '--file' access outside '${preAccess.callerConvId}' is disabled in self-only mode.`,
+          { isGovernanceError: true }
+        );
+      }
+    } else if (preAccess.hasRestriction && !isContainedInDir(candidatePath, brainDir)) {
+      return failResolution(
+        `Security containment error: '--file' path '${candidatePath}' escapes brain directory '${brainDir}' while a transcript access policy is active.`,
+        { isGovernanceError: true }
+      );
+    }
+    return null;
+  };
+
   const finalizeResolution = (filePath, convId) => {
-    const postAccess = verifyTranscriptCoreAccess({ targetConvId: convId, subcommand: "resolve" });
+    if (preAccess.hasRestriction && !convId) {
+      return failResolution(
+        `Security containment error: unable to derive a valid conversation directory inside '${brainDir}' for '${filePath}'.`,
+        { isGovernanceError: true }
+      );
+    }
+    const postAccess = verifyTranscriptCoreAccess({
+      targetConvId: convId,
+      subcommand,
+      consumeGrant: !retainGrantForFallback,
+      isImplicitCurrent
+    });
     if (!postAccess.allowed) {
-      return { error: postAccess.error };
+      return { error: postAccess.error, isGovernanceError: true };
     }
     return { filePath, convId };
   };
 
   // 0. Explicit --file operator path
-  if (explicitFile !== null && explicitFile !== undefined && String(explicitFile).trim() !== "") {
+  if (hasExplicitFile) {
     const fileStr = String(explicitFile).trim();
     if (!fileStr.toLowerCase().endsWith(".jsonl")) {
-      return { error: `Invalid --file path '${fileStr}': explicit transcript file must end with .jsonl.` };
+      return failResolution(`Invalid --file path '${fileStr}': explicit transcript file must end with .jsonl.`);
     }
     const resolvedFile = path.resolve(fileStr);
     if (!fs.existsSync(resolvedFile)) {
-      return { error: `Transcript file not found at --file path: '${resolvedFile}'.` };
+      return failResolution(`Transcript file not found at --file path: '${resolvedFile}'.`);
     }
     const realFile = realOrNull(resolvedFile);
     if (!realFile) {
-      return { error: `Unable to resolve realpath for --file path: '${resolvedFile}'.` };
+      return failResolution(`Unable to resolve realpath for --file path: '${resolvedFile}'.`);
     }
     try {
       if (!fs.statSync(realFile).isFile()) {
-        return { error: `Invalid --file path '${resolvedFile}': target is not a regular file.` };
+        return failResolution(`Invalid --file path '${resolvedFile}': target is not a regular file.`);
       }
     } catch (err) {
-      return { error: `Unable to stat --file path '${resolvedFile}': ${err.message}` };
+      return failResolution(`Unable to stat --file path '${resolvedFile}': ${err.message}`);
     }
-    const finalPath = siblingModePath(realFile, mode);
-    return finalizeResolution(finalPath, extractConvId(finalPath));
+    const modeCandidate = siblingModePath(realFile, mode);
+    const finalPath = realOrNull(modeCandidate) || modeCandidate;
+    try {
+      if (!fs.statSync(finalPath).isFile()) {
+        return failResolution(`Invalid --file path '${finalPath}': target is not a regular file.`);
+      }
+    } catch (err) {
+      return failResolution(`Unable to stat --file path '${finalPath}': ${err.message}`);
+    }
+    const containmentErr = enforceResolvedFileContainment(finalPath);
+    if (containmentErr) return containmentErr;
+    return finalizeResolution(
+      finalPath,
+      extractConvId(finalPath, { strictBrainContainment: preAccess.hasRestriction })
+    );
   }
 
   // 1. Omitted or "current": check GEMINI_CONVERSATION_ID, else scan <brainDir> with active-swarm disambiguation
-  let raw = String(target || "").trim();
+  let raw = rawTargetInput;
   if (!raw || raw.toLowerCase() === "current") {
     if (process.env.GEMINI_CONVERSATION_ID && process.env.GEMINI_CONVERSATION_ID.trim()) {
       raw = process.env.GEMINI_CONVERSATION_ID.trim();
@@ -569,76 +725,93 @@ export function resolveTranscriptPath(target, mode = "compact", options = {}) {
         const listing = recent
           .map((c) => `- ${c.convId} (modified ${Math.max(0, Math.round((now - c.mtimeMs) / 1000))}s ago)`)
           .join("\n");
-        return {
-          error: `Ambiguous active conversation: ${recent.length} transcripts in ${brainDir} were modified in the last 5 minutes (active swarm). Specify an explicit --id <uuid>:\n${listing}`,
-          candidates: recent.map((c) => c.convId)
-        };
+        return failResolution(
+          `Ambiguous active conversation: ${recent.length} transcripts in ${brainDir} were modified in the last 5 minutes (active swarm). Specify an explicit --id <uuid>:\n${listing}`,
+          { candidates: recent.map((c) => c.convId) }
+        );
       }
       if (recent.length === 1) {
         raw = recent[0].convId;
       } else if (candidates.length > 0) {
         raw = candidates[0].convId;
       } else {
-        return { error: `No conversation transcripts found in brain directory: ${brainDir}. Specify --id <uuid> or --file <path>.` };
+        return failResolution(
+          `No conversation transcripts found in brain directory: ${brainDir}. Specify --id <uuid> or --file <path>.`
+        );
       }
     }
   }
 
   // 2. Reject path traversal / external path tokens in --id unless allowExternalPaths is explicitly enabled
   const normalized = raw.replace(/\\/g, "/");
-  if (!allowExternalPaths) {
+  if (!allowExternalPaths || preAccess.hasRestriction) {
     if (raw.includes("\0") || raw.includes("..") || raw.includes("/") || raw.includes("\\") || normalized.endsWith(".jsonl")) {
-      return {
-        error: `Invalid conversation ID '${raw}': must be a bare conversation UUID/folder inside ${brainDir}. Use --file <path> for explicit external .jsonl files.`
-      };
+      return failResolution(
+        `Invalid conversation ID '${raw}': must be a bare conversation UUID/folder inside ${brainDir}. Use --file <path> for explicit external .jsonl files.`
+      );
     }
   }
 
-  // 3. Direct file path (legacy MCP compatibility when allowExternalPaths === true)
-  if (allowExternalPaths && normalized.endsWith(".jsonl") && fs.existsSync(normalized)) {
-    const finalPath = siblingModePath(normalized, mode);
-    return finalizeResolution(finalPath, extractConvId(finalPath));
+  // 3. Direct file path (legacy compatibility when allowExternalPaths === true and no restriction is active)
+  if (allowExternalPaths && !preAccess.hasRestriction && normalized.endsWith(".jsonl") && fs.existsSync(normalized)) {
+    const modeCandidate = siblingModePath(normalized, mode);
+    const finalPath = realOrNull(modeCandidate) || modeCandidate;
+    const containmentErr = enforceResolvedFileContainment(finalPath);
+    if (containmentErr) return containmentErr;
+    return finalizeResolution(
+      finalPath,
+      extractConvId(finalPath, { strictBrainContainment: preAccess.hasRestriction })
+    );
   }
 
   // 4. UUID / Directory resolution under <brainDir>/<id>
-  const brainCandidate = path.join(brainDir, normalized, ".system_generated", "logs", fileName);
-  if (fs.existsSync(brainCandidate)) {
-    if (!allowExternalPaths && !isContainedInDir(brainCandidate, brainDir)) {
-      return { error: `Security containment error: resolved path '${brainCandidate}' escapes brain directory '${brainDir}'.` };
+  const expectedSessionDir = path.join(brainDir, normalized);
+  const checkBrainCandidate = (candidatePath) => {
+    const realCandidate = realOrNull(candidatePath);
+    if (!realCandidate) {
+      return failResolution(`Unable to resolve realpath for '${candidatePath}'.`);
     }
-    return finalizeResolution(realOrNull(brainCandidate) || brainCandidate, normalized);
+    if ((!allowExternalPaths || preAccess.hasRestriction) && (!isContainedInDir(realCandidate, brainDir) || !isContainedInDir(realCandidate, expectedSessionDir))) {
+      return failResolution(
+        `Security containment error: resolved path '${realCandidate}' escapes conversation directory '${expectedSessionDir}'.`,
+        { isGovernanceError: true }
+      );
+    }
+    const derivedConvId = extractConvId(realCandidate, { strictBrainContainment: preAccess.hasRestriction }) || normalized;
+    return finalizeResolution(realCandidate, derivedConvId);
+  };
+
+  const brainCandidate = path.join(expectedSessionDir, ".system_generated", "logs", fileName);
+  if (fs.existsSync(brainCandidate)) {
+    return checkBrainCandidate(brainCandidate);
   }
   if (isFull) {
-    const compactFallback = path.join(brainDir, normalized, ".system_generated", "logs", "transcript.jsonl");
+    const compactFallback = path.join(expectedSessionDir, ".system_generated", "logs", "transcript.jsonl");
     if (fs.existsSync(compactFallback)) {
-      if (!allowExternalPaths && !isContainedInDir(compactFallback, brainDir)) {
-        return { error: `Security containment error: resolved path '${compactFallback}' escapes brain directory '${brainDir}'.` };
-      }
-      return finalizeResolution(realOrNull(compactFallback) || compactFallback, normalized);
+      return checkBrainCandidate(compactFallback);
     }
   } else {
-    const fullFallback = path.join(brainDir, normalized, ".system_generated", "logs", "transcript_full.jsonl");
+    const fullFallback = path.join(expectedSessionDir, ".system_generated", "logs", "transcript_full.jsonl");
     if (fs.existsSync(fullFallback)) {
-      if (!allowExternalPaths && !isContainedInDir(fullFallback, brainDir)) {
-        return { error: `Security containment error: resolved path '${fullFallback}' escapes brain directory '${brainDir}'.` };
-      }
-      return finalizeResolution(realOrNull(fullFallback) || fullFallback, normalized);
+      return checkBrainCandidate(fullFallback);
     }
   }
 
-  // 5. Legacy local relative/absolute directory path (only when allowExternalPaths === true)
-  if (allowExternalPaths) {
+  // 5. Legacy local relative/absolute directory path (only when allowExternalPaths === true and no restriction is active)
+  if (allowExternalPaths && !preAccess.hasRestriction) {
     const localCandidate = path.resolve(normalized, ".system_generated", "logs", fileName);
     if (fs.existsSync(localCandidate)) {
-      return finalizeResolution(localCandidate, extractConvId(localCandidate));
+      const realLocal = realOrNull(localCandidate) || localCandidate;
+      return finalizeResolution(realLocal, extractConvId(realLocal));
     }
     const directCandidate = path.resolve(normalized, fileName);
     if (fs.existsSync(directCandidate)) {
-      return finalizeResolution(directCandidate, extractConvId(directCandidate));
+      const realDirect = realOrNull(directCandidate) || directCandidate;
+      return finalizeResolution(realDirect, extractConvId(realDirect));
     }
   }
 
-  return { error: `Transcript not found for target: '${target}'. Searched: ${brainCandidate}` };
+  return failResolution(`Transcript not found for target: '${target}'. Searched: ${brainCandidate}`);
 }
 
 function isUrlTokenAtOffset(str, offset) {
@@ -1011,7 +1184,11 @@ export async function readTranscript({
   includeThinking = false,
   allowExternalPaths = false
 } = {}) {
-  const resolved = resolveTranscriptPath(conversationId, mode, { explicitFile, allowExternalPaths });
+  const resolved = resolveTranscriptPath(conversationId, mode, {
+    explicitFile,
+    allowExternalPaths,
+    subcommand: "read"
+  });
   if (resolved.error) {
     return { isError: true, text: resolved.error, error: resolved.error, candidates: resolved.candidates };
   }
@@ -1400,19 +1577,41 @@ export async function getStepDetail({
 } = {}) {
   const parsedSelector = parseStepSelector(stepIndex, startStep, endStep);
   if (parsedSelector.error) {
+    consumeTranscriptAccessGrant();
     return { isError: true, text: parsedSelector.error, error: parsedSelector.error };
   }
 
   const { indices, isMulti } = parsedSelector;
   const targetSet = new Set(indices);
 
-  const resolvedFull = resolveTranscriptPath(conversationId, "full", { explicitFile, allowExternalPaths });
-  if (resolvedFull.error && explicitFile) {
-    return { isError: true, text: resolvedFull.error, error: resolvedFull.error, candidates: resolvedFull.candidates };
+  let resolvedFull;
+  let resolvedCompact;
+  try {
+    resolvedFull = resolveTranscriptPath(conversationId, "full", {
+      explicitFile,
+      allowExternalPaths,
+      subcommand: "step",
+      retainGrantForFallback: true
+    });
+    if (resolvedFull.error && (explicitFile || resolvedFull.isGovernanceError)) {
+      return { isError: true, text: resolvedFull.error, error: resolvedFull.error, candidates: resolvedFull.candidates };
+    }
+    resolvedCompact = resolveTranscriptPath(conversationId, "compact", {
+      explicitFile,
+      allowExternalPaths,
+      subcommand: "step",
+      retainGrantForFallback: false
+    });
+  } finally {
+    consumeTranscriptAccessGrant();
+  }
+
+  if (resolvedCompact.error && !resolvedFull.filePath) {
+    return { isError: true, text: resolvedCompact.error, error: resolvedCompact.error, candidates: resolvedCompact.candidates };
   }
 
-  let usedConvId = resolvedFull.convId;
-  let usedFilePath = resolvedFull.filePath;
+  let usedConvId = resolvedFull.convId || resolvedCompact.convId;
+  let usedFilePath = resolvedFull.filePath || resolvedCompact.filePath;
   const foundMap = new Map();
 
   if (resolvedFull && resolvedFull.filePath && fs.existsSync(resolvedFull.filePath)) {
@@ -1424,17 +1623,12 @@ export async function getStepDetail({
 
   if (foundMap.size < targetSet.size) {
     const missingSet = new Set(indices.filter((idx) => !foundMap.has(idx)));
-    const resolvedCompact = resolveTranscriptPath(conversationId, "compact", { explicitFile, allowExternalPaths });
-    if (resolvedCompact.error && !resolvedFull.filePath) {
-      return { isError: true, text: resolvedCompact.error, error: resolvedCompact.error, candidates: resolvedCompact.candidates };
-    }
     if (
       resolvedCompact &&
       resolvedCompact.filePath &&
       resolvedCompact.filePath !== resolvedFull.filePath &&
       fs.existsSync(resolvedCompact.filePath)
     ) {
-      usedConvId = usedConvId || resolvedCompact.convId;
       if (foundMap.size === 0) usedFilePath = resolvedCompact.filePath;
       const compactMatches = await batchFindFullSteps(resolvedCompact.filePath, missingSet);
       for (const [k, v] of compactMatches.entries()) {
@@ -1527,13 +1721,27 @@ export async function queryTranscript(args = {}) {
     summaryOnly = false,
     stepIndex,
     field,
-    allowExternalPaths = false
+    allowExternalPaths = false,
+    subcommand = "query"
   } = args;
 
-  if (stepIndex !== undefined && stepIndex !== null) {
-    return getStepDetail({ conversationId, filePath: explicitFile, stepIndex, startStep, endStep, field, allowExternalPaths });
+    if (stepIndex !== undefined && stepIndex !== null) {
+    return getStepDetail({
+      conversationId,
+      filePath: explicitFile,
+      stepIndex,
+      startStep,
+      endStep,
+      field,
+      allowExternalPaths
+    });
   }
 
+  const effectiveSubcommand =
+    canonicalizeTranscriptSubcommand(subcommand) === "read" && Boolean(summaryOnly) && !query
+      ? "read"
+      : "query";
+
   const normalizedField = field ? String(field).trim() : null;
   const fieldImpliesTools = Boolean(
     normalizedField === "tool_args" ||
@@ -1545,16 +1753,29 @@ export async function queryTranscript(args = {}) {
 
   const resolved = resolveTranscriptPath(conversationId, mode === "full" ? "full" : "compact", {
     explicitFile,
-    allowExternalPaths
+    allowExternalPaths,
+    subcommand: effectiveSubcommand
   });
   if (resolved.error) {
     return { isError: true, text: resolved.error, error: resolved.error, candidates: resolved.candidates };
   }
 
   const { filePath, convId } = resolved;
-  const fullSiblingPath = filePath.endsWith("transcript_full.jsonl")
+  const verifiedParentDir = path.dirname(realOrNull(filePath) || filePath);
+  const rawFullSiblingPath = filePath.endsWith("transcript_full.jsonl")
     ? filePath
     : filePath.replace(/transcript\.jsonl$/, "transcript_full.jsonl");
+  let fullSiblingPath = null;
+  if (rawFullSiblingPath === filePath) {
+    fullSiblingPath = filePath;
+  } else if (fs.existsSync(rawFullSiblingPath)) {
+    const realSibling = realOrNull(rawFullSiblingPath);
+    try {
+      if (realSibling && fs.statSync(realSibling).isFile() && isContainedInDir(realSibling, verifiedParentDir)) {
+        fullSiblingPath = realSibling;
+      }
+    } catch {}
+  }
 
   const roleList = Array.isArray(roles)
     ? roles
@@ -1605,7 +1826,7 @@ export async function queryTranscript(args = {}) {
 
   const flushTruncatedCandidates = async (batchIndices) => {
     if (batchIndices.length === 0 || mode !== "auto") return;
-    if (!fs.existsSync(fullSiblingPath)) return;
+    if (!fullSiblingPath || !fs.existsSync(fullSiblingPath)) return;
     const fullMap = await batchFindFullSteps(fullSiblingPath, new Set(batchIndices));
     for (const stepIdx of batchIndices) {
       const fullItem = fullMap.get(stepIdx);
@@ -1747,7 +1968,7 @@ export async function queryTranscript(args = {}) {
     : mergedItems;
 
   // Auto-dereferencing for full rendering mode (or when fullArgs / field requires untruncated tool calls)
-  if (mode === "auto" && (!summaryOnly || effectiveFullArgs || normalizedField) && filePath !== fullSiblingPath) {
+  if (mode === "auto" && (!summaryOnly || effectiveFullArgs || normalizedField) && fullSiblingPath && filePath !== fullSiblingPath) {
     const hydrateIndices = new Set();
     for (const it of finalItems) {
       if (it.step_index === undefined) continue;
@@ -1918,9 +2139,10 @@ export async function checkContextHealth({
   allowExternalPaths = false
 } = {}) {
   const resolved = explicitFile
-    ? resolveTranscriptPath(null, "compact", { explicitFile, allowExternalPaths })
+    ? resolveTranscriptPath(null, "compact", { explicitFile, allowExternalPaths, subcommand: "health" })
     : resolveTranscriptPath(transcriptPath || conversationId || "current", "compact", {
-        allowExternalPaths: allowExternalPaths || Boolean(transcriptPath)
+        allowExternalPaths: allowExternalPaths || Boolean(transcriptPath),
+        subcommand: "health"
       });
 
   if (resolved.error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agy-context-saver",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "PreToolUse execution hook and transcript CLI (agy-context) for Google Antigravity, paired with RTK",
   "main": "lib/transcript-core.mjs",
   "bin": {

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agy-context-saver",
   "displayName": "Agy-Context-Saver",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "PreToolUse execution hook, background polling governor, and transcript CLI (agy-context) for Google Antigravity, paired with RTK.",
   "logo": "assets/logo.svg",
   "suggestedPrompts": [

package/scripts/execution-guard-hook.mjs

@@ -2212,13 +2212,42 @@ function checkAgyContextTranscriptCommand(segments, convId = "global") {
       };
     }
 
+    let resolvedTargetConvId = targetInfo.targetId || null;
+    if (targetInfo.explicitFile) {
+      if (accessEval.ownerId && !accessEval.isOwner && !isPathInsideDir(targetInfo.explicitFile, getBrainDir())) {
+        return {
+          matched: true,
+          allowed: false,
+          isAccessDenial: true,
+          reason: buildTranscriptAccessDenial({
+            subcommand,
+            mode: accessEval.mode,
+            source: accessEval.source,
+            callerConvId: convId,
+            rosterName: accessEval.rosterName,
+            detail: `'--file' paths outside '${getBrainDir()}' are disabled while a parent transcript access policy is active.`
+          })
+        };
+      }
+      if (isPathInsideDir(targetInfo.explicitFile, getBrainDir())) {
+        const rel = path.relative(
+          tryRealpath(path.resolve(getBrainDir())),
+          tryRealpath(path.resolve(targetInfo.explicitFile))
+        );
+        const firstSeg = rel.split(path.sep)[0];
+        if (firstSeg && firstSeg !== "." && firstSeg !== "..") {
+          resolvedTargetConvId = firstSeg;
+        }
+      }
+    }
+
     return {
       matched: true,
       allowed: true,
       subcommand,
       mode: "open",
       needsReadGrant: true,
-      targetConvId: targetInfo.targetId || null
+      targetConvId: resolvedTargetConvId
     };
   }
 

package/scripts/install-register.mjs

@@ -23,6 +23,13 @@ import { formatTranscriptAccessStatus } from "../lib/transcript-core.mjs";
 const fsPromises = fs.promises;
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const repoRoot = path.resolve(__dirname, "..");
+const PACKAGE_VERSION = (() => {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(repoRoot, "package.json"), "utf8")).version || "2.0.1";
+  } catch {
+    return "2.0.1";
+  }
+})();
 
 const homeDir = process.env.AGY_TEST_PROFILE_DIR || os.homedir();
 const geminiConfigDir = path.join(homeDir, ".gemini", "config");
@@ -455,9 +462,9 @@ export async function runInstall(options = {}) {
     if (existing.details.cliShim.exists) {
       log(`   [OK] CLI Shims (agy-context): Installed in ${antigravityBinDir}`);
     }
-    log("\nRe-verifying and synchronizing to v2.0.0...");
+    log(`\nRe-verifying and synchronizing to v${PACKAGE_VERSION}...`);
   } else {
-    log("Fresh installation of Agy-Context-Saver v2.0.0...");
+    log(`Fresh installation of Agy-Context-Saver v${PACKAGE_VERSION}...`);
   }
 
   // 0. Pre-flight Validation: Verify configuration directory write access
@@ -779,7 +786,7 @@ export {
 
 function printCliHelp() {
   console.log(`
-Agy-Context-Saver Registration & Lifecycle Engine (v2.0.0)
+Agy-Context-Saver Registration & Lifecycle Engine (v${PACKAGE_VERSION})
 
 Usage:
   node scripts/install-register.mjs [command/option]
@@ -791,7 +798,7 @@ Commands & Options:
   --restore-backups            Restore original configuration backup files (*.bak) (standalone or during uninstall)
   --allow-degraded             Allow installation to proceed even if RTK optimizer provisioning fails
   --help, -h, help             Show this help message
-  (no arguments)               Synchronize and verify v2.0.0 CLI-first installation
+  (no arguments)               Synchronize and verify v${PACKAGE_VERSION} CLI-first installation
 `);
 }
 

package/scripts/provision-rtk.mjs

@@ -13,9 +13,15 @@ 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. Empty until verified v1.1.0 hashes are pinned;
-// ensureRtkInstalled fails closed with manual install instructions when an asset hash is absent.
-export const RTK_CHECKSUMS = {};
+// 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": "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) {
   if (!versionStr || typeof versionStr !== "string") return false;

package/scripts/release-preflight.mjs

@@ -44,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],