agy-context-saver 1.5.0 → 1.6.0

package/scripts/install-register.mjs

@@ -22,7 +22,7 @@ const fsPromises = fs.promises;
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const repoRoot = path.resolve(__dirname, "..");
 
-const homeDir = os.homedir();
+const homeDir = process.env.AGY_TEST_PROFILE_DIR || os.homedir();
 const geminiConfigDir = path.join(homeDir, ".gemini", "config");
 const pluginsDir = path.join(geminiConfigDir, "plugins");
 const pluginDest = path.join(pluginsDir, "agy-context-saver");
@@ -138,13 +138,62 @@ export function detectExistingInstallation() {
   };
 }
 
+export function parseAndValidateJsonConfig(filePath, configName) {
+  if (!fs.existsSync(filePath)) return null;
+  const content = fs.readFileSync(filePath, "utf-8");
+  let parsed;
+  try {
+    parsed = JSON.parse(content);
+  } catch (err) {
+    throw new Error(`Configuration error: ${filePath} contains invalid JSON (${err.message}). Installation aborted to prevent data loss. Original file is unchanged.`);
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new Error(`Configuration error: ${filePath} must contain a JSON object, but found ${parsed === null ? "null" : Array.isArray(parsed) ? "array" : typeof parsed}. Installation aborted to prevent data loss. Original file is unchanged.`);
+  }
+  if (configName === "mcp" && parsed.mcpServers !== undefined) {
+    if (typeof parsed.mcpServers !== "object" || parsed.mcpServers === null || Array.isArray(parsed.mcpServers)) {
+      throw new Error(`Configuration error: ${filePath} property "mcpServers" must be a JSON object. Installation aborted to prevent data loss. Original file is unchanged.`);
+    }
+  }
+  return parsed;
+}
+
 export async function runInstall(options = {}) {
   const log = options.silent ? () => {} : console.log;
   const warn = options.silent ? () => {} : console.warn;
 
   const startTime = performance.now();
+
+  // Pre-flight Fail-Closed Validation: Verify existing configs BEFORE ANY DISK MUTATION OR CHECK RETURN
+  const validatedHooks = parseAndValidateJsonConfig(hooksJsonPath, "hooks");
+  const validatedMcp = parseAndValidateJsonConfig(mcpJsonPath, "mcp");
+
   const existing = detectExistingInstallation();
 
+  // If checkOnly is requested, execute strictly read-only inspection (zero disk writes, zero network calls)
+  if (options.checkOnly) {
+    if (existing.isInstalled) {
+      log("🔍 Existing installation detected:");
+      if (existing.details.plugin.exists) {
+        log(`   ✓ Native Plugin Link: ${pluginDest}`);
+      }
+      if (existing.details.hook.registered) {
+        log(`   ✓ Governor Hook: Registered in ${hooksJsonPath}`);
+      }
+      if (existing.details.mcp.registered) {
+        log(`   ✓ Universal MCP Server: Configured in ${mcpJsonPath}`);
+      }
+      if (existing.details.schemas.exists) {
+        log(`   ✓ Antigravity Tool Schemas: Present in ${antigravityMcpDir}`);
+      }
+      log("\n[OK] Pre-flight check complete. Installation is active.");
+    } else {
+      log("🔍 Pre-flight check: No active installation detected (clean profile).");
+      log("\n[OK] Pre-flight check complete. Zero changes written.");
+    }
+    return existing;
+  }
+
   if (existing.isInstalled) {
     log("🔍 Existing installation detected:");
     if (existing.details.plugin.exists) {
@@ -159,11 +208,6 @@ export async function runInstall(options = {}) {
     if (existing.details.schemas.exists) {
       log(`   ✓ Antigravity Tool Schemas: Present in ${antigravityMcpDir}`);
     }
-
-    if (options.checkOnly) {
-      log("\n[OK] Pre-flight check complete. Installation is active.");
-      return existing;
-    }
     log("\n⚡ Re-verifying and synchronizing to latest version...");
   } else {
     log("⚡ Fresh installation of Agy-Context-Saver (Zero-Delay Mode)...");
@@ -184,17 +228,27 @@ export async function runInstall(options = {}) {
     const rtkResult = await ensureRtkInstalled({ silent: options.silent, existingRtk: existing.details.rtk });
     log(`[OK] RTK Command Optimizer verified: ${rtkResult.version} (${rtkResult.path})`);
   } catch (err) {
-    warn(`[WARN] RTK provisioning check encountered an issue: ${err.message}`);
+    if (options.allowDegraded) {
+      warn(`[WARN] RTK provisioning check encountered an issue: ${err.message}. Continuing in degraded mode.`);
+    } else {
+      throw new Error(`RTK provisioning failed: ${err.message}. To install without RTK (degraded mode), re-run with --allow-degraded.`);
+    }
   }
 
   // 1. Instant Native Plugin Junction / Symlink or Permanent Copy (Takes ~5ms)
   await fsPromises.mkdir(pluginsDir, { recursive: true });
   const isGitRepo = fs.existsSync(path.join(repoRoot, ".git"));
   const isTempOrNpx = !isGitRepo || repoRoot.includes("_npx") || repoRoot.includes("npm-cache") || repoRoot.includes("node_modules");
+  const copyFilter = (src) => {
+    const rel = path.relative(repoRoot, src);
+    if (!rel) return true;
+    const topSegment = rel.split(path.sep)[0];
+    return ![".git", "node_modules", ".venv", "scratch", "site"].includes(topSegment);
+  };
 
   if (!fs.existsSync(pluginDest)) {
-    if (isTempOrNpx) {
-      await fsPromises.cp(repoRoot, pluginDest, { recursive: true });
+    if (isTempOrNpx || options.forceCopyFallback) {
+      await fsPromises.cp(repoRoot, pluginDest, { recursive: true, filter: copyFilter });
       log(`[OK] Native Antigravity Plugin installed to: ${pluginDest}`);
     } else {
       try {
@@ -202,14 +256,14 @@ export async function runInstall(options = {}) {
         fs.symlinkSync(repoRoot, pluginDest, isWin ? "junction" : "dir");
         log(`[OK] Native Antigravity Plugin linked: ${pluginDest} -> ${repoRoot}`);
       } catch (err) {
-        await fsPromises.cp(repoRoot, pluginDest, { recursive: true });
+        await fsPromises.cp(repoRoot, pluginDest, { recursive: true, filter: copyFilter });
         log(`[OK] Native Antigravity Plugin copied to: ${pluginDest}`);
       }
     }
   } else {
-    if (isTempOrNpx) {
+    if (isTempOrNpx || options.forceCopyFallback) {
       try {
-        await fsPromises.cp(repoRoot, pluginDest, { recursive: true });
+        await fsPromises.cp(repoRoot, pluginDest, { recursive: true, filter: copyFilter });
       } catch {}
     }
     log(`[OK] Native Antigravity Plugin verified: ${pluginDest}`);
@@ -221,21 +275,20 @@ export async function runInstall(options = {}) {
   log(`[OK] Governor hook script mirrored to: ${destHook}${hookUpdated ? "" : " (up-to-date)"}`);
 
   // 3. Register Hook in ~/.gemini/config/hooks.json (Preserves existing hooks + creates backup)
-  let hooksConfig = {};
-  if (fs.existsSync(hooksJsonPath)) {
+  let hooksConfig = validatedHooks ? { ...validatedHooks } : {};
+  if (fs.existsSync(hooksJsonPath) && !fs.existsSync(hooksBakPath)) {
     try {
-      hooksConfig = JSON.parse(fs.readFileSync(hooksJsonPath, "utf-8"));
-      // Create backup if none exists
-      if (!fs.existsSync(hooksBakPath)) {
-        await fsPromises.copyFile(hooksJsonPath, hooksBakPath);
-        log(`[OK] Created configuration backup: ${hooksBakPath}`);
-      }
+      await fsPromises.copyFile(hooksJsonPath, hooksBakPath);
+      log(`[OK] Created configuration backup: ${hooksBakPath}`);
     } catch (err) {
-      hooksConfig = {};
+      warn(`[WARN] Could not create backup of ${hooksJsonPath}: ${err.message}`);
     }
   }
 
   const alreadyHadHook = Boolean(hooksConfig["execution-guard"]);
+  if (hooksConfig["agy-context-saver"]) {
+    delete hooksConfig["agy-context-saver"];
+  }
   hooksConfig["execution-guard"] = {
     PreToolUse: [
       {
@@ -254,18 +307,18 @@ export async function runInstall(options = {}) {
   log(`[OK] Lifecycle hook ${alreadyHadHook ? "re-verified" : "registered"} in: ${hooksJsonPath}${hooksUpdated ? "" : " (up-to-date)"}`);
 
   // 4. Register MCP Server in ~/.gemini/config/mcp_config.json (Preserves existing servers + creates backup)
-  let mcpConfig = { mcpServers: {} };
-  if (fs.existsSync(mcpJsonPath)) {
+  let mcpConfig = validatedMcp ? { ...validatedMcp } : { mcpServers: {} };
+  if (!mcpConfig.mcpServers || typeof mcpConfig.mcpServers !== "object") {
+    mcpConfig.mcpServers = {};
+  } else {
+    mcpConfig.mcpServers = { ...mcpConfig.mcpServers };
+  }
+  if (fs.existsSync(mcpJsonPath) && !fs.existsSync(mcpBakPath)) {
     try {
-      mcpConfig = JSON.parse(fs.readFileSync(mcpJsonPath, "utf-8"));
-      if (!mcpConfig.mcpServers) mcpConfig.mcpServers = {};
-      // Create backup if none exists
-      if (!fs.existsSync(mcpBakPath)) {
-        await fsPromises.copyFile(mcpJsonPath, mcpBakPath);
-        log(`[OK] Created configuration backup: ${mcpBakPath}`);
-      }
+      await fsPromises.copyFile(mcpJsonPath, mcpBakPath);
+      log(`[OK] Created configuration backup: ${mcpBakPath}`);
     } catch (err) {
-      mcpConfig = { mcpServers: {} };
+      warn(`[WARN] Could not create backup of ${mcpJsonPath}: ${err.message}`);
     }
   }
 
@@ -318,7 +371,7 @@ Agy-Context-Saver is the universal Model Context Protocol server and lifecycle g
 
 ## Available MCP Tools
 - \`check_context_health\`: Diagnoses transcript turn counts, byte payload, and polling loops. Accepts \`transcriptPath\` or \`conversationId\`.
-- \`subagent_brief\`: Generates scope-isolated instructions for delegated subagents with Pointer-Over-Wire delivery contract.
+- \`subagent_brief\`: Formulates scope-isolated prompts and ready-to-use invoke_subagent JSON payloads for single or multiple delegated subagents with Pointer-Over-Wire delivery contract.
 - \`read_transcript\`: Streams recent turns from \`transcript.jsonl\` or \`transcript_full.jsonl\` formatted as clean Markdown.
 - \`query_transcript\`: Forensic regex search and filtering engine across transcript steps with optional \`summaryOnly: true\`, and surgical step extraction via \`stepIndex\` and \`field\`.
 - \`get_installation_status\`: Audits live health of the plugin link, hook, MCP server, tool schemas, and RTK.
@@ -351,15 +404,37 @@ Agy-Context-Saver is the universal Model Context Protocol server and lifecycle g
 
   const subagentBriefSchema = {
     name: "subagent_brief",
-    description: "Generates a scope-isolated, anti-bloat prompt for invoking a subagent. Instructs the subagent to absorb all intermediate file reads/searches and return only high-signal findings.",
+    description: "Generates scope-isolated, anti-bloat prompts and ready-to-use invoke_subagent JSON payloads for single or multiple delegated subagents. Instructs subagents to absorb intermediate file reads/searches and return only high-signal findings.",
     parameters: {
       type: "object",
       properties: {
-        objective: { type: "string", description: "The core research or investigative objective." },
+        objective: { type: "string", description: "The core research or investigative objective (for single subagent)." },
+        role: { type: "string", description: "2-5 word role description (e.g. 'Comprehensive Test Engineer', 'Codebase Security Auditor'). Defaults to 'Scope-Isolated Deep Research Subagent'." },
+        instructions: { type: "string", description: "Optional step-by-step instructions or specialized directives." },
         scopeFiles: { type: "array", items: { type: "string" }, description: "List of files or directories to investigate." },
-        expectedDeliverable: { type: "string", description: "The concise format expected back by the parent agent." }
-      },
-      required: ["objective"]
+        expectedDeliverable: { type: "string", description: "The concise format expected back by the parent agent." },
+        typeName: { type: "string", description: "Subagent type name: 'self' (default, inherits parent tools/prompt/model) or 'research' (read-only)." },
+        model: { type: "string", enum: ["inherit", "flash_lite", "flash", "pro"], description: "Model tier: 'inherit' (default), 'flash_lite', 'flash', or 'pro'." },
+        workspace: { type: "string", enum: ["inherit", "branch", "share"], description: "Workspace isolation: 'inherit' (default), 'branch', or 'share'." },
+        subagents: {
+          type: "array",
+          description: "Optional array of subagent configurations to formulate multiple subagents at once.",
+          items: {
+            type: "object",
+            properties: {
+              role: { type: "string", description: "2-5 word role description." },
+              objective: { type: "string", description: "The core objective for this subagent." },
+              instructions: { type: "string", description: "Optional step-by-step instructions." },
+              scopeFiles: { type: "array", items: { type: "string" }, description: "Files/directories to investigate." },
+              expectedDeliverable: { type: "string", description: "Expected deliverable format." },
+              typeName: { type: "string", description: "Subagent type name: 'self' or 'research'." },
+              model: { type: "string", enum: ["inherit", "flash_lite", "flash", "pro"], description: "Model tier." },
+              workspace: { type: "string", enum: ["inherit", "branch", "share"], description: "Workspace isolation." }
+            },
+            required: ["objective"]
+          }
+        }
+      }
     }
   };
 
@@ -494,7 +569,8 @@ Agy-Context-Saver is the universal Model Context Protocol server and lifecycle g
   const elapsed = (performance.now() - startTime).toFixed(1);
   const statusVerb = existing.isInstalled ? "synchronized & up-to-date" : "completed";
   log(`\n✓ Installation ${statusVerb} in ${elapsed}ms (Zero Delay)!\n`);
-  return { ...existing, isInstalled: true, elapsedMs: elapsed };
+  const postInstall = detectExistingInstallation();
+  return { ...postInstall, isInstalled: true, elapsedMs: elapsed };
 }
 
 export async function runUninstall(options = {}) {
@@ -557,25 +633,42 @@ export async function runUninstall(options = {}) {
 
   // 6. Optional: Restore configuration files from backups if requested
   if (options.restoreBackups) {
-    if (fs.existsSync(hooksBakPath)) {
-      try {
-        await fsPromises.copyFile(hooksBakPath, hooksJsonPath);
-        log(`[OK] Restored hooks.json from backup: ${hooksBakPath}`);
-      } catch (err) {
-        warn(`[WARN] Could not restore hooks backup: ${err.message}`);
-      }
+    await runRestoreBackups(options);
+  }
+
+  log("\n✓ Uninstallation complete.\n");
+}
+
+export async function runRestoreBackups(options = {}) {
+  const log = options.silent ? () => {} : console.log;
+  const warn = options.silent ? () => {} : console.warn;
+  let restoredCount = 0;
+
+  if (fs.existsSync(hooksBakPath)) {
+    try {
+      await fsPromises.copyFile(hooksBakPath, hooksJsonPath);
+      log(`[OK] Restored hooks.json from backup: ${hooksBakPath}`);
+      restoredCount++;
+    } catch (err) {
+      warn(`[WARN] Could not restore hooks backup: ${err.message}`);
     }
-    if (fs.existsSync(mcpBakPath)) {
-      try {
-        await fsPromises.copyFile(mcpBakPath, mcpJsonPath);
-        log(`[OK] Restored mcp_config.json from backup: ${mcpBakPath}`);
-      } catch (err) {
-        warn(`[WARN] Could not restore mcp backup: ${err.message}`);
-      }
+  } else {
+    log(`[INFO] No hooks.json backup found at ${hooksBakPath}`);
+  }
+
+  if (fs.existsSync(mcpBakPath)) {
+    try {
+      await fsPromises.copyFile(mcpBakPath, mcpJsonPath);
+      log(`[OK] Restored mcp_config.json from backup: ${mcpBakPath}`);
+      restoredCount++;
+    } catch (err) {
+      warn(`[WARN] Could not restore mcp backup: ${err.message}`);
     }
+  } else {
+    log(`[INFO] No mcp_config.json backup found at ${mcpBakPath}`);
   }
 
-  log("\n✓ Uninstallation complete.\n");
+  return restoredCount > 0;
 }
 
 export function runStatus(options = {}) {
@@ -613,7 +706,8 @@ Commands & Options:
   --status, status             Check live integration status across all layers + RTK
   --check, -c                  Run pre-flight validation check without writing changes
   --uninstall, uninstall       Remove governor hook, plugin link, and MCP server
-  --restore-backups            Restore original configuration backup files (*.bak) during uninstall
+  --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 full 4-layer installation
 `);
@@ -621,18 +715,38 @@ Commands & Options:
 
 // Auto-run if executed directly as script
 if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
-  const arg = process.argv[2];
-  if (arg === "--help" || arg === "-h" || arg === "help") {
+  const args = process.argv.slice(2);
+  const isHelp = args.includes("--help") || args.includes("-h") || args.includes("help");
+  const isUninstall = args.includes("--uninstall") || args.includes("uninstall");
+  const isStatus = args.includes("--status") || args.includes("status");
+  const isCheck = args.includes("--check") || args.includes("-c");
+  const isRestoreBackups = args.includes("--restore-backups") || args.includes("restore-backups");
+  const allowDegraded = args.includes("--allow-degraded");
+
+  if (isHelp) {
     printCliHelp();
     process.exit(0);
-  } else if (arg === "--uninstall" || arg === "uninstall") {
-    const restoreBackups = process.argv.includes("--restore-backups");
-    await runUninstall({ restoreBackups });
-  } else if (arg === "--status" || arg === "status") {
+  }
+
+  // Reject conflicting read-only and mutating flags explicitly
+  if ((isCheck || isStatus) && (isUninstall || isRestoreBackups)) {
+    console.error("Error: Read-only flags (--check, --status) cannot be combined with mutating flags (--uninstall, --restore-backups).");
+    process.exit(1);
+  }
+  if (isCheck && isStatus) {
+    console.error("Error: Conflicting flags: specify either --check or --status, not both.");
+    process.exit(1);
+  }
+
+  if (isCheck) {
+    await runInstall({ checkOnly: true, allowDegraded });
+  } else if (isStatus) {
     runStatus();
-  } else if (arg === "--check" || arg === "-c") {
-    await runInstall({ checkOnly: true });
+  } else if (isUninstall) {
+    await runUninstall({ restoreBackups: isRestoreBackups });
+  } else if (isRestoreBackups) {
+    await runRestoreBackups();
   } else {
-    await runInstall();
+    await runInstall({ allowDegraded });
   }
 }

package/scripts/provision-rtk.mjs

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import crypto from "node:crypto";
 import { execSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 
@@ -9,6 +10,26 @@ 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_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"
+};
+
+export function isCompatibleRtkVersion(versionStr) {
+  if (!versionStr || typeof versionStr !== "string") return false;
+  const match = versionStr.match(/(\d+)\.(\d+)\.(\d+)/);
+  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);
+}
 
 export function getRtkPlatformAsset() {
   const platform = os.platform();
@@ -32,21 +53,36 @@ export function getRtkPlatformAsset() {
   return null;
 }
 
-export function findExistingRtk() {
-  // Check local binDir first
-  const info = getRtkPlatformAsset();
-  const localExe = info ? path.join(binDir, info.exeName) : null;
-  if (localExe && fs.existsSync(localExe)) {
-    try {
-      const out = execSync(`"${localExe}" --version`, { encoding: "utf-8", timeout: 5000 }).trim();
-      return { path: localExe, version: out, isLocal: true };
-    } catch {}
+export function findExistingRtk(options = {}) {
+  const names = os.platform() === "win32" ? ["rtk.exe", "rtk.cmd"] : ["rtk"];
+  const profileHome = process.env.AGY_TEST_PROFILE_DIR || os.homedir();
+  const pluginBinDir = path.join(profileHome, ".gemini", "config", "plugins", "agy-context-saver", "bin");
+  const candidateDirs = [binDir, pluginBinDir];
+
+  for (const dir of candidateDirs) {
+    for (const exeName of names) {
+      const localExe = path.join(dir, exeName);
+      if (fs.existsSync(localExe)) {
+        try {
+          const out = execSync(`"${localExe}" --version`, { encoding: "utf-8", timeout: 5000, stdio: ["ignore", "pipe", "ignore"] }).trim();
+          if (isCompatibleRtkVersion(out)) {
+            return { path: localExe, version: out, isLocal: true };
+          }
+        } catch {}
+      }
+    }
   }
 
   // Check PATH
   try {
-    const out = execSync("rtk --version", { encoding: "utf-8", timeout: 5000 }).trim();
-    return { path: "rtk", version: out, isLocal: false };
+    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;
@@ -54,9 +90,9 @@ export function findExistingRtk() {
 
 export async function ensureRtkInstalled(options = {}) {
   const log = options.silent ? () => {} : console.log;
-  const existing = options.existingRtk || findExistingRtk();
+  const existing = options.existingRtk || findExistingRtk(options);
   if (existing) {
-    log(`✓ RTK is already installed: ${existing.version} (${existing.path})`);
+    log(`✓ RTK is already installed and verified: ${existing.version} (${existing.path})`);
     return existing;
   }
 
@@ -79,6 +115,23 @@ 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(
+      `SHA-256 checksum verification failed for ${assetInfo.asset}!\n` +
+      `  Expected: ${expectedHash}\n` +
+      `  Actual:   ${actualHash}\n` +
+      `Archive extraction aborted to protect system integrity.`
+    );
+  }
+  log(`✓ Verified SHA-256 checksum: ${actualHash}`);
+
   const archivePath = path.join(binDir, assetInfo.asset);
   fs.writeFileSync(archivePath, buffer);
 
@@ -102,7 +155,7 @@ export async function ensureRtkInstalled(options = {}) {
     try { fs.chmodSync(targetExe, 0o755); } catch {}
   }
 
-  const verified = findExistingRtk();
+  const verified = findExistingRtk(options);
   if (!verified) {
     throw new Error(`RTK installation verification failed: could not run ${targetExe}`);
   }

package/scripts/release-preflight.mjs

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+/**
+ * Non-destructive release metadata/package preflight for Agy-Context-Saver.
+ * Run from the repository root: node scripts/release-preflight.mjs
+ * This script reads files only; it does not install the plugin or provision RTK.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const errors = [];
+const warnings = [];
+
+function readText(relativePath) {
+  const target = path.join(root, relativePath);
+  try {
+    return fs.readFileSync(target, 'utf8');
+  } catch {
+    errors.push(`Required file is missing or unreadable: ${relativePath}`);
+    return '';
+  }
+}
+
+function exists(relativePath) {
+  return fs.existsSync(path.join(root, relativePath));
+}
+
+let pkg;
+try {
+  pkg = JSON.parse(readText('package.json'));
+} catch (error) {
+  errors.push(`package.json is not valid JSON: ${error.message}`);
+}
+
+if (pkg) {
+  if (pkg.name !== 'agy-context-saver') {
+    errors.push(`Expected package name "agy-context-saver"; found ${JSON.stringify(pkg.name)}.`);
+  }
+  if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(pkg.version ?? '')) {
+    errors.push(`package.json version is not a valid semver release version: ${JSON.stringify(pkg.version)}.`);
+  }
+
+  const requiredMetadata = [
+    ['repository.url', pkg.repository?.url],
+    ['homepage', pkg.homepage],
+    ['bugs.url', pkg.bugs?.url],
+    ['engines.node', pkg.engines?.node],
+  ];
+  for (const [label, value] of requiredMetadata) {
+    if (typeof value !== 'string' || value.trim() === '') {
+      errors.push(`Add package.json metadata field "${label}" before publishing.`);
+    }
+  }
+  if (pkg.engines?.node && !/^>=\s*22(?:\.0\.0)?$/.test(pkg.engines.node.trim())) {
+    warnings.push(`Current release policy expects engines.node to be ">=22"; found ${JSON.stringify(pkg.engines.node)}. Update this check if the support policy changes.`);
+  }
+
+  const requiredPackageFiles = [
+    'mcp/index.js',
+    'scripts/install-register.mjs',
+    'scripts/provision-rtk.mjs',
+    'plugin.json',
+    'hooks.json',
+    'mcp_config.json',
+    'README.md',
+    'CHANGELOG.md',
+    'LICENSE',
+  ];
+
+  for (const relativePath of requiredPackageFiles) {
+    if (!exists(relativePath)) errors.push(`Required runtime/release file is missing: ${relativePath}`);
+    const coveredByFiles = (pkg.files ?? []).some((entry) => {
+      const normalized = entry.replace(/\\/g, '/').replace(/\/$/, '');
+      return relativePath === normalized || relativePath.startsWith(`${normalized}/`);
+    });
+    if (!coveredByFiles) {
+      errors.push(`package.json "files" does not clearly include ${relativePath}.`);
+    }
+  }
+
+  const binEntries = Object.values(pkg.bin ?? {});
+  if (binEntries.length === 0) errors.push('package.json has no bin entry.');
+  for (const binPath of binEntries) {
+    if (!exists(binPath)) errors.push(`package.json bin target does not exist: ${binPath}`);
+    const coveredByFiles = (pkg.files ?? []).some((entry) => {
+      const normalized = entry.replace(/\\/g, '/').replace(/\/$/, '');
+      return binPath === normalized || binPath.startsWith(`${normalized}/`);
+    });
+    if (!coveredByFiles) errors.push(`package.json "files" does not include the bin target: ${binPath}`);
+  }
+
+  const testCommand = pkg.scripts?.test;
+  if (typeof testCommand !== 'string' || !testCommand.trim()) {
+    errors.push('package.json is missing the npm test script.');
+  } else {
+    const suitePaths = [...testCommand.matchAll(/(?:^|&&\s*)node\s+(tests\/[\w.-]+\.mjs)/g)].map((match) => match[1]);
+    if (suitePaths.length === 0) {
+      errors.push('Could not find test entrypoints in package.json scripts.test; update release-preflight.mjs for the new test runner format.');
+    }
+    for (const suitePath of suitePaths) {
+      if (!exists(suitePath)) errors.push(`npm test references a missing test file: ${suitePath}`);
+    }
+
+    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".');
+    } else if (Number(countMatch[1]) !== suitePaths.length) {
+      errors.push(`README.md says ${countMatch[1]} test suites, but package.json scripts.test runs ${suitePaths.length}.`);
+    }
+    for (const suitePath of suitePaths) {
+      if (!readme.includes(suitePath)) {
+        errors.push(`README.md does not list the test entrypoint that npm test runs: ${suitePath}`);
+      }
+    }
+  }
+
+  for (const relativePath of ['SECURITY.md', 'CONTRIBUTING.md', 'CODE_OF_CONDUCT.md']) {
+    if (!exists(relativePath)) errors.push(`Add ${relativePath} before the public release.`);
+  }
+
+  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.');
+  } else {
+    console.log(`RTK provisioner pin found: ${rtkVersionMatch[1]}`);
+  }
+
+  if (!pkg.scripts?.setup || !pkg.scripts?.status || !pkg.scripts?.test) {
+    errors.push('Expected npm scripts setup, status, and test to be present.');
+  }
+  if (Object.keys(pkg.dependencies ?? {}).length > 0) {
+    warnings.push(`Runtime npm dependencies are present (${Object.keys(pkg.dependencies).join(', ')}); review whether each is required and trusted.`);
+  }
+}
+
+for (const warning of warnings) console.warn(`WARN: ${warning}`);
+for (const error of errors) console.error(`FAIL: ${error}`);
+
+if (errors.length) {
+  console.error(`\nRelease preflight failed with ${errors.length} error(s) and ${warnings.length} warning(s).`);
+  process.exitCode = 1;
+} else {
+  console.log(`\nRelease preflight passed${warnings.length ? ` with ${warnings.length} warning(s)` : ''}.`);
+}