@coworker-jp/aidr 0.1.292 → 0.1.293

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coworker-jp/aidr",
-  "version": "0.1.292",
+  "version": "0.1.293",
   "description": "AIDR setup CLI - installs ai-scanner hooks for 19+ AI coding agents",
   "type": "module",
   "bin": {

package/src/agents/claude.mjs

@@ -13,7 +13,11 @@ const SCRIPT_FILES = [
   "scan_webfetch.sh", "scan_websearch.sh",
   "log_web_urls.sh",
 ];
-const BIN_FILES = ["ai-scanner", "opengrep"];
+// `.ai-scanner-unscanned` は hook が「無検査でツールコールが通った」ことを
+// 記録するファイル (#1774)。**消す対象に入れておくこと** —— 残ると bin
+// ディレクトリが空にならず `rmdirIfEmpty` が効かないので、アンインストール後に
+// ディレクトリと記録が居座る。7 エージェントすべて同じ表を持つ。
+const BIN_FILES = ["ai-scanner", "opengrep", ".ai-scanner-unscanned"];
 
 export const meta = {
   name: "claude",

package/src/agents/codex.mjs

@@ -27,7 +27,11 @@ const SCRIPT_FILES = [
   "pre_shell.sh",
   "post_shell.sh",
 ];
-const BIN_FILES = ["ai-scanner", "opengrep"];
+// `.ai-scanner-unscanned` は hook が「無検査でツールコールが通った」ことを
+// 記録するファイル (#1774)。**消す対象に入れておくこと** —— 残ると bin
+// ディレクトリが空にならず `rmdirIfEmpty` が効かないので、アンインストール後に
+// ディレクトリと記録が居座る。7 エージェントすべて同じ表を持つ。
+const BIN_FILES = ["ai-scanner", "opengrep", ".ai-scanner-unscanned"];
 const ROOT_FILES = ["AGENTS.md"];
 
 export const meta = {

package/src/agents/cursor.mjs

@@ -28,7 +28,11 @@ const SCRIPT_FILES = [
   "post_read.sh",
   "post_write.sh",
 ];
-const BIN_FILES = ["ai-scanner", "opengrep"];
+// `.ai-scanner-unscanned` は hook が「無検査でツールコールが通った」ことを
+// 記録するファイル (#1774)。**消す対象に入れておくこと** —— 残ると bin
+// ディレクトリが空にならず `rmdirIfEmpty` が効かないので、アンインストール後に
+// ディレクトリと記録が居座る。7 エージェントすべて同じ表を持つ。
+const BIN_FILES = ["ai-scanner", "opengrep", ".ai-scanner-unscanned"];
 
 export const meta = {
   name: "cursor",

package/src/agents/gemini.mjs

@@ -5,7 +5,11 @@ import * as T from "../templates.mjs";
 import { buildGeminiSettings, mergeGeminiSettings, unmergeGeminiSettings } from "../merge.mjs";
 
 const HOOK_FILES = ["aidr-pre.sh"];
-const BIN_FILES = ["ai-scanner", "opengrep"];
+// `.ai-scanner-unscanned` は hook が「無検査でツールコールが通った」ことを
+// 記録するファイル (#1774)。**消す対象に入れておくこと** —— 残ると bin
+// ディレクトリが空にならず `rmdirIfEmpty` が効かないので、アンインストール後に
+// ディレクトリと記録が居座る。7 エージェントすべて同じ表を持つ。
+const BIN_FILES = ["ai-scanner", "opengrep", ".ai-scanner-unscanned"];
 
 export const meta = {
   name: "gemini",

package/src/agents/kiro.mjs

@@ -18,7 +18,11 @@ const SCRIPT_FILES = [
   "post_read.sh",
   "post_write.sh",
 ];
-const BIN_FILES = ["ai-scanner", "opengrep"];
+// `.ai-scanner-unscanned` は hook が「無検査でツールコールが通った」ことを
+// 記録するファイル (#1774)。**消す対象に入れておくこと** —— 残ると bin
+// ディレクトリが空にならず `rmdirIfEmpty` が効かないので、アンインストール後に
+// ディレクトリと記録が居座る。7 エージェントすべて同じ表を持つ。
+const BIN_FILES = ["ai-scanner", "opengrep", ".ai-scanner-unscanned"];
 
 export const meta = {
   name: "kiro",

package/src/agents/standalone.mjs

@@ -2,7 +2,11 @@ import path from "node:path";
 import fsp from "node:fs/promises";
 import { pathExists, rmdirIfEmpty } from "../fs-utils.mjs";
 
-const BIN_FILES = ["ai-scanner", "opengrep"];
+// `.ai-scanner-unscanned` は hook が「無検査でツールコールが通った」ことを
+// 記録するファイル (#1774)。**消す対象に入れておくこと** —— 残ると bin
+// ディレクトリが空にならず `rmdirIfEmpty` が効かないので、アンインストール後に
+// ディレクトリと記録が居座る。7 エージェントすべて同じ表を持つ。
+const BIN_FILES = ["ai-scanner", "opengrep", ".ai-scanner-unscanned"];
 
 export const meta = {
   name: "standalone",

package/src/agents/windsurf.mjs

@@ -25,7 +25,11 @@ const SCRIPT_FILES = [
   "post_read.sh",
   "post_write.sh",
 ];
-const BIN_FILES = ["ai-scanner", "opengrep"];
+// `.ai-scanner-unscanned` は hook が「無検査でツールコールが通った」ことを
+// 記録するファイル (#1774)。**消す対象に入れておくこと** —— 残ると bin
+// ディレクトリが空にならず `rmdirIfEmpty` が効かないので、アンインストール後に
+// ディレクトリと記録が居座る。7 エージェントすべて同じ表を持つ。
+const BIN_FILES = ["ai-scanner", "opengrep", ".ai-scanner-unscanned"];
 
 export const meta = {
   name: "windsurf",

package/src/binary-fetcher.mjs

@@ -65,11 +65,117 @@ async function fetchBuffer(url, accessKey) {
   return Buffer.from(ab);
 }
 
-async function fetchText(url, accessKey) {
+/**
+ * Refused to install because the download could not be checked against a
+ * publisher checksum. `status` is set ONLY when the endpoint gave a definite
+ * "not there" for the sidecar, so `fetchBinary` can treat an incompletely
+ * published pinned release exactly like a missing pinned payload (fall back to
+ * the published key, which brings its own checksum) instead of turning a half
+ * release into an unverified install.
+ */
+export class IntegrityUnverifiableError extends Error {
+  constructor(message, { status } = {}) {
+    super(message);
+    this.name = "IntegrityUnverifiableError";
+    if (status !== undefined) this.status = status;
+  }
+}
+
+/** A publisher checksum is 64 lowercase-or-uppercase hex characters. */
+const SHA256_HEX_RE = /^[0-9a-fA-F]{64}$/;
+
+/** Statuses that mean "this object is not there", as opposed to "ask again". */
+const DEFINITELY_ABSENT = new Set([404, 410]);
+
+/**
+ * Statuses that will not change on a retry but are NOT evidence of absence: the
+ * caller was refused. Kept apart from `DEFINITELY_ABSENT` so a rejected access
+ * key never makes `fetchBinary` fall back to another key (same reason as the
+ * payload's own 403 rule below) and never reads as "the release is incomplete".
+ */
+const REFUSED = new Set([401, 403]);
+
+/** How many times a transient sidecar failure is re-asked before giving up. */
+export const CHECKSUM_ATTEMPTS = 3;
+const CHECKSUM_RETRY_MS = 400;
+
+/**
+ * Fetch the sibling `.sha256` sidecar and classify the outcome. The three
+ * outcomes are kept apart on purpose — the previous implementation collapsed
+ * every one of them into `null` (`if (!res.ok) return null` plus a
+ * `.catch(() => null)`), which is how "the object is gone" became
+ * indistinguishable from "the network blinked", and both became "install it
+ * anyway":
+ *
+ *   { kind: "hash", hex }        200 carrying a usable digest
+ *   { kind: "absent", status }   the endpoint answered that it is not there
+ *   { kind: "unusable", detail } reachable but no digest came back, or the
+ *                               service/network could not answer at all
+ *
+ * A 200 whose body is empty / whitespace / not 64 hex characters is `unusable`,
+ * NOT `absent`: an empty sidecar object and an error page both used to pass the
+ * old `if (expected)` test as falsy-or-garbage and skip verification.
+ */
+async function fetchChecksum(url, accessKey, { attempts = CHECKSUM_ATTEMPTS, sleep = defaultSleep } = {}) {
   const headers = accessKey ? { "x-access-key": accessKey } : {};
-  const res = await fetch(url, { redirect: "follow", headers });
-  if (!res.ok) return null;
-  return (await res.text()).trim();
+  let last = null;
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    let res;
+    try {
+      res = await fetch(url, { redirect: "follow", headers });
+    } catch (e) {
+      last = { kind: "unusable", detail: `${url} could not be reached (${e.message})` };
+      if (attempt < attempts) { await sleep(CHECKSUM_RETRY_MS * attempt); continue; }
+      return last;
+    }
+    if (DEFINITELY_ABSENT.has(res.status)) {
+      // Not a transient condition: asking again cannot make it appear.
+      return { kind: "absent", status: res.status, detail: `${url} -> HTTP ${res.status}` };
+    }
+    if (REFUSED.has(res.status)) {
+      return {
+        kind: "unusable",
+        detail: `${url} -> HTTP ${res.status} (the access key was refused for the checksum)`,
+      };
+    }
+    if (!res.ok) {
+      last = { kind: "unusable", detail: `${url} -> HTTP ${res.status}` };
+      if (attempt < attempts) { await sleep(CHECKSUM_RETRY_MS * attempt); continue; }
+      return last;
+    }
+    const body = (await res.text().catch(() => "")).trim();
+    const token = body.split(/\s+/)[0] || "";
+    if (SHA256_HEX_RE.test(token)) return { kind: "hash", hex: token.toLowerCase() };
+    // Reachable, answered 200, and still no digest. Re-asking a served object
+    // will not change its bytes, so this is decided on the first look.
+    return {
+      kind: "unusable",
+      detail: body
+        ? `${url} did not return a SHA256 digest (got ${JSON.stringify(token.slice(0, 32))})`
+        : `${url} returned an empty checksum`,
+    };
+  }
+  return last;
+}
+
+function defaultSleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Throw unless this asset was checked against a publisher checksum. Callers use
+ * this so `verified` is a CONDITION, not a caption: it used to be read only to
+ * decide whether to append ", sha256 verified" to a log line, which meant a code
+ * path returning `verified: false` would install the binary and merely print
+ * one word less. Every consumer of `fetchAsset` / `fetchBinary` must call this
+ * before treating the file as installed.
+ */
+export function assertVerified(result, label = "the downloaded file") {
+  if (result?.verified === true) return result;
+  throw new IntegrityUnverifiableError(
+    `${label} was not checked against a publisher SHA256 checksum, so it was not installed. ` +
+    `Re-run the installer; if it keeps happening, contact your IT administrator.`,
+  );
 }
 
 async function clearQuarantine(destPath) {
@@ -82,28 +188,53 @@ async function clearQuarantine(destPath) {
 }
 
 /**
- * Download an asset from `binUrl` into `destPath`, validating SHA256 when a
- * sibling `.sha256` file is available. Sets executable mode and strips macOS
- * quarantine. Returns { path, sha256, verified }.
+ * Download an asset from `binUrl` into `destPath`, validating it against the
+ * sibling `.sha256` published beside it. Sets executable mode and strips macOS
+ * quarantine. Returns { path, sha256, verified } with `verified` always true —
+ * the alternative is a throw, never a returned `verified: false` (#1773).
+ * `checksumOpts` is a test seam ({ attempts, sleep }) for the retry loop.
  */
-export async function fetchAsset(binUrl, destPath, { accessKey } = {}) {
+export async function fetchAsset(binUrl, destPath, { accessKey, checksumOpts } = {}) {
   const shaUrl = `${binUrl}.sha256`;
   await fsp.mkdir(path.dirname(destPath), { recursive: true });
 
   const buf = await fetchBuffer(binUrl, accessKey);
   const sha256 = crypto.createHash("sha256").update(buf).digest("hex");
 
-  let verified = false;
-  const expected = await fetchText(shaUrl, accessKey).catch(() => null);
-  if (expected) {
-    const want = expected.split(/\s+/)[0].toLowerCase();
-    if (want !== sha256) {
-      throw new Error(`SHA256 mismatch for ${binUrl}: got ${sha256}, expected ${want}`);
-    }
-    verified = true;
-  } else {
-    console.warn(`warning: ${shaUrl} unavailable; skipping SHA256 verification`);
+  // FAIL-CLOSED (#1773). No checksum ⇒ nothing is written to `destPath`.
+  //
+  // This is the same rule the scanner's own self-updater has followed since
+  // #319 ("a missing sha256 means DO NOT install", docker/scanner/src/main.rs
+  // `check_download_hash`) and the same rule `fetchOpengrep` below follows
+  // against its pinned hash. Only the FIRST install — this function — used to
+  // be exempt, which is exactly backwards: at first install there is no
+  // previously-verified binary in place to fall back on.
+  //
+  // Suppressing one small object must not be able to downgrade the check on a
+  // security product's executable, and it is far easier to delete a hash than
+  // to forge one. So the outcomes are: verified install, or no install plus a
+  // loud, actionable status — never a quiet unverified install.
+  const checksum = await fetchChecksum(shaUrl, accessKey, checksumOpts);
+  if (checksum.kind === "absent") {
+    throw new IntegrityUnverifiableError(
+      `no published SHA256 checksum for ${binUrl} (${checksum.detail}), so the download was ` +
+      `discarded without being installed. Re-run the installer in a few minutes; if it keeps ` +
+      `happening, contact your IT administrator — the release is incomplete.`,
+      { status: checksum.status },
+    );
+  }
+  if (checksum.kind !== "hash") {
+    throw new IntegrityUnverifiableError(
+      `could not read the SHA256 checksum for ${binUrl} after ${CHECKSUM_ATTEMPTS} attempts ` +
+      `(${checksum.detail}), so the download was discarded without being installed. ` +
+      `Check the network connection and re-run the installer; if it keeps happening, ` +
+      `contact your IT administrator.`,
+    );
+  }
+  if (checksum.hex !== sha256) {
+    throw new Error(`SHA256 mismatch for ${binUrl}: got ${sha256}, expected ${checksum.hex}`);
   }
+  const verified = true;
 
   const tmp = `${destPath}.tmp-${process.pid}`;
   await fsp.writeFile(tmp, buf);
@@ -159,6 +290,11 @@ export async function fetchBinary(destPath, { env = "prod", accessKey, version,
     const result = await fetchAsset(`${base}/v${version}/${platform}`, destPath, { accessKey });
     return { ...result, platform, requestedVersion: version, servedUnpinned: false };
   } catch (e) {
+    // A pinned release whose CHECKSUM is a definite 404 is incomplete in exactly
+    // the same way as one whose binary is (#1773): half a release is not a
+    // release. It falls back here, and the published key it falls back to
+    // carries its own checksum — the fallback can never widen into an
+    // unverified install, because `fetchAsset` refuses that on both keys.
     if (e?.status !== 404) throw e;
     const result = await fetchAsset(unpinnedUrl, destPath, { accessKey });
     return { ...result, platform, requestedVersion: version, servedUnpinned: true };

package/src/cli.mjs

@@ -10,7 +10,7 @@ import { Command } from "commander";
 const execFileP = promisify(execFile);
 import { AGENT_ORDER, AGENT_REGISTRY, loadAgent } from "./agents/index.mjs";
 import { verifyKey, maskKey } from "./verify.mjs";
-import { fetchBinary, fetchOpengrep } from "./binary-fetcher.mjs";
+import { fetchBinary, fetchOpengrep, assertVerified } from "./binary-fetcher.mjs";
 import { detectInstalled } from "./detect.mjs";
 import { evaluateInstallGate, formatLocalPcGuidance } from "./env-gate.mjs";
 import { resolveCallerHome, isRunningUnderSudo, chownToCaller } from "./sudo-user.mjs";
@@ -200,20 +200,30 @@ async function cmdInstall(opts) {
         // dir so ai-scanner's sibling-lookup finds opengrep without relying on
         // PATH. Users can point AI_SCANNER_OPENGREP elsewhere to substitute
         // their own LGPL-2.1 build.
-        const scannerRes = await fetchBinary(path.join(primaryDir, "ai-scanner"), fetchOpts);
+        const scannerRes = assertVerified(
+          await fetchBinary(path.join(primaryDir, "ai-scanner"), fetchOpts),
+          "the ai-scanner binary",
+        );
         binaryOutcome.scannerInstalled = true;
-        console.log(`binary: ${scannerRes.path} (${scannerRes.platform}${scannerRes.verified ? ", sha256 verified" : ""})`);
+        // Stated unconditionally, because it is now a condition of getting here
+        // rather than a caption on a file that may or may not have been checked
+        // (#1773): `fetchAsset` throws unless the bytes matched the published
+        // SHA256, and `assertVerified` is the second lock on that.
+        console.log(`binary: ${scannerRes.path} (${scannerRes.platform}, sha256 verified)`);
         if (scannerRes.servedUnpinned) {
           // Say what was asked for, what arrived, and how to check — the pinned
           // build genuinely has no bytes behind it, but protection IS in place,
           // so this is a note, not an alarm.
-          console.error(`note: release v${scannerRes.requestedVersion} of the scanner is not published for ${scannerRes.platform} yet, so it could not be the one installed.`);
+          console.error(`note: release v${scannerRes.requestedVersion} of the scanner is not fully published for ${scannerRes.platform} yet (its binary or its checksum is not there), so it could not be the one installed.`);
           console.error(`note: the currently published build was installed instead, so scanning is active. Check which build you have with: ${scannerRes.path} version`);
         }
         // Opengrep is fetched unmodified from its public upstream GitHub
         // release (LGPL-2.1); no access-key gating is needed here.
-        const opengrepRes = await fetchOpengrep(path.join(primaryDir, "opengrep"));
-        console.log(`binary: ${opengrepRes.path} (opengrep ${opengrepRes.platform}${opengrepRes.verified ? ", sha256 verified" : ""})`);
+        const opengrepRes = assertVerified(
+          await fetchOpengrep(path.join(primaryDir, "opengrep")),
+          "the opengrep engine",
+        );
+        console.log(`binary: ${opengrepRes.path} (opengrep ${opengrepRes.platform}, sha256 verified)`);
 
         const copyOps = restDirs.flatMap(restDir =>
           ["ai-scanner", "opengrep"].map(async (file) => {
@@ -570,13 +580,55 @@ async function cmdDoctor() {
       await fs.access(bin, fs.constants.F_OK);
       present = true;
     } catch {}
-    return `binary: ${bin} ${present ? "[present]" : "[missing]"}`;
+    const out = [`binary: ${bin} ${present ? "[present]" : "[missing]"}`];
+    // What the hooks recorded while there was no binary (#1774). Without this,
+    // "[missing]" was the only trace, and it said nothing about how long the
+    // machine had been unscanned or how much had gone through unscanned —
+    // start_scanner.sh removes the record as soon as a binary is in place, so
+    // its presence describes the CURRENT state, not history.
+    const unscanned = await readUnscannedRecord(path.dirname(bin));
+    if (unscanned) {
+      out.push(
+        `  ${unscanned.count} tool call(s) ran with no scanner in place, ` +
+        `from ${unscanned.first.toISOString()} to ${unscanned.last.toISOString()}.`,
+      );
+      out.push(present
+        ? "  A binary is in place now, and this record has not been cleared yet: " +
+          "it is cleared at the next session start. Whether anything was missed in that " +
+          "window is not knowable from here — nothing scanned those calls."
+        // INSTALL_COMMAND_HINT, not a literal: the DEV package must never tell
+        // anyone to install PROD.
+        : `  Those calls were not scanned. Re-run the installer (${INSTALL_COMMAND_HINT}), ` +
+          "or contact your IT administrator.");
+    }
+    return out.join("\n");
   }));
   for (const line of lines) {
     if (line) console.log(line);
   }
 }
 
+/**
+ * Read the `.ai-scanner-unscanned` record the scan hooks write next to the
+ * binary when they exit without one (templates.mjs `note_unscanned`). Three
+ * integers on one line: first seen, last seen, count. A malformed or absent
+ * file yields null — this is a diagnostic read, so it must never throw and must
+ * never invent a number (a count of 0 would read as "nothing was missed").
+ */
+export async function readUnscannedRecord(binDir) {
+  let raw;
+  try {
+    raw = await fs.readFile(path.join(binDir, ".ai-scanner-unscanned"), "utf8");
+  } catch {
+    return null;
+  }
+  const parts = raw.split(/\r?\n/)[0].trim().split(/\s+/);
+  if (parts.length < 3) return null;
+  const [first, last, count] = parts.map((n) => (/^\d+$/.test(n) ? Number(n) : null));
+  if (first === null || last === null || count === null || count === 0) return null;
+  return { first: new Date(first * 1000), last: new Date(last * 1000), count };
+}
+
 async function cmdListAgents() {
   for (const name of AGENT_ORDER) {
     const mod = await loadAgent(name);

package/src/red-team.mjs

@@ -16,7 +16,7 @@ import path from "node:path";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 
-import { fetchAsset, detectPlatform } from "./binary-fetcher.mjs";
+import { fetchAsset, detectPlatform, assertVerified } from "./binary-fetcher.mjs";
 import { downloadBase } from "./verify.mjs";
 
 const execFileP = promisify(execFile);
@@ -97,7 +97,13 @@ export async function fetchRedTeamBinary(
   const platform = detectPlatform();
   const rel = product === DEFAULT_RED_TEAM_PRODUCT ? platform : `${product}/${platform}`;
   const binUrl = `${downloadBase(env)}/red-team/${rel}`;
-  const result = await fetchAsset(binUrl, destPath, { accessKey });
+  // 検証できなかったものは `fetchAsset` が throw するので、ここに来た時点で
+  // 公開 SHA256 と一致している。`assertVerified` はその 2 つ目の錠で、
+  // 「verified を表示にしか使っていない」状態 (#1773) に戻ることを防ぐ。
+  const result = assertVerified(
+    await fetchAsset(binUrl, destPath, { accessKey }),
+    `the ${product} binary`,
+  );
   return { ...result, platform, product };
 }
 
@@ -281,7 +287,7 @@ export async function installRedTeam({
   await fs.mkdir(binDir, { recursive: true });
   const res = await fetchRedTeamBinary(binPath, { env, accessKey, product });
   stdout(
-    `binary: ${res.path} (${res.platform}${res.verified ? ", sha256 verified" : ""})`,
+    `binary: ${res.path} (${res.platform}, sha256 verified)`,
   );
 
   const args = buildMcpAddArgs(binPath, accessKey, scope, meta.mcpServerName);

package/src/templates.mjs

@@ -4,6 +4,7 @@
 // only the access key and the verify endpoint differ.
 
 import { buildClaudeSettings, buildGeminiSettings } from "./merge.mjs";
+import { isDevDownloadBase } from "./verify.mjs";
 
 export function getSettingsJson(accessKey, scope = "project") {
   return JSON.stringify(buildClaudeSettings(accessKey, scope), null, 2) + "\n";
@@ -15,6 +16,14 @@ export function getSettingsJson(accessKey, scope = "project") {
 // is kept for signature stability with callers and the wider TS template.
 // eslint-disable-next-line no-unused-vars
 export function getStartScannerSh(downloadBase = "https://pytd2jd5p7.execute-api.ap-northeast-1.amazonaws.com/download", agentType = "claude-code") {
+  // Which installer to quote back at the user, derived from the endpoint this
+  // script was generated against. The DEV package must never tell anyone to
+  // install PROD (same rule as cli.mjs's INSTALL_COMMAND_HINT) — and here the
+  // package name is not in scope, so the endpoint is the only evidence
+  // available. Anything that is not the DEV endpoint is treated as PROD.
+  const installCommand = isDevDownloadBase(downloadBase)
+    ? "npx @coworker-jp/aidr-dev install"
+    : "npx @coworker-jp/aidr install";
   return `#!/bin/bash
 # SessionStart hook: Setup ai-scanner for the current platform
 # - Linux (x86_64 / aarch64): download native binary from S3
@@ -46,9 +55,41 @@ should_check_update() {
     [ $(($(date +%s) - last)) -ge "$PULL_INTERVAL" ]
 }
 
+# True for exactly 64 hex characters — the shape of a SHA-256 digest.
+is_sha256() {
+    [ "\${#1}" -eq 64 ] || return 1
+    case "$1" in *[!0-9a-fA-F]*) return 1 ;; esac
+    return 0
+}
+
+# Lower-case SHA-256 of $1, using whichever tool this machine has. Returns
+# non-zero when it has none — which is refused below, not waved through.
+sha256_of() {
+    local out
+    if command -v sha256sum >/dev/null 2>&1; then
+        out=$(sha256sum "$1" 2>/dev/null) || return 1
+    elif command -v shasum >/dev/null 2>&1; then
+        out=$(shasum -a 256 "$1" 2>/dev/null) || return 1
+    elif command -v openssl >/dev/null 2>&1; then
+        out=$(openssl dgst -sha256 "$1" 2>/dev/null | awk '{print $NF}') || return 1
+    else
+        return 1
+    fi
+    printf '%s' "\${out%% *}" | tr 'A-F' 'a-f'
+}
+
 # Download binary from $1 to $BIN, strip quarantine (macOS), chmod +x.
 # Uses curl's native --max-time so no external \`timeout\` dependency.
 # Access key is required by the /download endpoint.
+#
+# FAIL-CLOSED on the checksum (#1786). This path used to install whatever came
+# back, unchecked. Every other place the product obtains this binary verifies it
+# — the scanner's own self-update (#319), the sentinel daemon's self-provision,
+# and \`aidr install\` (#1773) — and this one is the one that runs on a machine
+# whose binary already went missing once. Refusing leaves the machine in the
+# same state a failed download leaves it in (no binary, and the caller says so
+# out loud), which is strictly better than running bytes nobody checked.
+# \`$UNVERIFIED_REASON\` carries WHY, so the message can name it.
 download_binary() {
     local url="$1"
     local tmp=$(mktemp "\${BIN_DIR}/ai-scanner.XXXXXX")
@@ -56,16 +97,67 @@ download_binary() {
     if [ -n "\${AI_SCANNER_ACCESS_KEY:-}" ]; then
         auth_args=(-H "x-access-key: \${AI_SCANNER_ACCESS_KEY}")
     fi
-    if curl -sfL --max-time 60 "\${auth_args[@]}" -o "$tmp" "$url" 2>/dev/null; then
-        chmod +x "$tmp"
-        # macOS: strip Gatekeeper quarantine so unsigned binary can execute
-        # (no-op on Linux where xattr isn't typically present)
-        xattr -d com.apple.quarantine "$tmp" 2>/dev/null || true
-        mv -f "$tmp" "$BIN"
-        return 0
+    if ! curl -sfL --max-time 60 "\${auth_args[@]}" -o "$tmp" "$url" 2>/dev/null; then
+        rm -f "$tmp"
+        UNVERIFIED_REASON="the download from $url did not complete"
+        return 1
     fi
-    rm -f "$tmp"
-    return 1
+
+    local want got
+    want=$(curl -sfL --retry 2 --max-time 30 "\${auth_args[@]}" "\${url}.sha256" 2>/dev/null \
+           | tr -d '\\r' | awk 'NR==1{print $1}')
+    if ! is_sha256 "$want"; then
+        rm -f "$tmp"
+        UNVERIFIED_REASON="no published checksum was readable at \${url}.sha256, so the download could not be checked"
+        return 1
+    fi
+    if ! got=$(sha256_of "$tmp"); then
+        rm -f "$tmp"
+        UNVERIFIED_REASON="this machine has none of sha256sum, shasum or openssl, so the download could not be checked"
+        return 1
+    fi
+    if [ "$got" != "$(printf '%s' "$want" | tr 'A-F' 'a-f')" ]; then
+        rm -f "$tmp"
+        UNVERIFIED_REASON="the download did not match its published checksum (expected $want, got $got)"
+        return 1
+    fi
+
+    chmod +x "$tmp"
+    # macOS: strip Gatekeeper quarantine so unsigned binary can execute
+    # (no-op on Linux where xattr isn't typically present)
+    xattr -d com.apple.quarantine "$tmp" 2>/dev/null || true
+    mv -f "$tmp" "$BIN"
+    return 0
+}
+
+# What has already run unscanned on this machine, if anything (#1774). The scan
+# hooks append to this file every time they exit without a binary; this is the
+# first moment anyone can say it out loud, and it is deleted the moment a binary
+# is in place so a healed machine stops claiming to be blind.
+UNSCANNED_STAMP="\${BIN_DIR}/.ai-scanner-unscanned"
+
+report_unscanned_history() {
+    local line first count
+    [ -r "$UNSCANNED_STAMP" ] || return 0
+    read -r line < "$UNSCANNED_STAMP" 2>/dev/null || return 0
+    set -- $line
+    first="\${1:-}"; count="\${3:-}"
+    case "$count" in ''|*[!0-9]*) return 0 ;; esac
+    # \`date -d @<epoch>\` is GNU, \`date -r <epoch>\` is BSD/macOS, and the epoch
+    # itself is the fallback — printing nothing here would drop the fact.
+    local when
+    when=$(date -d "@$first" 2>/dev/null || date -r "$first" 2>/dev/null || echo "epoch $first")
+    echo "ai-scanner: $count tool call(s) have already run unscanned on this machine (first at $when)." >&2
+}
+
+# There is no build for this platform, so this machine will not be scanned.
+# Said with the next action attached, because a lone "Warning: Unsupported …"
+# reads as cosmetic (docs/product/UI_COPY.md 【非交渉】) — and unlike a failed
+# download, re-running the installer cannot fix it, so the action is different.
+unsupported_platform() {
+    echo "ai-scanner: this session is NOT being scanned — there is no scanner build for this platform ($1)." >&2
+    report_unscanned_history
+    echo "ai-scanner: tool calls keep working, and they run unscanned on this machine. Contact your IT administrator with this message." >&2
 }
 
 OS=$(uname -s)
@@ -77,7 +169,7 @@ case "$OS" in
             x86_64)         PLATFORM_SLUG="linux-x86_64" ;;
             aarch64|arm64)  PLATFORM_SLUG="linux-aarch64" ;;
             *)
-                echo "Warning: Unsupported Linux architecture: $ARCH (expected x86_64 or aarch64)" >&2
+                unsupported_platform "Linux/$ARCH"
                 exit 0
                 ;;
         esac
@@ -91,13 +183,13 @@ case "$OS" in
             # — only its contents became universal, never its name.
             arm64|x86_64) PLATFORM_SLUG="darwin-aarch64" ;;
             *)
-                echo "Warning: Unsupported macOS architecture: $ARCH" >&2
+                unsupported_platform "macOS/$ARCH"
                 exit 0
                 ;;
         esac
         ;;
     *)
-        echo "Warning: Unsupported OS for ai-scanner: $OS" >&2
+        unsupported_platform "$OS"
         exit 0
         ;;
 esac
@@ -105,13 +197,24 @@ esac
 # Binary missing → fetch it
 if [ ! -x "$BIN" ]; then
     if download_binary "\${DOWNLOAD_BASE}/\${PLATFORM_SLUG}"; then
-        echo "ai-scanner binary installed (\${PLATFORM_SLUG})" >&2
+        echo "ai-scanner binary installed (\${PLATFORM_SLUG}, checksum verified)" >&2
+        rm -f "$UNSCANNED_STAMP"
     else
-        echo "Warning: Failed to download ai-scanner binary from \${DOWNLOAD_BASE}/\${PLATFORM_SLUG}" >&2
+        # docs/product/UI_COPY.md 【非交渉】: the fact, stated so it cannot be
+        # read as harmless, and then the next action. The old single line
+        # ("Warning: Failed to download …") said neither what it meant for the
+        # session nor what to do, and it was the ONLY trace anywhere (#1774).
+        echo "ai-scanner: this session is NOT being scanned — the scanner is not installed on this machine and could not be installed now: \${UNVERIFIED_REASON:-the download failed}." >&2
+        report_unscanned_history
+        echo "ai-scanner: tool calls keep working, and they run unscanned until it is in place. Re-run the installer (${installCommand}), or contact your IT administrator with this message." >&2
     fi
     exit 0
 fi
 
+# A binary IS in place. Clear any record of having run unscanned, so the record
+# only ever describes the machine's CURRENT state.
+rm -f "$UNSCANNED_STAMP"
+
 # Binary exists — throttled self-update check
 if should_check_update; then
     "$BIN" update 2>/dev/null || true
@@ -148,6 +251,42 @@ exit 0
 // generous enough to absorb cold-start variance while still bounding a
 // truly hung scanner. AI_SCANNER_HOOK_TIMEOUT (seconds) lets operators
 // tune further per-environment.
+// A tool call ran with NO scanner in place (issue #1774).
+//
+// The hook still exits 0 — fail-open is non-negotiable (CLAUDE.md "Fail-open
+// Design"): the scanner's own absence must never block the user's work. What
+// was missing is everything AFTER that: nothing re-fetched, nothing recorded,
+// nothing visible. From the outside a machine whose binary vanished looked
+// exactly like a healthy one, because "healthy" also produces no output.
+//
+// So the fact is written down next to where the binary belongs: first time
+// seen, last time seen, and how many tool calls have run unscanned. That file
+// is what `start_scanner.sh` reads to tell the user at the next session start,
+// and what `aidr doctor` reads on demand. `start_scanner.sh` DELETES it once a
+// binary is in place, so a machine that healed stops claiming to be blind.
+//
+// Never fails, never blocks: every write is best-effort and the function always
+// returns 0. A bookkeeping error must not become a scanning outage.
+//
+// Two hooks firing at once can lose a count (last write wins). That is
+// accepted: this is a signal that scanning stopped, not an accounting ledger.
+const UNSCANNED_NOTE = `note_unscanned() {
+  local dir stamp now first count line
+  dir="$(dirname "$BIN")"
+  [ -d "$dir" ] || return 0
+  stamp="$dir/.ai-scanner-unscanned"
+  now="$(date +%s 2>/dev/null)" || return 0
+  first="$now"; count=0
+  if [ -r "$stamp" ]; then
+    read -r line < "$stamp" 2>/dev/null || line=""
+    set -- $line
+    case "\${1:-}" in ''|*[!0-9]*) ;; *) first="$1" ;; esac
+    case "\${3:-}" in ''|*[!0-9]*) ;; *) count="$3" ;; esac
+  fi
+  printf '%s %s %s\\n' "$first" "$now" "$((count + 1))" > "$stamp" 2>/dev/null || true
+  return 0
+}`;
+
 const SCAN_HELPERS = `run_scanner() {
   if command -v timeout >/dev/null 2>&1; then
     timeout --kill-after=2s "\${AI_SCANNER_HOOK_TIMEOUT:-30}" "$BIN" "$@"
@@ -165,7 +304,8 @@ export const SCAN_BASH_SH = `#!/bin/bash
 # PostToolUse hook for Bash: Scan command output.
 # Thin Claude Code adapter — Rust handles cap, detection log, actor resolution.
 BIN="\${AI_SCANNER_BIN:-$HOME/.claude/bin/ai-scanner}"
-[ ! -x "$BIN" ] && exit 0
+${UNSCANNED_NOTE}
+[ ! -x "$BIN" ] && { note_unscanned; exit 0; }
 
 export AI_SCANNER_DETECTION_LOG="\${CLAUDE_PROJECT_DIR:-.}/.claude/logs/detections.log"
 
@@ -181,7 +321,8 @@ export const SCAN_BASH_INPUT_SH = `#!/bin/bash
 # PreToolUse hook for Bash: Scan command before execution.
 # Thin Claude Code adapter — Rust handles cap, detection log, actor resolution.
 BIN="\${AI_SCANNER_BIN:-$HOME/.claude/bin/ai-scanner}"
-[ ! -x "$BIN" ] && exit 0
+${UNSCANNED_NOTE}
+[ ! -x "$BIN" ] && { note_unscanned; exit 0; }
 
 export AI_SCANNER_DETECTION_LOG="\${CLAUDE_PROJECT_DIR:-.}/.claude/logs/detections.log"
 
@@ -198,7 +339,8 @@ export const SCAN_EDIT_SH = `#!/bin/bash
 # Thin Claude Code adapter — Rust handles cap, exclude dirs, detection log.
 # Only the Edit-vs-MultiEdit content extraction is Claude Code specific.
 BIN="\${AI_SCANNER_BIN:-$HOME/.claude/bin/ai-scanner}"
-[ ! -x "$BIN" ] && exit 0
+${UNSCANNED_NOTE}
+[ ! -x "$BIN" ] && { note_unscanned; exit 0; }
 
 export AI_SCANNER_DETECTION_LOG="\${CLAUDE_PROJECT_DIR:-.}/.claude/logs/detections.log"
 
@@ -223,7 +365,8 @@ export const SCAN_READ_SH = `#!/bin/bash
 # PostToolUse hook for Read: Scan file content Claude just read.
 # Thin Claude Code adapter — Rust handles cap, exclude dirs, detection log.
 BIN="\${AI_SCANNER_BIN:-$HOME/.claude/bin/ai-scanner}"
-[ ! -x "$BIN" ] && exit 0
+${UNSCANNED_NOTE}
+[ ! -x "$BIN" ] && { note_unscanned; exit 0; }
 
 export AI_SCANNER_DETECTION_LOG="\${CLAUDE_PROJECT_DIR:-.}/.claude/logs/detections.log"
 
@@ -242,7 +385,8 @@ export const SCAN_EDIT_OUTPUT_SH = `#!/bin/bash
 # PostToolUse hook for Edit/MultiEdit/Write: Scan final file content.
 # Thin Claude Code adapter — Rust handles cap, exclude dirs, detection log.
 BIN="\${AI_SCANNER_BIN:-$HOME/.claude/bin/ai-scanner}"
-[ ! -x "$BIN" ] && exit 0
+${UNSCANNED_NOTE}
+[ ! -x "$BIN" ] && { note_unscanned; exit 0; }
 
 export AI_SCANNER_DETECTION_LOG="\${CLAUDE_PROJECT_DIR:-.}/.claude/logs/detections.log"
 
@@ -262,7 +406,8 @@ export const SCAN_READ_INPUT_SH = `#!/bin/bash
 # binary, including actor resolution, exclude-dir filtering, content cap, and
 # detection-log writing.
 BIN="\${AI_SCANNER_BIN:-$HOME/.claude/bin/ai-scanner}"
-[ ! -x "$BIN" ] && exit 0
+${UNSCANNED_NOTE}
+[ ! -x "$BIN" ] && { note_unscanned; exit 0; }
 
 export AI_SCANNER_DETECTION_LOG="\${CLAUDE_PROJECT_DIR:-.}/.claude/logs/detections.log"
 
@@ -279,7 +424,8 @@ export const SCAN_WEBFETCH_SH = `#!/bin/bash
 # PreToolUse hook for WebFetch: Scan URL before Claude fetches it.
 # Thin Claude Code adapter — Rust handles phishing scoring + YARA + detection log.
 BIN="\${AI_SCANNER_BIN:-$HOME/.claude/bin/ai-scanner}"
-[ ! -x "$BIN" ] && exit 0
+${UNSCANNED_NOTE}
+[ ! -x "$BIN" ] && { note_unscanned; exit 0; }
 
 export AI_SCANNER_DETECTION_LOG="\${CLAUDE_PROJECT_DIR:-.}/.claude/logs/detections.log"
 
@@ -295,7 +441,8 @@ export const SCAN_WEBSEARCH_SH = `#!/bin/bash
 # PostToolUse hook for WebSearch: Scan search results for phishing URLs.
 # Thin Claude Code adapter — Rust handles cap, phishing scoring, detection log.
 BIN="\${AI_SCANNER_BIN:-$HOME/.claude/bin/ai-scanner}"
-[ ! -x "$BIN" ] && exit 0
+${UNSCANNED_NOTE}
+[ ! -x "$BIN" ] && { note_unscanned; exit 0; }
 
 export AI_SCANNER_DETECTION_LOG="\${CLAUDE_PROJECT_DIR:-.}/.claude/logs/detections.log"
 
@@ -354,6 +501,8 @@ export CLAUDE_PROJECT_DIR="\${CLAUDE_PROJECT_DIR:-.}"
 # \`timeout\` (timed out) is mapped to 0 so a hung scanner never blocks the
 # tool call. Bare macOS (no coreutils) falls through without a timeout —
 # install coreutils (\`brew install coreutils\`) to get the safety net.
+${UNSCANNED_NOTE}
+
 run_scanner() {
   if command -v timeout >/dev/null 2>&1; then
     timeout --kill-after=2s "\${AI_SCANNER_HOOK_TIMEOUT}" "\${AI_SCANNER_BIN}" "$@"
@@ -388,7 +537,7 @@ EOF
 export const CURSOR_PRE_SHELL_SH = `#!/bin/bash
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 source "$SCRIPT_DIR/env.sh"
-BIN="$AI_SCANNER_BIN"; [ ! -x "$BIN" ] && exit 0
+BIN="$AI_SCANNER_BIN"; [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
 export AI_SCANNER_DETECTION_LOG
 jq -r '.tool_input.command // ""' | run_scanner scan bash-input
 `;
@@ -396,7 +545,7 @@ jq -r '.tool_input.command // ""' | run_scanner scan bash-input
 export const CURSOR_PRE_READ_SH = `#!/bin/bash
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 source "$SCRIPT_DIR/env.sh"
-BIN="$AI_SCANNER_BIN"; [ ! -x "$BIN" ] && exit 0
+BIN="$AI_SCANNER_BIN"; [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
 export AI_SCANNER_DETECTION_LOG
 FILE_PATH=$(jq -r '.tool_input.file_path // ""')
 [ -z "$FILE_PATH" ] || [ "$FILE_PATH" = "null" ] && exit 0
@@ -406,7 +555,7 @@ run_scanner scan read-input --file "$FILE_PATH" </dev/null
 export const CURSOR_PRE_EDIT_SH = `#!/bin/bash
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 source "$SCRIPT_DIR/env.sh"
-BIN="$AI_SCANNER_BIN"; [ ! -x "$BIN" ] && exit 0
+BIN="$AI_SCANNER_BIN"; [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
 export AI_SCANNER_DETECTION_LOG
 INPUT=$(cat)
 FILE_PATH=$(jq -r '.tool_input.file_path // ""' <<<"$INPUT")
@@ -423,7 +572,7 @@ printf '%s' "$CONTENT" | run_scanner scan edit-input --file "$FILE_PATH"
 export const CURSOR_POST_SHELL_SH = `#!/bin/bash
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 source "$SCRIPT_DIR/env.sh"
-BIN="$AI_SCANNER_BIN"; [ ! -x "$BIN" ] && exit 0
+BIN="$AI_SCANNER_BIN"; [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
 export AI_SCANNER_DETECTION_LOG
 INPUT=$(cat)
 COMMAND=$(jq -r '.tool_output // ""' <<<"$INPUT" | head -1 && jq -r '.tool_input.command // ""' <<<"$INPUT")
@@ -433,7 +582,7 @@ jq -r '.tool_output // ""' <<<"$INPUT" | run_scanner scan bash-output --command
 export const CURSOR_POST_READ_SH = `#!/bin/bash
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 source "$SCRIPT_DIR/env.sh"
-BIN="$AI_SCANNER_BIN"; [ ! -x "$BIN" ] && exit 0
+BIN="$AI_SCANNER_BIN"; [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
 export AI_SCANNER_DETECTION_LOG
 INPUT=$(cat)
 FILE_PATH=$(jq -r '.tool_input.file_path // ""' <<<"$INPUT")
@@ -444,7 +593,7 @@ jq -r '.tool_output // ""' <<<"$INPUT" | run_scanner scan read-output --file "$F
 export const CURSOR_POST_WRITE_SH = `#!/bin/bash
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 source "$SCRIPT_DIR/env.sh"
-BIN="$AI_SCANNER_BIN"; [ ! -x "$BIN" ] && exit 0
+BIN="$AI_SCANNER_BIN"; [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
 export AI_SCANNER_DETECTION_LOG
 INPUT=$(cat)
 FILE_PATH=$(jq -r '.tool_input.file_path // ""' <<<"$INPUT")
@@ -475,7 +624,7 @@ return 0 2>/dev/null || true
 export const WINDSURF_PRE_COMMAND_SH = `#!/bin/bash
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 source "$SCRIPT_DIR/ensure_scanner.sh"
-BIN="$AI_SCANNER_BIN"; [ ! -x "$BIN" ] && exit 0
+BIN="$AI_SCANNER_BIN"; [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
 export AI_SCANNER_DETECTION_LOG
 CONTENT=$(jq -r '.tool_info.command_line // ""')
 [ -z "$CONTENT" ] || [ "$CONTENT" = "null" ] && exit 0
@@ -485,7 +634,7 @@ printf '%s' "$CONTENT" | run_scanner scan bash-input
 export const WINDSURF_PRE_READ_SH = `#!/bin/bash
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 source "$SCRIPT_DIR/ensure_scanner.sh"
-BIN="$AI_SCANNER_BIN"; [ ! -x "$BIN" ] && exit 0
+BIN="$AI_SCANNER_BIN"; [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
 export AI_SCANNER_DETECTION_LOG
 FILE_PATH=$(jq -r '.tool_info.file_path // ""')
 [ -z "$FILE_PATH" ] || [ "$FILE_PATH" = "null" ] && exit 0
@@ -495,7 +644,7 @@ run_scanner scan read-input --file "$FILE_PATH" </dev/null
 export const WINDSURF_PRE_WRITE_SH = `#!/bin/bash
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 source "$SCRIPT_DIR/ensure_scanner.sh"
-BIN="$AI_SCANNER_BIN"; [ ! -x "$BIN" ] && exit 0
+BIN="$AI_SCANNER_BIN"; [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
 export AI_SCANNER_DETECTION_LOG
 INPUT=$(cat)
 FILE_PATH=$(jq -r '.tool_info.file_path // ""' <<<"$INPUT")
@@ -507,7 +656,7 @@ printf '%s' "$CONTENT" | run_scanner scan edit-input --file "$FILE_PATH"
 export const WINDSURF_POST_READ_SH = `#!/bin/bash
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 source "$SCRIPT_DIR/ensure_scanner.sh"
-BIN="$AI_SCANNER_BIN"; [ ! -x "$BIN" ] && exit 0
+BIN="$AI_SCANNER_BIN"; [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
 export AI_SCANNER_DETECTION_LOG
 FILE_PATH=$(jq -r '.tool_info.file_path // ""')
 [ -z "$FILE_PATH" ] || [ ! -f "$FILE_PATH" ] && exit 0
@@ -517,7 +666,7 @@ run_scanner scan read-output --file "$FILE_PATH" < "$FILE_PATH"
 export const WINDSURF_POST_WRITE_SH = `#!/bin/bash
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 source "$SCRIPT_DIR/ensure_scanner.sh"
-BIN="$AI_SCANNER_BIN"; [ ! -x "$BIN" ] && exit 0
+BIN="$AI_SCANNER_BIN"; [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
 export AI_SCANNER_DETECTION_LOG
 FILE_PATH=$(jq -r '.tool_info.file_path // ""')
 [ -z "$FILE_PATH" ] || [ ! -f "$FILE_PATH" ] && exit 0
@@ -560,7 +709,7 @@ exec "$SCRIPT_DIR/start_scanner.sh"
 export const KIRO_PRE_SHELL_SH = `#!/bin/bash
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 source "$SCRIPT_DIR/env.sh"
-BIN="$AI_SCANNER_BIN"; [ ! -x "$BIN" ] && exit 0
+BIN="$AI_SCANNER_BIN"; [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
 export AI_SCANNER_DETECTION_LOG
 jq -r '.tool_input.command // ""' | run_scanner scan bash-input
 `;
@@ -568,7 +717,7 @@ jq -r '.tool_input.command // ""' | run_scanner scan bash-input
 export const KIRO_PRE_READ_SH = `#!/bin/bash
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 source "$SCRIPT_DIR/env.sh"
-BIN="$AI_SCANNER_BIN"; [ ! -x "$BIN" ] && exit 0
+BIN="$AI_SCANNER_BIN"; [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
 export AI_SCANNER_DETECTION_LOG
 FILE_PATH=$(jq -r '.tool_input.file_path // .tool_input.operations[0].path // ""')
 [ -z "$FILE_PATH" ] || [ "$FILE_PATH" = "null" ] && exit 0
@@ -578,7 +727,7 @@ run_scanner scan read-input --file "$FILE_PATH" </dev/null
 export const KIRO_PRE_WRITE_SH = `#!/bin/bash
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 source "$SCRIPT_DIR/env.sh"
-BIN="$AI_SCANNER_BIN"; [ ! -x "$BIN" ] && exit 0
+BIN="$AI_SCANNER_BIN"; [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
 export AI_SCANNER_DETECTION_LOG
 INPUT=$(cat)
 FILE_PATH=$(jq -r '.tool_input.file_path // .tool_input.path // ""' <<<"$INPUT")
@@ -590,7 +739,7 @@ printf '%s' "$CONTENT" | run_scanner scan edit-input --file "$FILE_PATH"
 export const KIRO_POST_SHELL_SH = `#!/bin/bash
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 source "$SCRIPT_DIR/env.sh"
-BIN="$AI_SCANNER_BIN"; [ ! -x "$BIN" ] && exit 0
+BIN="$AI_SCANNER_BIN"; [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
 export AI_SCANNER_DETECTION_LOG
 INPUT=$(cat)
 COMMAND=$(jq -r '.tool_input.command // ""' <<<"$INPUT")
@@ -601,7 +750,7 @@ printf '%s' "$RESPONSE" | run_scanner scan bash-output --command "$COMMAND"
 export const KIRO_POST_READ_SH = `#!/bin/bash
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 source "$SCRIPT_DIR/env.sh"
-BIN="$AI_SCANNER_BIN"; [ ! -x "$BIN" ] && exit 0
+BIN="$AI_SCANNER_BIN"; [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
 export AI_SCANNER_DETECTION_LOG
 INPUT=$(cat)
 FILE_PATH=$(jq -r '.tool_input.file_path // .tool_input.operations[0].path // ""' <<<"$INPUT")
@@ -613,7 +762,7 @@ printf '%s' "$RESPONSE" | run_scanner scan read-output --file "$FILE_PATH"
 export const KIRO_POST_WRITE_SH = `#!/bin/bash
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 source "$SCRIPT_DIR/env.sh"
-BIN="$AI_SCANNER_BIN"; [ ! -x "$BIN" ] && exit 0
+BIN="$AI_SCANNER_BIN"; [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
 export AI_SCANNER_DETECTION_LOG
 INPUT=$(cat)
 FILE_PATH=$(jq -r '.tool_input.file_path // .tool_input.path // ""' <<<"$INPUT")
@@ -635,7 +784,8 @@ export function getGeminiPreHookSh(binary) {
 # the run_scanner timeout helper is inlined here. See agentEnvSh for the
 # canonical version and the rationale for fail-open on exit 124.
 BIN="${binary}"
-[ ! -x "$BIN" ] && exit 0
+${UNSCANNED_NOTE}
+[ ! -x "$BIN" ] && { note_unscanned; exit 0; }
 
 run_scanner() {
   if command -v timeout >/dev/null 2>&1; then
@@ -705,7 +855,7 @@ export const CODEX_PRE_SHELL_SH = `#!/bin/bash
 # Codex PreToolUse Bash hook: scan command and return block JSON to Codex.
 SCRIPT_DIR="$(cd "$(dirname "\${BASH_SOURCE[0]:-$0}")" && pwd)"
 source "$SCRIPT_DIR/env.sh"
-BIN="$AI_SCANNER_BIN"; [ ! -x "$BIN" ] && exit 0
+BIN="$AI_SCANNER_BIN"; [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
 export AI_SCANNER_DETECTION_LOG
 INPUT=$(cat)
 CMD=$(jq -r '.tool_input.command // ""' <<<"$INPUT" 2>/dev/null)
@@ -735,7 +885,7 @@ export const CODEX_POST_SHELL_SH = `#!/bin/bash
 # Codex PostToolUse Bash hook: scan command output and return feedback JSON.
 SCRIPT_DIR="$(cd "$(dirname "\${BASH_SOURCE[0]:-$0}")" && pwd)"
 source "$SCRIPT_DIR/env.sh"
-BIN="$AI_SCANNER_BIN"; [ ! -x "$BIN" ] && exit 0
+BIN="$AI_SCANNER_BIN"; [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
 export AI_SCANNER_DETECTION_LOG
 INPUT=$(cat)
 CMD=$(jq -r '.tool_input.command // ""' <<<"$INPUT" 2>/dev/null)

package/src/verify.mjs

@@ -40,6 +40,17 @@ export function downloadBaseOverride(env = process.env) {
   return null;
 }
 
+/**
+ * Is this download base the DEV endpoint? Used by the hook templates to quote
+ * the right installer back at the user (the DEV package must never tell anyone
+ * to install PROD). Derived from `ENDPOINTS` rather than matched against a
+ * literal, so changing the DEV endpoint cannot leave a second, stale copy of
+ * that decision behind.
+ */
+export function isDevDownloadBase(base = "") {
+  return typeof base === "string" && base.startsWith(ENDPOINTS.dev);
+}
+
 export function downloadBase(env = "prod") {
   const override = downloadBaseOverride();
   if (override) return `${override}/download`;