@coworker-jp/aidr 0.1.290 → 0.1.293

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coworker-jp/aidr",
-  "version": "0.1.290",
+  "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

@@ -40,19 +40,142 @@ export function detectOpengrepPlatform() {
   throw new Error(`Unsupported platform for Opengrep: ${os}/${arch}`);
 }
 
+/**
+ * An HTTP status the download endpoint actually returned, carried on the error
+ * so callers can tell "this release does not exist" (404) apart from "the key
+ * was rejected" (403), "the service is unwell" (5xx) and "the network died"
+ * (no status at all). A plain `Error` with the status only in its message forces
+ * callers to regex-match prose, which is how a credential problem ends up
+ * being handled as a release problem.
+ */
+export class HttpStatusError extends Error {
+  constructor(url, status) {
+    super(`GET ${url} -> HTTP ${status}`);
+    this.name = "HttpStatusError";
+    this.status = status;
+    this.url = url;
+  }
+}
+
 async function fetchBuffer(url, accessKey) {
   const headers = accessKey ? { "x-access-key": accessKey } : {};
   const res = await fetch(url, { redirect: "follow", headers });
-  if (!res.ok) throw new Error(`GET ${url} -> HTTP ${res.status}`);
+  if (!res.ok) throw new HttpStatusError(url, res.status);
   const ab = await res.arrayBuffer();
   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) {
@@ -65,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);
@@ -100,16 +248,57 @@ export async function fetchAsset(binUrl, destPath, { accessKey } = {}) {
 
 /**
  * Download ai-scanner for the current platform into `destPath`.
- * Returns { path, platform, sha256, verified }.
+ *
+ * TWO KEYS, ONE FALLBACK (issue #1687)
+ * ------------------------------------
+ * The PROD npm package pins its own version, so it asks for `v{X.Y.Z}/{platform}`.
+ * That key exists only once the release's 4-platform upload has actually landed
+ * in S3 — and the version bump and the upload fire on the same push with no
+ * ordering between them, so for a window (7.8 hours on 2026-08-22's v0.1.289)
+ * the pinned key is a definite 404 while the *unpinned* key
+ * `{platform}` — the one the verify Lambda gates, which serves the last
+ * fully-published release (#176 / #387) — is serving a working binary the whole
+ * time. Without a fallback the client is the only party that does not know this.
+ *
+ * ONLY a definite 404 falls back:
+ *   - 403 means the access key was rejected. The unpinned key would reject it
+ *     too, and retrying would blur a credential problem into a release problem.
+ *   - 5xx / network failure is NOT evidence of absence — same rule, and the same
+ *     reasoning, as the release-readiness gate's fail-open
+ *     (`aidr_common/release_publication.py`: "Only a *definite* not-found
+ *     suppresses the version").
+ * The pin itself is NOT weakened: a healthy pinned fetch is used as-is and never
+ * consults the unpinned key. The pin exists so a machine installing during a
+ * release gets the release it asked for; the fallback only covers the case where
+ * that release provably has no bytes behind it.
+ *
+ * Returns { path, platform, sha256, verified, requestedVersion, servedUnpinned }.
+ * `servedUnpinned: true` means the caller must NOT claim the pinned version was
+ * installed — what landed is whatever the endpoint currently publishes.
  */
-export async function fetchBinary(destPath, { env = "prod", accessKey, version } = {}) {
+export async function fetchBinary(destPath, { env = "prod", accessKey, version, baseUrl } = {}) {
   const platform = detectPlatform();
-  const base = downloadBase(env);
-  const pathPrefix = version ? `v${version}/` : "";
-  const binUrl = `${base}/${pathPrefix}${platform}`;
+  const base = baseUrl || downloadBase(env);
+  const unpinnedUrl = `${base}/${platform}`;
+
+  if (!version) {
+    const result = await fetchAsset(unpinnedUrl, destPath, { accessKey });
+    return { ...result, platform, requestedVersion: null, servedUnpinned: false };
+  }
 
-  const result = await fetchAsset(binUrl, destPath, { accessKey });
-  return { ...result, platform };
+  try {
+    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 };
+  }
 }
 
 // Pinned Opengrep release used by aidr. Must be updated in lockstep with

package/src/cli.mjs

@@ -10,10 +10,11 @@ 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";
+import { formatMissingBinaryStatus, formatPartialBinaryStatus } from "./install-status.mjs";
 
 // Package identity — read at module load from the bundled package.json.
 // The PROD publish workflow renames the package to `@coworker-jp/aidr`;
@@ -31,6 +32,11 @@ const IS_PROD_PACKAGE = PKG.name === "@coworker-jp/aidr";
 const PINNED_VERSION = IS_PROD_PACKAGE ? PKG.version : undefined;
 const DEFAULT_ENV = IS_PROD_PACKAGE ? "prod" : "dev";
 
+// The command to quote back at the user when they have to re-run. Built from
+// the package that is actually running, so the DEV package never tells anyone
+// to install PROD.
+const INSTALL_COMMAND_HINT = `npx ${PKG.name} install --agent <agents> --key <access key>`;
+
 const ACCESS_KEY_RE = /^ak_[A-Za-z0-9_-]{43}$/;
 
 function validateKey(key) {
@@ -164,6 +170,12 @@ async function cmdInstall(opts) {
     }
   }
 
+  // Outcome of the binary step, read again at the end of the install to write
+  // the closing status. `needed` distinguishes "no binary was asked for"
+  // (--skip-binary, stub-only agent set) from "a binary was asked for and did
+  // not arrive" — the two must never print the same closing line.
+  const binaryOutcome = { needed: false, scannerInstalled: false, error: null };
+
   if (!opts.skipBinary && !opts.dryRun) {
     const agentBinDirs = [];
     for (const name of agents) {
@@ -175,6 +187,7 @@ async function cmdInstall(opts) {
     if (agentBinDirs.length === 0) {
       console.error("no agents with binary support selected; skipping binary fetch");
     } else {
+      binaryOutcome.needed = true;
       try {
         const [primaryDir, ...restDirs] = agentBinDirs;
         const fetchOpts = {
@@ -187,12 +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);
-        console.log(`binary: ${scannerRes.path} (${scannerRes.platform}${scannerRes.verified ? ", sha256 verified" : ""})`);
+        const scannerRes = assertVerified(
+          await fetchBinary(path.join(primaryDir, "ai-scanner"), fetchOpts),
+          "the ai-scanner binary",
+        );
+        binaryOutcome.scannerInstalled = true;
+        // 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 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) => {
@@ -226,8 +257,9 @@ async function cmdInstall(opts) {
         );
         await Promise.all(copyOps);
       } catch (e) {
+        binaryOutcome.error = e;
         console.error(`binary fetch failed: ${e.message}`);
-        if (!opts.binaryOnly) console.error("continuing with hook install (use --skip-binary to suppress)");
+        if (!opts.binaryOnly) console.error("continuing with hook install; the closing status below says what this machine is protected by.");
         else process.exit(1);
       }
     }
@@ -248,7 +280,14 @@ async function cmdInstall(opts) {
       for (const bp of backups) {
         console.log(`[${name}] existing file backed up to ${bp}`);
       }
-      return { name, displayName: mod.meta.displayName || name };
+      // Derived, never declared: an agent can re-fetch a missing binary at the
+      // start of its next session iff its install actually wrote a
+      // start_scanner.sh (templates.mjs — it pulls from the UNPINNED key). A
+      // boolean on `meta` would rot the first time an agent gains or loses that
+      // script; reading the written file list cannot.
+      const selfHeals = Boolean(res && Array.isArray(res.installed)
+        && res.installed.some((p) => path.basename(p) === "start_scanner.sh"));
+      return { name, displayName: mod.meta.displayName || name, selfHeals, needsBinary: Boolean(mod.meta.agentDir) };
     } catch (e) {
       console.error(`[${name}] install failed: ${e.message}`);
       process.exit(1);
@@ -306,6 +345,41 @@ async function cmdInstall(opts) {
       console.log("Click Allow — the scanner uses this to collect endpoint info (login items).");
     }
   }
+
+  // ── Closing status (issue #1687) ──────────────────────────────────────
+  // LAST, on purpose. The per-agent lines above all say "installed", and a
+  // warning printed before them scrolls out of sight on a real terminal. If a
+  // binary was asked for and did not arrive, the run ends by saying so.
+  if (binaryOutcome.needed && binaryOutcome.error) {
+    const reason = binaryOutcome.error.message;
+    if (binaryOutcome.scannerInstalled) {
+      console.error(formatPartialBinaryStatus({ reason, installCommand: INSTALL_COMMAND_HINT }));
+      return;
+    }
+    const needBinary = installResults.filter((r) => r.needsBinary);
+    const selfHealing = needBinary.filter((r) => r.selfHeals).map((r) => r.displayName);
+    const stranded = needBinary.filter((r) => !r.selfHeals).map((r) => r.displayName);
+    const binPaths = (await Promise.all(needBinary.map(async (r) => {
+      const mod = await loadAgent(r.name);
+      return mod.meta.agentDir ? path.join(home, mod.meta.agentDir, "bin", "ai-scanner") : null;
+    }))).filter(Boolean);
+    console.error(formatMissingBinaryStatus({
+      reason, selfHealing, stranded, binPaths, installCommand: INSTALL_COMMAND_HINT,
+    }));
+    // EXIT CODE. Default installs stay 0 when every agent that needs the
+    // binary can fetch it itself at the next session start: the hooks really
+    // are installed, they really do self-heal, and turning that red would
+    // break scripted installs for a condition that usually resolves on its
+    // own. But when at least one installed agent needs the binary and has NO
+    // self-heal path (gemini's hook is `[ ! -x "$BIN" ] && exit 0`; standalone
+    // has no hooks at all), nothing on this machine will ever fetch it again.
+    // Exiting 0 there is the CLI asserting an install that did not happen, so
+    // it exits 1. Verified against the consumers in this repo: both smoke
+    // harnesses (tests/smoke/aidr-matrix.sh — `--skip-binary`;
+    // tests/smoke/aidr-upgrade.sh — `--agent claude`, self-healing) are
+    // unaffected in either direction.
+    if (stranded.length > 0) process.exit(1);
+  }
 }
 
 async function cmdUninstall(opts) {
@@ -506,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/install-status.mjs

@@ -0,0 +1,114 @@
+// Closing status for `aidr install` — the last thing the user reads.
+//
+// WHY THIS IS A SEPARATE, TESTABLE MODULE (issue #1687)
+// ----------------------------------------------------
+// Before this existed, an install that obtained no scanner binary printed one
+// warning line and then `continuing with hook install`, and exited 0. Forty
+// lines of per-agent output later, the run looked exactly like a successful
+// one. The machine was configured and unprotected at the same time, and the
+// only sentence about it had scrolled away.
+//
+// docs/product/UI_COPY.md, two 【非交渉】 rules, both of which apply here:
+//   1. A failure sentence never ends at the fact. It carries the next action.
+//      Rewriting it into a success sentence is explicitly forbidden.
+//   2. "Unknown" must not read as "safe", and must not be defended with a
+//      negation ("this does not mean ..."). The uncertainty is stated on the
+//      fact side instead.
+// Both are load-bearing here: whether the hooks' own download succeeds at the
+// next session start is genuinely unknown at install time, and saying nothing
+// about it is what made this defect ship.
+
+const RULE = "─".repeat(72);
+
+function bulletList(names) {
+  return names.join(", ");
+}
+
+/**
+ * The machine has no scanner binary. `selfHealing` are the installed agents
+ * whose hooks re-try the download at the start of their next session
+ * (start_scanner.sh, unpinned key); `stranded` are the installed agents that
+ * need the binary and have no such retry — for them nothing on this machine
+ * will ever fetch it again on its own.
+ */
+export function formatMissingBinaryStatus({
+  reason,
+  selfHealing = [],
+  stranded = [],
+  binPaths = [],
+  installCommand = "npx @coworker-jp/aidr install ...",
+}) {
+  const lines = [
+    "",
+    RULE,
+    "This machine is NOT being scanned yet — the ai-scanner binary is not in place.",
+    "",
+    `  what stopped it: ${reason}`,
+    "",
+  ];
+
+  if (selfHealing.length > 0) {
+    lines.push(
+      `The hooks for ${bulletList(selfHealing)} are installed, and they try to`,
+      "download the binary once at the start of the next session.",
+      "Whether that download will succeed is unknown from here: nothing on this",
+      "machine has checked it yet, and until it lands, tool calls are unscanned.",
+      "",
+    );
+  }
+  if (stranded.length > 0) {
+    lines.push(
+      `${bulletList(stranded)} will not re-try: the hooks for those agents exit`,
+      "without scanning while the binary is missing, and nothing on this machine",
+      "fetches it again.",
+      "Re-running this installer is the only thing that puts it in place.",
+      "",
+    );
+  }
+
+  lines.push("Do this next:");
+  lines.push(`  1. Re-run the installer once the network and the access key are working:`);
+  lines.push(`       ${installCommand}`);
+  if (binPaths.length > 0) {
+    lines.push("  2. Confirm the binary is there afterwards:");
+    for (const p of binPaths) lines.push(`       ls -l ${p}`);
+    lines.push("  3. If it is still missing, contact your IT administrator and show them");
+    lines.push("     the 'binary fetch failed' line above.");
+  } else {
+    lines.push("  2. If it still does not arrive, contact your IT administrator and show");
+    lines.push("     them the 'binary fetch failed' line above.");
+  }
+  lines.push(RULE);
+  lines.push("");
+  return lines.join("\n");
+}
+
+/**
+ * The scanner binary IS in place, but a later step of the binary install threw
+ * (the bundled Opengrep engine, or the copy into the other agents' bin dirs).
+ * Protection exists, so this must not be dressed up as an outage — but the
+ * install is incomplete and saying "installed" alone would hide that.
+ */
+export function formatPartialBinaryStatus({
+  reason,
+  installCommand = "npx @coworker-jp/aidr install ...",
+}) {
+  return [
+    "",
+    RULE,
+    "Scanning is active on this machine, but the binary step did not finish.",
+    "",
+    `  what stopped it: ${reason}`,
+    "",
+    "Which agents received their own copy of the scanner, and whether the",
+    "code-analysis engine (opengrep) is present, is unknown from here. While",
+    "opengrep is absent the code-analysis rules stay switched off.",
+    "",
+    "Do this next:",
+    `  1. Re-run the installer to complete it: ${installCommand}`,
+    "  2. If it stops at the same place, contact your IT administrator and show",
+    "     them the 'binary fetch failed' line above.",
+    RULE,
+    "",
+  ].join("\n");
+}

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

@@ -14,7 +14,46 @@ export function verifyEndpoint(env = "prod") {
   return `${base}/verify`;
 }
 
+// `AIDR_DOWNLOAD_BASE` redirects the licensed download endpoint, but ONLY to
+// loopback. It is a TEST SEAM, not a configuration knob: the object it fetches
+// IS the protection, so an env var able to point it at an arbitrary host would
+// be a supply-chain hole in a security product. Restricted to loopback, anyone
+// who can set it already owns the machine and gains nothing they did not have.
+// A non-loopback value is refused *out loud* rather than silently ignored — a
+// mis-set variable that quietly does nothing is the "silently lies" shape this
+// repo keeps paying for.
+const LOOPBACK_BASE_RE = /^http:\/\/(?:127\.0\.0\.1|localhost|\[::1\])(?::\d+)?(?:\/|$)/;
+let warnedAboutDownloadBase = false;
+
+export function downloadBaseOverride(env = process.env) {
+  const raw = env.AIDR_DOWNLOAD_BASE;
+  if (!raw) return null;
+  if (LOOPBACK_BASE_RE.test(raw)) return raw.replace(/\/+$/, "");
+  if (!warnedAboutDownloadBase) {
+    warnedAboutDownloadBase = true;
+    console.warn(
+      `warning: AIDR_DOWNLOAD_BASE is set to a non-loopback URL and was refused; ` +
+      `the built-in download endpoint is being used instead. ` +
+      `Unset it, or point it at http://127.0.0.1:<port> if you are running tests.`,
+    );
+  }
+  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`;
   const base = ENDPOINTS[env] || ENDPOINTS.prod;
   return `${base}/download`;
 }