penthera 1.8.1 → 1.9.0-rc.1

package/CHANGELOG.md

@@ -4,6 +4,187 @@ All notable changes to Penthera are documented here. Versioning follows [SemVer]
 
 ## [Unreleased]
 
+## [1.9.0-rc.1] - 2026-10-22
+
+Release candidate for 1.9.0, on npm's `next` dist-tag (`npm install penthera@next`).
+New: `penthera mcp` (an MCP server for coding agents, local and read-only by
+default), opt-in AI mode where a local model proposes and Penthera's rules
+verify, new detection rules, and default scans that send no attack payloads.
+
+### Added
+
+- **Coverage ledger** in every `--repo` report (terminal, Markdown, JSON
+  `coverage`): which files each check read, which it did not and why, and the
+  source files no code analysis looked at. It reads only file names and sizes,
+  and is the first step toward an opt-in AI mode.
+- **AI mode, opt-in and experimental: `penthera --repo . --ai`.** A model in
+  your local Ollama reads your code part by part and proposes problems no rule
+  describes; Penthera checks each proposal with its rules. Confirmed ones mark
+  the rule finding "also proposed by AI"; the rest are shown as
+  "model-proposed, unverified", apart from rule findings, and never change the
+  exit code. Every run asks first (default no), on stderr; runs that cannot ask
+  need `--ai-consent local` or `"ai": { "allow": ["local"] }` in
+  `penthera.policy.json`, or stop with exit 2 before scanning. Ollama cloud
+  models (`-cloud`) are recognised and need a second screen where you type
+  `ollama.com`. Secrets are masked before any code reaches the model; budgets
+  (`--ai-budget`) are hard stops; consents are logged locally
+  (`penthera ai consent`). `penthera ai models` lists models and where they
+  run. See [docs/ai-mode.md](docs/ai-mode.md).
+- **AI mode in the dashboard.** New scan has an AI mode switch, off; turning
+  it on opens the consent sheet on every scan (a picture of where the code
+  goes, the model picker, the terminal's exact consent lines, two equal
+  buttons; cloud models need `ollama.com` typed). The server checks the
+  model's route with Ollama itself and logs the consent. Runs show an
+  "AI · local" tag, unverified proposals are folded under their own heading,
+  and Settings lists the consent log.
+- **`penthera verify <findings.json>`** checks findings from an AI security
+  audit against Penthera's rules on your checkout. It reads Cloudflare's
+  security-audit skill `findings.json` (schema vendored from commit `c1c8a8c`,
+  MIT). A finding a rule agrees with is shown as Penthera's own finding, marked
+  "also proposed by" the model; the rest are labelled "model-proposed,
+  unverified" and never fail CI. Penthera runs no model and sends nothing
+  anywhere. See [docs/commands/verify.md](docs/commands/verify.md).
+- **`--audit-seeds <file>`** writes repo findings in the security-audit
+  skill's `findings.json` schema, as seeds for an AI audit: each entry is
+  `needs_validation`, names its class and the line the rule matched, and is
+  checked against the skill's schema before it is written.
+- Risky-pattern findings from `--repo` now carry the repo-relative `file` and
+  the `pattern` name.
+- **`penthera mcp`: Penthera as an MCP server for your coding agent.** Claude
+  Code, Cursor, Codex, VS Code and Windsurf can call it over stdio. Add it
+  with a pinned version: `claude mcp add penthera -- npx -y penthera@1.9.0 mcp`.
+  Six read-only tools: `scan_repo`, `scan_url` (passive only),
+  `check_dependencies`, `audit_ai_tooling`, `explain_finding` and
+  `runtime_advisories`. Results are structured JSON plus a summary, with
+  evidence at `file:line`, confidence labels and each tool's limits.
+  - Tools read only inside the workspace roots, and symlinks cannot lead
+    out. `scan_url` reaches loopback, or hosts you list with
+    `--allow-host`; active modes are not reachable over MCP.
+  - Text from scanned files has invisible characters removed and is marked
+    as data, so a file cannot steer the agent through the results.
+  - Speaks MCP 2026-07-28 and the earlier `initialize` versions. No new
+    dependency, no port, no telemetry.
+  - `server.json` and `mcpName` for the MCP Registry
+    (`io.github.danoszz/penthera`). See `docs/commands/mcp.md`.
+- **Secret findings carry the line number**, so reports and SARIF point at
+  the line.
+
+### Detection
+
+- Three exposure checks in the default URL scan, each a documented miss in
+  the E10 pilot (Juice Shop). All send plain `GET`s, no payloads:
+  - a public Prometheus `/metrics` endpoint (medium), matched on the
+    exposition format, so an SPA's index page at `/metrics` does not count;
+  - browsable directory listings (medium) in folders that `robots.txt`
+    disallows and in common upload and backup folders, matched on the
+    listing's page title;
+  - a stack trace in the error page for a path that does not exist (low),
+    matched on Node.js, Python, Java, PHP and .NET frame shapes.
+- The header audit reports an `X-Powered-By` header (low, `confirmed`), such
+  as Express's default `X-Powered-By: Express`. It was a documented miss in
+  the E10 pilot (DVNA). The finding names the value and how to turn the
+  header off.
+- The secret scan reads Terraform and HCL files (`.tf`, `.tfvars`, `.hcl`).
+  A private key inline in a Terraform file was a documented miss in the E10
+  pilot (Juice Shop).
+- New secret rule: a session signing secret written into
+  `session({ secret: '...' })` or `cookieSession(...)`, including a hardcoded
+  fallback after `process.env.X ||` (high). Express's documented example,
+  `'keyboard cat'`, was a documented miss in the E10 pilot (DVNA).
+- The repo scan looks for code-execution sinks in all server code, not just
+  route handlers: `eval`/`new Function` with a non-constant argument, `vm`
+  calls and `child_process` `exec` with request data in their arguments.
+  A taint-lite pass (assignments and destructuring within one file) sets the
+  confidence: `likely` when request data reaches the sink, `potential` for an
+  `eval` of a value it cannot trace. Before, a repo with an Express `routes/`
+  folder stopped before any code-pattern check; three E10 pilot misses (DVNA's
+  `exec` in `core/appHandler.js`, Juice Shop's B2B `vm` and profile `eval`)
+  came from this.
+- The advisories pack knows MongoDB: end-of-life lines from MongoDB's
+  lifecycle schedule (4.4 ended 2024-02-29, 5.0 on 2024-10-31, 6.0 on
+  2025-07-31, and the interim releases), matched against the official `mongo`
+  image in Dockerfiles and compose files and `mongodb` in `.tool-versions`.
+  `mongo:4.4.29` in Juice Shop's compose file was a documented miss in the
+  E10 pilot. **The pack is unsigned in this change**: the maintainer signs it
+  (`scripts/rules/sign-pack.sh`) before release.
+
+### Changed
+
+- **Faster merges for contributors.** Pull requests get a quicker install check
+  (Linux and macOS, Node 22), and docs-, site- or benchmark-only changes skip it.
+  The merge queue and `main` still run the full matrix (Linux, macOS and
+  Windows on Node 22 and 24, plus the upgrade test). Release notes are written
+  as fragments in `changelog.d/`, so parallel pull requests no longer conflict
+  on `CHANGELOG.md`.
+- **The default scan sends no attack payloads to your login.** A URL scan
+  used to POST nine logins and an `' OR '1'='1` string to `/api/login`,
+  which a CDN firewall (Vercel, Cloudflare) can read as an attack and start
+  challenging you. Now `quick` sends no login request, `standard` sends one
+  login with invalid credentials (to catch a login that accepts anything),
+  and the rate-limit burst and the SQL error check run only with `--deep`.
+  The MCP `scan_url` tool follows the same profiles.
+
+### Fixed
+
+- `penthera ui` listens for SIGINT and SIGTERM before it prints that it is
+  listening. A signal that arrived in between got the default action and
+  killed the process without "Stopped." (seen as a hung CI test; about one
+  run in a hundred locally). The test now fails within seconds with the
+  child's output instead of hanging for three minutes.
+- `--repo` scans of Express, Hono and Fastify apps with a `routes/`, `api/` or
+  `server/routes/` folder now get route discovery, trust-boundary and
+  risky-pattern checks. That folder was taken for a Next.js API root, no
+  `route.js` files were found there, and route analysis stopped. An explicit
+  `--api-root` is still used as given.
+- **TLS keys anyone can compute.** URL scans report, as critical, any
+  certificate in the served chain whose EC public key (P-256, P-384, P-521) is
+  k·G for a private scalar k below 1024. The private key then follows from
+  the certificate alone. This is the flaw in eMudhra's P-384 intermediates
+  ([Mozilla bug 2083449](https://bugzilla.mozilla.org/show_bug.cgi?id=2083449),
+  private keys below 256). The check is arithmetic, not a list, so it has no
+  false positives and no data to maintain. Research note:
+  [docs/research/emudhra-weak-keys-2026-10.md](docs/research/emudhra-weak-keys-2026-10.md).
+- **Node.js security release of 21 October 2026** in the `advisories` pack:
+  CVE-2026-111497 (Brotli decoder out-of-bounds write, remote code execution)
+  and the TLS certificate hostname bypasses CVE-2026-106069, CVE-2026-105483
+  and CVE-2026-106072, fixed in 22.23.4, 24.22.1 and 26.12.1, from
+  [nodejs.org](https://nodejs.org/en/blog/vulnerability/october-2026-security-releases).
+  Node.js has no server banner, so repo scans find it (`.nvmrc`,
+  `.node-version`, `.tool-versions`, `node:` images); 20.x and 25.x are
+  reported as end-of-life lines. The pack's signature was removed with the
+  change; `npm run rules:check` fails until the maintainer re-signs it.
+- **Python start-up code in wheels.** `penthera deps` now finds `.pth` files
+  and a shipped `sitecustomize.py` / `usercustomize.py` wherever a wheel puts
+  them at the site-packages root, including `<name>-<version>.data/purelib/`
+  and `platlib/`, the layout the malicious litellm 1.107.0 used
+  ([OSV MAL-2026-2144](https://osv.dev/vulnerability/MAL-2026-2144)). Before,
+  only top-level `.pth` files were read, so that wheel's hook was missed until
+  it was installed. A `.pth` import of clean code is now medium (was low);
+  risky code behind it, or any shipped `sitecustomize.py`, is high. The
+  `penthera install` policy holds `startup-hook` for approval by default.
+- **PyPI indicators.** A new rule kind, `ioc-pypi-package` (PEP 503 names,
+  PEP 440 versions, kept apart from npm names), and a new bundled pack,
+  `ioc-pypi-2026`, with the litellm 1.82.7, 1.82.8 and 1.107.0 versions, the
+  1.107.0 payload files by SHA-256 and its endpoints. Python scans now run
+  `ioc-file` and `ioc-host` rules too. The pack is unsigned until the
+  maintainer signs it, so `npm run rules:check` fails until then.
+- **The pre-commit hook keeps working when the npx cache is cleaned.** A hook
+  installed through `npx penthera` pointed at a copy in npm's cache; once
+  that was gone, every commit skipped the check silently. It now falls back
+  to the same version through npx (`npx -y penthera@<version> hook run`,
+  pinned), and only skips, with a clear warning, when that cannot run either.
+
+### Site
+
+- The FAQ says how to scan your own site behind Vercel's or Cloudflare's
+  firewall: allow your IP first, or scan a preview URL.
+
+### Docs
+
+- README, ROADMAP and the research plan describe what is on main for 1.9
+  (`penthera mcp`, AI mode, new detection, no attack payloads by default) and
+  list the E10 benchmark.
+
 ## [1.8.1] - 2026-10-22
 
 A fixes-only release. Runtime advisories are more careful: pre-release builds
@@ -64,6 +245,28 @@ cleanly under `npx`.
   CSP now allows connections only to those two paths on penthera.org; the
   browser check still sends nothing, and the page says so. The CLI, the
   dashboard and the npm package have no telemetry, unchanged.
+- A shared penthera.org link now plays a 14-second muted reel in iMessage
+  and other apps that support `og:video`: setup, an offline scan, the
+  verdict, the PHP advisory of 21 October 2026, and the share card.
+  `og.png` stays the poster and the fallback; X keeps the image card.
+  Rendered by `site/tools/reel.mjs`.
+
+### Research
+
+- Draft protocol for experiment E10: Penthera against six deliberately
+  vulnerable apps with public answer keys (Juice Shop, DVNA, NodeGoat, DVWA,
+  crAPI, WebGoat), each pinned by commit and image digest. Answer keys in
+  `bench/known-vuln/`, frozen before any scan; an opt-in runner
+  (`npm run bench:known`, not in `npm test` or the package) starts the apps
+  isolated in Docker on 127.0.0.1. A pilot on Juice Shop and DVNA is in
+  `bench/known-vuln/RESULTS.md`, marked as a pilot.
+- Each of the pilot's 13 standard-run misses is verified in
+  `bench/known-vuln/MISSES.md` (all real gaps; none a scoring artefact).
+  A re-run after the fixes that followed (#107, #108, #110, #111) is in
+  `bench/known-vuln/RESULTS-after-fixes.md`, next to the unchanged pilot:
+  pooled standard recall 1/14 to 10/14 at the same precision, flagged as not
+  independent, with WebGoat as a held-out app that did not change. The
+  runner gains `--out <file>`.
 
 ### Docs
 

package/README.md

@@ -87,6 +87,21 @@ npx skills add danoszz/penthera
 The skill tells your agent to refuse targets you do not own or are not
 authorized to test. Other install routes (the one-line installer, the Claude
 Code plugin, a per-project copy) are in [docs/commands/skill.md](docs/commands/skill.md).
+
+### Use it from your agent
+
+Penthera is also an MCP server, so Claude Code, Cursor, Codex, VS Code and
+Windsurf can call it as a tool. Pin the version:
+
+```bash
+claude mcp add penthera -- npx -y penthera@1.9.0 mcp
+```
+
+It offers six read-only tools: `scan_repo`, `check_dependencies`,
+`audit_ai_tooling`, `runtime_advisories`, `explain_finding`, and `scan_url`
+(passive, loopback or hosts you list). Tools read only inside your project,
+never apply fixes, and run no shell. Configs for the other clients and the
+safety rules are in [docs/commands/mcp.md](docs/commands/mcp.md).
 Penthera needs Node.js 22 or later. To run it in a container:
 `docker build -t penthera . && docker run --rm penthera https://your-app.example`.
 
@@ -268,9 +283,9 @@ What changed, what we are measuring, and what comes next, in one place.
 | | Where it stands | Read more |
 |---|---|---|
 | **Latest release** | 1.8.1 (2026-10-22): more careful runtime advisories (pre-releases, distribution builds, older lines) on top of 1.8.0's runtime advisories, security-review fixes and redesigned dashboard | [CHANGELOG](CHANGELOG.md) |
-| **On main, unreleased** | Toward 1.9: AI mode (opt-in, local model, rules verify), new detection rules, the E10 benchmark | [Unreleased](CHANGELOG.md#unreleased) |
-| **Now** | Toward 1.9: accuracy on real code (E1) and an MCP server, so coding agents can call Penthera | [Roadmap](ROADMAP.md#next) |
-| **Research** | E1, accuracy on real code, is pre-registered; the benchmark tooling is in review. After the 2026 agent incidents: a checklist for running agents safely and a draft experiment (E8) | [E1 pre-registration](docs/research/prereg/E1-real-world-accuracy.md), [agents safely](docs/agents-safely.md), [what the incidents mean](docs/research/agent-incidents-2026.md) |
+| **On main, unreleased** | For 1.9: `penthera mcp` for coding agents, opt-in AI mode (a local model proposes, rules verify), new detection rules, no attack payloads in default scans | [Unreleased](CHANGELOG.md#unreleased) |
+| **Now** | 1.9.0-rc.1 on npm `next`, then accuracy on real code (E1) | [Roadmap](ROADMAP.md#on-main-for-19) |
+| **Research** | E10 pilot published: precision 0.88, recall 0.07 → 0.71 on two known-vulnerable apps after fixes (one labeller, not independent; a re-run is pending because default scans no longer send login checks). E1 on real code is pre-registered; E8 (agent guardrails) is a draft | [E10 results](bench/known-vuln/RESULTS.md), [E1 pre-registration](docs/research/prereg/E1-real-world-accuracy.md), [agents safely](docs/agents-safely.md) |
 | **Next** | Real-world precision and recall with intervals, published whatever the result | [Roadmap: next](ROADMAP.md#next), [research plan](docs/vision-2.0.md) |
 
 Releases are deliberately slow: a feature freeze, an independent review, the

package/lib/advisories/evidence.js

@@ -84,7 +84,7 @@ export function evidenceFromResponse(fp = {}, more = {}) {
 
 // ── White-box ─────────────────────────────────────────────────────────────
 
-const SKIP_DIRS = new Set([
+export const RUNTIME_PIN_SKIP_DIRS = new Set([
   "node_modules", ".git", "dist", "build", ".next", "coverage", "reports", "vendor",
   "venv", ".venv", "site-packages", "__pycache__", ".tox", ".nox", ".obsidian",
 ]);
@@ -96,7 +96,9 @@ const isCompose = (n) => /^(?:docker-)?compose(?:\.[\w-]+)?\.ya?ml$/i.test(n);
 const VERSION_FILES = new Set(Object.values(PRODUCTS).flatMap((p) => p.versionFiles));
 const ROOT_ONLY = new Set([".tool-versions", "runtime.txt", "composer.json"]);
 
-function wanted(name, depth) {
+/** Would the runtime-pin check read a file with this name at this folder depth (0 = repo root)? */
+export function isRuntimePinFile(name, depth) {
+  if (depth > MAX_DEPTH) return false;
   if (isDockerfile(name) || isCompose(name) || VERSION_FILES.has(name)) return true;
   return depth === 0 && ROOT_ONLY.has(name);
 }
@@ -122,10 +124,10 @@ function walk(dir, depth, files) {
   let entries;
   try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
   for (const e of entries) {
-    if (SKIP_DIRS.has(e.name)) continue;
+    if (RUNTIME_PIN_SKIP_DIRS.has(e.name)) continue;
     const full = join(dir, e.name);
     if (e.isFile()) {
-      if (wanted(e.name, depth)) files.push({ full, depth });
+      if (isRuntimePinFile(e.name, depth)) files.push({ full, depth });
       continue;
     }
     if (!e.isDirectory()) continue;

package/lib/advisories/products.js

@@ -76,6 +76,19 @@ export const PRODUCTS = Object.freeze({
     toolVersions: ["python"],
     versionFiles: [".python-version"],
   },
+  mongodb: {
+    branchOf: minorLine,
+    name: "MongoDB",
+    // Read only from the official image and .tool-versions, which are upstream builds.
+    backports: false,
+    checkCommand: "mongod --version",
+    // A database: no HTTP banner. Seen only in what the repository pins.
+    banner: null,
+    present: null,
+    dockerImages: ["mongo"],
+    toolVersions: ["mongodb"],
+    versionFiles: [],
+  },
   openssl: {
     branchOf: (v) => (v.major >= 3 ? minorLine(v) : v.patch === null ? null : `${v.major}.${v.minor}.${v.patch}`),
     name: "OpenSSL",

package/lib/ai/consent.js

@@ -0,0 +1,213 @@
+/**
+ * Consent for AI mode (docs/ai-mode.md, spec-ai-mode.md "Consent").
+ *
+ * Every `--ai` run asks. Nothing is remembered as permission: the log in
+ * ~/.penthera/consent.jsonl records what was agreed, for the user and for an
+ * auditor, and is never read back to skip a question.
+ *
+ * Two routes exist, and the text always states the one that applies:
+ * - local:        Ollama on 127.0.0.1 runs the model on this computer.
+ * - ollama-cloud: Ollama on 127.0.0.1 forwards the code to ollama.com. Needs a
+ *                 second screen where the user types the host.
+ *
+ * Interactive runs ask on stderr (stdout stays clean for --json). A run that
+ * cannot ask (CI, piped, --json) needs --ai-consent <route> or the policy
+ * file's "ai": { "allow": ... }, and a local consent never covers the cloud.
+ * Declining is never an error: the scan runs with rules only.
+ */
+import { appendFileSync, chmodSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+
+/** Bumped whenever the meaning of the consent text changes; a log entry records the version shown. */
+export const CONSENT_TEXT_VERSION = 1;
+export const ROUTES = ["local", "ollama-cloud"];
+export const CLOUD_HOST = "ollama.com";
+export const CONSENT_LOG = "consent.jsonl";
+
+export function consentLogPath(env = process.env) {
+  const base = env.PENTHERA_HOME ? resolve(env.PENTHERA_HOME) : join(homedir(), ".penthera");
+  return join(base, CONSENT_LOG);
+}
+
+/**
+ * The five (or six) lines of the consent screen, plus the question.
+ * @param {{ route: string, model: string, project: string, maxUnits: number, repro?: boolean }} p
+ */
+export function consentScreen({ route, model, project, maxUnits, repro = false }) {
+  const cloud = route === "ollama-cloud";
+  const lines = [
+    "",
+    "  AI mode: a model reads your code to look for problems the rules can't see.",
+    "",
+    cloud
+      ? `  Model     ${model}, through your local Ollama, run on ${CLOUD_HOST}`
+      : `  Model     ${model}, through Ollama on this computer (127.0.0.1)`,
+    `  Reads     up to ${maxUnits} parts of ${project}, with secrets masked`,
+    cloud
+      ? `  Sends     those parts to ${CLOUD_HOST} (you confirm the host next)`
+      : "  Sends     nothing off this computer",
+    "  Decides   nothing. Penthera checks every model finding with its own rules.",
+    "            Unchecked ones are labelled and never fail CI.",
+  ];
+  if (repro) lines.push(`  Runs      parts of ${project}'s own code in a sandbox with no network, to check findings`);
+  lines.push("");
+  return { text: lines.join("\n") + "\n", question: `  Use this model for ${project}? [y/N/details]: ` };
+}
+
+/** The second screen for a cloud model: the host is typed back. */
+export function cloudScreen({ project, maxUnits }) {
+  return {
+    text: [
+      "",
+      `  This model runs on ${CLOUD_HOST}, not on this computer.`,
+      "",
+      `  Sends     up to ${maxUnits} parts of ${project}, secrets masked, to ${CLOUD_HOST}`,
+      "            through your local Ollama, under Ollama's terms",
+      "",
+    ].join("\n") + "\n",
+    question: `  Type ${CLOUD_HOST} to send your code there, or press Enter to stop: `,
+  };
+}
+
+/** What `details` prints: the route in full, the model, and where consent is kept. */
+export function consentDetails({ route, model, digest, size, logPath }) {
+  const cloud = route === "ollama-cloud";
+  return [
+    "",
+    "  What happens",
+    cloud
+      ? `    Penthera sends code units, secrets masked, to Ollama on 127.0.0.1, which forwards them to ${CLOUD_HOST}.`
+      : "    Penthera sends code units, secrets masked, to Ollama on 127.0.0.1. Nothing else.",
+    cloud
+      ? `    Your code leaves this computer and is processed by ${CLOUD_HOST} under Ollama's terms.`
+      : "    The model runs on this computer. The report lists every host Penthera contacted.",
+    "    Penthera checks the address and the model. It cannot see whether something on",
+    "    this computer forwards port 11434 elsewhere.",
+    "    The model gets no tools, files, network or shell. Its findings are candidates:",
+    "    a Penthera rule confirms them, or they are shown as model-proposed, unverified.",
+    "",
+    "  Model",
+    `    ${model}${size ? ` (${formatBytes(size)})` : ""}${digest ? `, digest ${String(digest).slice(0, 19)}` : ""}`,
+    "",
+    "  Consent",
+    "    Asked on every run; nothing is remembered as permission.",
+    `    Each answer is logged on this computer only: ${logPath}`,
+    "    `penthera ai consent` shows the log.",
+    "",
+  ].join("\n") + "\n";
+}
+
+function formatBytes(n) {
+  return n >= 1e9 ? `${(n / 1e9).toFixed(1)} GB` : `${Math.round(n / 1e6)} MB`;
+}
+
+/**
+ * Decide consent without asking: the --ai-consent flag or the policy file.
+ * @returns {{ ok: true, via: "flag"|"policy" } | { ok: false, reason: string } | null} null when nothing was given
+ */
+export function consentWithoutAsking({ route, flag = null, policyAllow = null }) {
+  if (flag != null) {
+    if (!ROUTES.includes(flag)) return { ok: false, reason: `--ai-consent must be one of ${ROUTES.join(", ")} (got "${flag}").` };
+    if (flag === route) return { ok: true, via: "flag" };
+    return { ok: false, reason: route === "ollama-cloud"
+      ? `This model runs on ${CLOUD_HOST}. --ai-consent local does not cover it; use --ai-consent ollama-cloud to send code there.`
+      : `--ai-consent ${flag} does not match this model's route (${route}).` };
+  }
+  if (policyAllow) {
+    if (policyAllow.includes(route)) return { ok: true, via: "policy" };
+    return { ok: false, reason: `penthera.policy.json allows AI mode only for ${policyAllow.join(", ") || "nothing"}; this model's route is ${route}.` };
+  }
+  return null;
+}
+
+/**
+ * Ask for consent. Interactive: the screens above. Non-interactive: the flag
+ * or the policy, else a refusal that names the flag.
+ *
+ * @param {object} p
+ * @param {"local"|"ollama-cloud"} p.route
+ * @param {string} p.model
+ * @param {string} p.project - display name of the repo
+ * @param {number} p.maxUnits
+ * @param {boolean} [p.repro]
+ * @param {string|null} [p.flag] - --ai-consent value
+ * @param {string[]|null} [p.policyAllow] - policy ai.allow
+ * @param {boolean} p.interactive
+ * @param {(q: string) => Promise<string>} p.ask
+ * @param {(t: string) => void} p.write
+ * @param {object} [p.modelInfo] - { digest, size } for details
+ * @returns {Promise<{ ok: boolean, via?: string, reason?: string, declined?: boolean }>}
+ */
+export async function askConsent(p) {
+  if (!ROUTES.includes(p.route)) return { ok: false, reason: `Unknown AI route ${p.route}` };
+  if (p.policyAllow && p.policyAllow.length === 0) {
+    return { ok: false, reason: "penthera.policy.json turns AI mode off for this repository (\"ai\": { \"allow\": [] })." };
+  }
+  if (!p.interactive) {
+    const decided = consentWithoutAsking(p);
+    if (decided) return decided;
+    return {
+      ok: false,
+      reason: `AI mode needs consent, and this run cannot ask. Add --ai-consent ${p.route}, or "ai": { "allow": ["${p.route}"] } in penthera.policy.json.`,
+    };
+  }
+  if (p.flag != null && !ROUTES.includes(p.flag)) return consentWithoutAsking(p);
+
+  const screen = consentScreen(p);
+  for (;;) {
+    p.write(screen.text);
+    const answer = String(await p.ask(screen.question)).trim().toLowerCase();
+    if (answer === "details" || answer === "d") {
+      p.write(consentDetails({ route: p.route, model: p.model, digest: p.modelInfo?.digest, size: p.modelInfo?.size, logPath: consentLogPath(p.env) }));
+      continue;
+    }
+    if (answer !== "y" && answer !== "yes") return { ok: false, declined: true, reason: "AI mode not confirmed." };
+    break;
+  }
+  if (p.route === "ollama-cloud") {
+    const cs = cloudScreen(p);
+    p.write(cs.text);
+    const typed = String(await p.ask(cs.question)).trim().toLowerCase();
+    if (typed !== CLOUD_HOST) return { ok: false, declined: true, reason: `${CLOUD_HOST} was not typed; nothing was sent.` };
+  }
+  return { ok: true, via: "terminal" };
+}
+
+/**
+ * Append one consent to the local log (mode 0600). Never read back to skip a question.
+ * @param {{ project: string, route: string, model: string, digest?: string, via: string, interface?: string }} entry
+ */
+export function logConsent(entry, env = process.env) {
+  const path = consentLogPath(env);
+  mkdirSync(resolve(path, ".."), { recursive: true });
+  const fresh = !existsSync(path);
+  const line = { at: new Date().toISOString(), textVersion: CONSENT_TEXT_VERSION, ...entry };
+  appendFileSync(path, JSON.stringify(line) + "\n", { mode: 0o600 });
+  if (fresh) {
+    try { chmodSync(path, 0o600); } catch { /* best effort on file systems without modes */ }
+  }
+  return line;
+}
+
+/** The consent log, newest last. Lines that do not parse are skipped. */
+export function readConsentLog(env = process.env) {
+  const path = consentLogPath(env);
+  if (!existsSync(path)) return [];
+  return readFileSync(path, "utf-8").split("\n").filter(Boolean).flatMap((l) => {
+    try { return [JSON.parse(l)]; } catch { return []; }
+  });
+}
+
+/** Validate the policy file's "ai" block: { allow: ["local"] | ["local", "ollama-cloud"] | [] }. */
+export function normalizeAiPolicy(raw, label) {
+  if (raw == null) return null;
+  if (typeof raw !== "object" || Array.isArray(raw)) throw new Error(`${label}: expected an object like { "allow": ["local"] }`);
+  const extra = Object.keys(raw).filter((k) => k !== "allow");
+  if (extra.length) throw new Error(`${label}: unknown field(s) ${extra.join(", ")} (expected allow)`);
+  const allow = typeof raw.allow === "string" ? [raw.allow] : raw.allow;
+  if (!Array.isArray(allow) || allow.some((r) => !ROUTES.includes(r))) {
+    throw new Error(`${label}: "allow" must list routes from ${ROUTES.join(", ")} (an empty list turns AI mode off)`);
+  }
+  return { allow: [...new Set(allow)] };
+}