@coworker-jp/aidr 0.1.290 → 0.1.292

package/package.json

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

package/src/binary-fetcher.mjs

@@ -40,10 +40,27 @@ 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);
 }
@@ -100,16 +117,52 @@ 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) {
+    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

@@ -14,6 +14,7 @@ import { fetchBinary, fetchOpengrep } 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 = {
@@ -188,7 +201,15 @@ async function cmdInstall(opts) {
         // 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);
+        binaryOutcome.scannerInstalled = true;
         console.log(`binary: ${scannerRes.path} (${scannerRes.platform}${scannerRes.verified ? ", 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: 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"));
@@ -226,8 +247,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 +270,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 +335,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) {

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/verify.mjs

@@ -14,7 +14,35 @@ 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;
+}
+
 export function downloadBase(env = "prod") {
+  const override = downloadBaseOverride();
+  if (override) return `${override}/download`;
   const base = ENDPOINTS[env] || ENDPOINTS.prod;
   return `${base}/download`;
 }