@clear-capabilities/agentic-security-scanner 0.195.21 → 0.195.23

package/src/integrations/index.js

@@ -15,6 +15,8 @@ import * as path from 'node:path';
 import * as yaml from '../util/yaml.js';
 import { statePath } from '../posture/state-dir.js';
 import { portfolioAssuranceEnabled, HEADLINE, BLOCKED_HEADLINE } from '../posture/portfolio/wording.js';
+// One decision for every surface (0.195.22): a digest built from a findings file with no scan health says it cannot confirm, never "safe".
+import { assuranceDecision } from '../posture/assurance/decision.js';
 
 function _configPath(scanRoot) {
   return statePath(scanRoot, 'integrations.yml');
@@ -35,10 +37,10 @@ export function configHas(scanRoot, key) {
 // ─── Slack webhook (vibecoder) ───────────────────────────────────────────────
 export function buildSlackDigest(findings, summary, options = {}) {
   const project = options.project || 'project';
-  const status = (summary.critical || 0) === 0 && (summary.high || 0) === 0
-    ? '✅ safe to deploy' : '❌ not safe to deploy';
+  const d = assuranceDecision({ actionable: (summary.critical || 0) + (summary.high || 0), scanHealth: options.scanHealth || null });
+  const status = `${d.icon} ${d.headline.toLowerCase()}`;
   const statusLine = portfolioAssuranceEnabled({ option: options.portfolioAssurance })
-    ? (status.startsWith('✅') ? `✅ ${HEADLINE}` : `❌ ${BLOCKED_HEADLINE}`) + ' (completed supported checks only)' : status;
+    ? (d.decision === 'deployable' ? `✅ ${HEADLINE} (completed supported checks only)` : d.decision === 'not_deployable' ? `❌ ${BLOCKED_HEADLINE}` : status) : status;
   const top = (findings || []).slice(0, 3);
 
   const lines = [
@@ -63,13 +65,15 @@ export function buildSlackDigest(findings, summary, options = {}) {
 // ─── Discord webhook (vibecoder) ─────────────────────────────────────────────
 export function buildDiscordDigest(findings, summary, options = {}) {
   const project = options.project || 'project';
-  const safe = (summary.critical || 0) === 0 && (summary.high || 0) === 0;
+  const d = assuranceDecision({ actionable: (summary.critical || 0) + (summary.high || 0), scanHealth: options.scanHealth || null });
+  const safe = d.decision === 'deployable';
   const top = (findings || []).slice(0, 3);
+  const plain = `${d.icon} ${d.headline.toLowerCase()}`;
   return {
     embeds: [{
       title: `🛡 agentic-security — ${project}`,
-      color: safe ? 0x2ecc71 : 0xe74c3c,
-      description: portfolioAssuranceEnabled({ option: options.portfolioAssurance }) ? (safe ? `✅ ${HEADLINE} (completed supported checks only)` : `❌ ${BLOCKED_HEADLINE}`) : (safe ? '✅ safe to deploy' : '❌ not safe to deploy'),
+      color: safe ? 0x2ecc71 : d.decision === 'not_deployable' ? 0xe74c3c : 0xf1c40f,
+      description: portfolioAssuranceEnabled({ option: options.portfolioAssurance }) ? (safe ? `✅ ${HEADLINE} (completed supported checks only)` : d.decision === 'not_deployable' ? `❌ ${BLOCKED_HEADLINE}` : plain) : plain,
       fields: [
         { name: 'Critical', value: String(summary.critical || 0), inline: true },
         { name: 'High',     value: String(summary.high || 0),     inline: true },
@@ -252,10 +256,11 @@ export async function postPagerDutyEvent(finding) {
 // ─── Microsoft Teams (Adaptive Card via Incoming Webhook) ───────────────────
 // Activated by AGENTIC_SECURITY_TEAMS_WEBHOOK (a webhook URL from a Teams
 // channel's "Incoming Webhook" connector).
-export function buildTeamsCard(findings, summary) {
+export function buildTeamsCard(findings, summary, options = {}) {
   const sev = summary || {};
   const total = (sev.critical || 0) + (sev.high || 0) + (sev.medium || 0) + (sev.low || 0);
   const top = (findings || []).filter(f => /critical|high/.test(f.severity || '')).slice(0, 5);
+  const d = assuranceDecision({ actionable: (sev.critical || 0) + (sev.high || 0), scanHealth: options.scanHealth || null });
   const card = {
     type: 'message',
     attachments: [{
@@ -266,6 +271,7 @@ export function buildTeamsCard(findings, summary) {
         version: '1.4',
         body: [
           { type: 'TextBlock', size: 'Medium', weight: 'Bolder', text: '🛡 agentic-security scan' },
+          { type: 'TextBlock', wrap: true, text: `${d.icon} ${d.headline}` },
           { type: 'FactSet', facts: [
             { title: 'Critical', value: String(sev.critical || 0) },
             { title: 'High',     value: String(sev.high || 0) },
@@ -287,10 +293,10 @@ export function buildTeamsCard(findings, summary) {
   return card;
 }
 
-export async function postTeamsCard(findings, summary) {
+export async function postTeamsCard(findings, summary, options = {}) {
   const url = process.env.AGENTIC_SECURITY_TEAMS_WEBHOOK;
   if (!url) return { ok: false, reason: 'teams-not-configured' };
-  const card = buildTeamsCard(findings, summary);
+  const card = buildTeamsCard(findings, summary, options);
   try {
     const r = await fetch(url, {
       method: 'POST',
@@ -307,9 +313,12 @@ export async function postTeamsCard(findings, summary) {
 export function buildPrComment(findings, summary, options = {}) {
   const sev = summary;
   const top = (findings || []).filter(f => /critical|high/.test(f.severity)).slice(0, 10);
+  const d = assuranceDecision({ actionable: (sev.critical || 0) + (sev.high || 0), scanHealth: options.scanHealth || null });
   const body = [
     '## 🛡 agentic-security',
     '',
+    `**${d.icon} ${d.headline}**`,
+    '',
     '| Critical | High | Medium | Low | Info |',
     '|---:|---:|---:|---:|---:|',
     `| ${sev.critical||0} | ${sev.high||0} | ${sev.medium||0} | ${sev.low||0} | ${sev.info||0} |`,

package/src/llm-validator/index.js

@@ -77,6 +77,7 @@ import { localEndpointConfig } from './local-endpoint.js';
 import { resolveProvider, buildProviderRequest, providerMatrix } from './providers.js';
 import { evaluateEgress } from '../egress/policy.js';
 import { recordEgressCall, payloadMetrics } from '../egress/audit.js';
+import { modelFetch } from '../egress/transport.js';
 import { MODEL_STATUS, summarizeModelStatus } from './model-status.js';
 import { callOllamaChat } from './ollama-provider.js';
 
@@ -408,12 +409,13 @@ async function callEndpoint(endpoint, apiKey, model, prompt, preset = null, shap
     // A model that accepts the connection and never answers must not hold a scan open forever: every call is bounded.
     // The result is an UNAVAILABLE finding (kept, unvalidated), never a silent pass.
     const ms = Number(process.env.AGENTIC_SECURITY_LLM_TIMEOUT_MS) > 0 ? Number(process.env.AGENTIC_SECURITY_LLM_TIMEOUT_MS) : 60_000;
-    const r = await fetch(endpoint, { method: 'POST', headers, body: JSON.stringify(body), signal: AbortSignal.timeout(ms) });
+    const r = await modelFetch(endpoint, { method: 'POST', headers, body: JSON.stringify(body) }, { timeoutMs: ms });
     if (!r.ok) return { ok: false, error: `HTTP ${r.status}` };
     const j = await r.json().catch(() => null);
     return { ok: true, text: String(extractText(j) || ''), usage: extractUsage ? extractUsage(j) : null };
   } catch (e) {
-    return { ok: false, error: e && e.name === 'TimeoutError' ? 'timeout' : e.message };
+    // a redirect, an oversized body or a spent budget is an unavailable validator, named by its transport code, never a pass
+    return { ok: false, error: e && e.code === 'timeout' ? 'timeout' : (e && e.code ? `${e.code}: ${e.message}` : e.message) };
   }
 }
 

package/src/llm-validator/local-endpoint.js

@@ -22,7 +22,10 @@
 // The connect timeout is short for the same reason — a dead port must not hang
 // a scan.
 
-const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '::1', '[::1]', '0.0.0.0']);
+// `localhost` is the one name accepted; `[::1]` is how the URL parser spells the IPv6 loopback (a bare `::1` never reaches this set).
+// `0.0.0.0` is NOT here (GA-06.3): it is the unspecified address, and a connect to it reaches a local interface only by an operating
+// system convention, not by the address's meaning. The promise is "literal loopback", so it is refused like `[::]` and `http://0/`.
+const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]']);
 
 export const DEFAULT_LOCAL_ENDPOINT = 'http://127.0.0.1:11434/v1/chat/completions';
 export const DEFAULT_LOCAL_TIMEOUT_MS = 20000;

package/src/llm-validator/ollama-provider.js

@@ -32,6 +32,7 @@
 // never to this module's error path. See ollama-offline-egress.test.js.
 
 import { isLoopbackUrl } from './local-endpoint.js';
+import { modelFetch } from '../egress/transport.js';
 import { recordOOMEvent } from './oom-feedback.js';
 
 export const DEFAULT_OLLAMA_HOST = 'http://127.0.0.1:11434';
@@ -199,16 +200,17 @@ export function parseOllamaChatResponse(json, model) {
  * "slow to generate" without a lower-level HTTP client.
  */
 async function _fetchOllama(url, init, { connectTimeoutMs, requestTimeoutMs }) {
-  const controller = new AbortController();
-  const totalTimer = setTimeout(() => controller.abort('total-timeout'), requestTimeoutMs);
+  void connectTimeoutMs; // see the note above: the client exposes no connect-only phase to bound separately
   try {
-    const res = await fetch(url, { ...init, signal: controller.signal });
+    // the shared transport: no redirect is followed, the reply is capped while it is read, the deadline is the total timeout
+    const res = await modelFetch(url, init, { timeoutMs: requestTimeoutMs });
     return { ok: true, res };
   } catch (e) {
-    if (controller.signal.aborted) return _err('ollama-timeout', `Ollama request timed out after ${requestTimeoutMs}ms.`);
+    if (e?.code === 'timeout') return _err('ollama-timeout', `Ollama request timed out after ${requestTimeoutMs}ms.`);
+    if (e?.code === 'redirect') return _err('ollama-unreachable', `Ollama answered with a redirect, which is never followed: ${e.message}`);
+    if (e?.code === 'response-too-large') return _err('ollama-malformed-response', e.message);
+    if (e?.code === 'budget-exhausted') return _err('ollama-timeout', e.message);
     return _err('ollama-unreachable', e?.message || String(e));
-  } finally {
-    clearTimeout(totalTimer);
   }
 }
 

package/src/pipeline/scan-health.js

@@ -185,9 +185,22 @@ export function computeScanHealth({ scanMeta = null, annotatorErrors = [], engin
 // twice. Each leg is additive: a leg not present in `freshnessPartial`
 // leaves scanHealth's existing `freshness` object and conditions
 // untouched, exactly like every other optional input this module accepts.
+// A feed whose freshness is UNKNOWN (`stale: null` because the feed was unavailable, never loaded, or cached with no timestamp) AND
+// that the scan consulted for at least one item (`consulted` for the KEV catalog, `cvesChecked` for EPSS) is a condition exactly like
+// a stale one (0.195.22, the GA plan's "missing scan health must remain unknown"): the result reasoned without data it needed, so it
+// cannot be called complete, and strict mode fails closed on it through the status. Two things are deliberately NOT conditions: a feed
+// the scan had nothing to look up in (it changed no result), and `offline-skipped`, which is the operator's own declared configuration
+// (AGENTIC_SECURITY_OFFLINE=1), recorded as `stale: null` with its source and left to the scan-health contract's existing offline rule.
+// A loaded catalog always carries a boolean, so this never fires on one.
+const unknownFeed = (f, what) => {
+  if (!f || f.stale !== null || !f.source || ['cache-fresh', 'live', 'cache/live', 'network', 'offline-skipped'].includes(f.source)) return null;
+  const consulted = Number(f.consulted ?? f.cvesChecked ?? 0);
+  if (!(consulted > 0)) return null;
+  return `${what} freshness is unknown (${f.source}): ${consulted} item(s) were checked without it, and the absence of a finding that needs it is not evidence`;
+};
 const FRESHNESS_CONDITION_BUILDERS = {
-  kev: (f) => (f?.stale === true) ? `KEV catalog is stale (${f.ageDays} day(s) old) — recently-added CVEs may not be reflected` : null,
-  epss: (f) => (f?.stale === true) ? `EPSS exploit-probability data is stale (${f.ageDays} day(s) old)` : null,
+  kev: (f) => (f?.stale === true) ? `KEV catalog is stale (${f.ageDays} day(s) old) — recently-added CVEs may not be reflected` : unknownFeed(f, 'KEV catalog'),
+  epss: (f) => (f?.stale === true) ? `EPSS exploit-probability data is stale (${f.ageDays} day(s) old)` : unknownFeed(f, 'EPSS exploit-probability data'),
   calibration: (f) => (f?.stale === true) ? `calibration data is stale (${f.ageDays} day(s) old${f.generatedAt ? `, last generated ${f.generatedAt}` : ''})` : null,
   customRules: (f) => (f?.stale === true) ? `${f.staleFiles.length} custom rule file(s) exceed their configured review interval` : null,
   advisories: (f) => (Number(f?.unanswered) > 0) ? `${f.unanswered} of ${f.componentsChecked} dependencies were not checked against advisory data (${f.source}) — the absence of a vulnerable dependency finding is not evidence that the dependency is safe` : null,

package/src/posture/CLAUDE.md

@@ -156,6 +156,7 @@ Foundation for the differentiation work (CORE-001, CORE-002, CORE-004). All of i
 - **`contracts.js`**: observation binding (references a lineage observation by id only; absence in a sampled observation cannot establish `blocked`), capability decision (only runner/proxy mediation with a backend and an active-probe digest may claim `enforced`; a hook or in-process check never can), routing label (a decided label must name an adjudication or trusted-execution source), release evidence (`complete` is derived, never trusted), and `validateRecordSet` for duplicate ids, dangling references and conflicting claims.
 - **`migrations.js`**: explicit v1 adapters from legacy shapes (proof tier, boolean verified, egress decision, attestation, lineage observation) and a legacy view back out. Evidence can be lost, never invented: a legacy `true` is `inconclusive`, `proof-failed` is `inconclusive` not `refuted`, and the only route to `confirmed` is an explicit `trustedRunner` assertion bound to a commit. The legacy view's `verified` is `true` only for confirmed and `false` only for refuted, otherwise `null`.
 - **`config.js`**: the unified feature configuration. Reuses the env/`.agentic-security/*.yml` mechanism. Precedence: kill switch (`AGENTIC_SECURITY_NO_ASSURANCE` or `AGENTIC_SECURITY_NO_<FEATURE>`) > explicit override > `AGENTIC_SECURITY_ASSURANCE_<FEATURE>` > `.agentic-security/assurance.yml` > default (everything off). **A project file can never enable a `high-risk-execution` feature** (the file lives in the scanned repo); invalid configuration fails closed; unsupported platforms return a typed `unsupported` with the disclosure. `runFeature` returns typed `blocked`/`unsupported`/`degraded`/`disabled` results and never prompts.
+- **`decision.js`** (0.195.22, the GA plan GA-11.7): `assuranceDecision({ actionable, scanHealth })`, the ONE decision every user-facing surface states (`deployable`, `needs_review`, `not_deployable`, `unknown` when no scan health was recorded). `report/index.js` `toShipVerdict`, the Slack, Discord and Teams digests and the pull-request comment in `integrations/index.js` derive their wording from it; actionable findings outrank a missing health record, and zero findings with no health record are `unknown`, never clean. The default wording of the three older states is the one the docs and brand assets carry; the bounded wording stays the `portfolio-assurance` opt-in.
 - **`bounded-io.js`**: `guardedModelCall` is the only route for new model/network calls. It owns no HTTP client (the transport is injected): feature gate, then `evaluateEgress` BEFORE the payload exists, then `redactPayload`, then the request-size limit, then deadline plus bounded retries, then output cap, with every decision appended to the existing egress audit chain. `readFileBounded`, `capOutput`, `withDeadline`, `retryBounded` enforce the limits `config.js` claims; `maxMemoryMiB` is carried for a runner and disclosed as not enforced here.
 - **`baseline.js`, `baseline-inventory.js`**: baseline capture (`scripts/baseline-capture.mjs`, `npm run baseline:capture`). Read-only; records HEAD, dirty paths, exact source and bundle digests, tool versions, entry points, the seven mappings and an 18-entry capability inventory (implemented / partial / unsupported / unmeasured, every path and exported symbol verified at capture time, a missing one is a reported problem). Unknown facts are `{status:'unknown', reason}` with no value. `evaluateBaseline` invalidates exactly the capabilities whose cited files changed and lists unrelated user changes as retained/introduced. The manifest is machine-specific, so it is generated on demand and not committed. When you change a capability's source or tests, update its inventory entry in the same change.
 

package/src/posture/adversary-agent.js

@@ -26,6 +26,8 @@
 
 import * as crypto from 'node:crypto';
 import { evaluateEgress } from '../egress/policy.js';
+import { modelFetch } from '../egress/transport.js';
+import { resolveProvider } from '../llm-validator/providers.js';
 
 const MAX_CALLS_DEFAULT = 50;
 const MAX_WALL_MS_DEFAULT = 15 * 60 * 1000;
@@ -96,11 +98,21 @@ export function isExceeded(transcript, budget) {
 // and parses the response as a single tool-call request. The endpoint is
 // expected to follow an OpenAI-style chat-completions shape; we extract a
 // JSON object of `{ tool, args }` from the model's reply.
+// GA-06.3: the provider is resolved like the validator's, so the `local` preset's loopback refusal applies here, and a vendor key is
+// sent only with that vendor's own preset (a bare OPENAI_API_KEY is never attached to an arbitrary endpoint). Ollama's protocol is not
+// implemented here, so that preset counts as not configured for this agent.
+export function _agentProvider(env = process.env) {
+  const r = resolveProvider({ role: 'verify', env });
+  if (!r.ok || r.config.provider === 'ollama') return null;
+  return r.config;
+}
+
 export async function defaultLlmInvoke(transcript) {
-  const endpoint = process.env.AGENTIC_SECURITY_LLM_ENDPOINT;
-  if (!endpoint) return null;
-  const model = process.env.AGENTIC_SECURITY_LLM_MODEL || 'gpt-4o-mini';
-  const apiKey = process.env.AGENTIC_SECURITY_LLM_API_KEY || process.env.OPENAI_API_KEY || '';
+  const provider = _agentProvider();
+  if (!provider) return null;
+  const { endpoint } = provider;
+  const model = provider.model || 'gpt-4o-mini';
+  const apiKey = provider.apiKey || '';
   const headers = { 'Content-Type': 'application/json' };
   if (apiKey) headers['Authorization'] = `Bearer ${apiKey}`;
   const tools = [...TOOL_ACL].map(t => ({ tool: t, description: TOOL_HELP[t] || '' }));
@@ -115,7 +127,7 @@ export async function defaultLlmInvoke(transcript) {
   };
   let res;
   try {
-    res = await fetch(endpoint, { method: 'POST', headers, body: JSON.stringify(body) });
+    res = await modelFetch(endpoint, { method: 'POST', headers, body: JSON.stringify(body) });
   } catch (e) {
     return null;
   }
@@ -136,6 +148,9 @@ const TOOL_HELP = {
   'record_outcome': 'Terminate the run with a verdict (outcome: one of OUTCOMES)',
 };
 
+/** Bounds for a tool probe against the target: a reply is kept to 4000 characters anyway, so 64 KiB and 30 s are generous. */
+const PROBE_BOUNDS = Object.freeze({ timeoutMs: 30_000, maxResponseBytes: 64 * 1024 });
+
 // Default executeTool — wraps http.get / http.post against `transcript.target`.
 // Falls back to refusal when the tool is db.read_sandbox_copy (we do not ship
 // a sandboxed DB by default; the caller must supply one).
@@ -144,7 +159,8 @@ export async function defaultExecuteTool(call, transcript) {
   if (call.tool === 'http.get') {
     const url = (transcript?.target || '').replace(/\/$/, '') + (call.args?.path || '/');
     try {
-      const r = await fetch(url, { method: 'GET', headers: call.args?.headers || {} });
+      // the probe goes through the shared transport too: no redirect off the target, a capped reply, a deadline
+      const r = await modelFetch(url, { method: 'GET', headers: call.args?.headers || {} }, PROBE_BOUNDS);
       const body = await r.text();
       return { status: r.status, headers: Object.fromEntries(r.headers), body: body.slice(0, 4000) };
     } catch (e) { return { error: String(e?.message || e) }; }
@@ -152,11 +168,11 @@ export async function defaultExecuteTool(call, transcript) {
   if (call.tool === 'http.post') {
     const url = (transcript?.target || '').replace(/\/$/, '') + (call.args?.path || '/');
     try {
-      const r = await fetch(url, {
+      const r = await modelFetch(url, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json', ...(call.args?.headers || {}) },
         body: typeof call.args?.body === 'string' ? call.args.body : JSON.stringify(call.args?.body || {}),
-      });
+      }, PROBE_BOUNDS);
       const body = await r.text();
       return { status: r.status, headers: Object.fromEntries(r.headers), body: body.slice(0, 4000) };
     } catch (e) { return { error: String(e?.message || e) }; }
@@ -176,8 +192,9 @@ export async function runAgent(finding, opts = {}) {
   // called later in the loop below) never runs at all.
   let egressDecision = null;
   let llmInvoke = opts.llmInvoke || null;
-  if (!llmInvoke && process.env.AGENTIC_SECURITY_LLM_ENDPOINT) {
-    egressDecision = evaluateEgress({ scanRoot: opts.scanRoot, purpose: 'adversary-agent', endpoint: process.env.AGENTIC_SECURITY_LLM_ENDPOINT });
+  const provider = llmInvoke ? null : _agentProvider();
+  if (!llmInvoke && provider) {
+    egressDecision = evaluateEgress({ scanRoot: opts.scanRoot, purpose: 'adversary-agent', endpoint: provider.endpoint });
     if (egressDecision.allowed) llmInvoke = defaultLlmInvoke;
   }
   const executeTool = opts.executeTool || (transcript.target ? (call) => defaultExecuteTool(call, transcript) : null);

package/src/posture/assurance/config.js

@@ -58,6 +58,8 @@ export const FEATURES = Object.freeze({
     platformNote: 'runner-level filesystem, network and process enforcement is only advertised on Linux; macOS can supervise but not enforce',
   },
   'model-routing': { risk: 'model-network', platforms: ['linux', 'darwin', 'win32'], platformNote: null },
+  // a detector-spec proposal drafted by a model for human review (Labs); the only route is guardedModelCall, with the egress policy evaluated before any sample file is read
+  'detector-spec-synthesis': { risk: 'model-network', platforms: ['linux', 'darwin', 'win32'], platformNote: null },
   'portfolio-assurance': { risk: 'passive', platforms: ['linux', 'darwin', 'win32'], platformNote: null },
 });
 

package/src/posture/assurance/decision.js

@@ -0,0 +1,45 @@
+// The one assurance decision every user-facing surface states (the GA plan, GA-11.7): the CLI ship verdict, the Slack, Discord and
+// Teams digests and the pull-request comment all call `assuranceDecision` and print its wording, so a surface can no longer decide
+// from severity counts alone. The decision vocabulary is the release verdict's (`release-verdict.js`): `deployable`, `needs_review`,
+// `not_deployable`, plus `unknown` when no scan health was recorded, because a result that cannot say whether the scan completed
+// cannot say anything about deployability.
+//
+// Rules, in order:
+//   - actionable findings (critical or high)                               -> not_deployable (an incomplete or missing scan health is noted)
+//   - no scan health at all (a findings file with no health record)        -> unknown: zero findings with no record of completion prove nothing
+//   - scan health not `complete`, no actionable findings                   -> needs_review (the first condition is the reason)
+//   - complete, no actionable findings                                     -> deployable
+//
+// Wording: the default strings are the ones the CLI, the docs and the brand assets have carried since the ship verdict existed, kept
+// so that existing output stays recognisable; the bounded wording of the `portfolio-assurance` feature (`portfolio/wording.js`) is the
+// opt-in alternative and the surfaces still choose it the way they did. What is new is the `unknown` state and that every surface
+// derives its wording from the same decision.
+// the four decisions: deployable, needs_review, not_deployable, unknown
+
+const WORDING = Object.freeze({
+  deployable: { icon: '✅', headline: 'Safe to deploy' },
+  not_deployable: { icon: '❌', headline: 'Not safe to deploy' },
+  needs_review: { icon: '⚠️', headline: 'Scan incomplete — cannot confirm safe to deploy' },
+  unknown: { icon: '⚠️', headline: 'Cannot confirm safe to deploy — no scan health recorded' },
+});
+
+/**
+ * @param {object} p
+ * @param {number|Array} p.actionable   the critical and high findings (a count or the array)
+ * @param {object|null} p.scanHealth    scan.scanHealth, or null when none was recorded
+ * @returns {{decision:string, icon:string, headline:string, reason:string, actionable:number, scanStatus:string|null, condition:string|null}}
+ */
+export function assuranceDecision({ actionable = 0, scanHealth = null } = {}) {
+  const n = Array.isArray(actionable) ? actionable.length : Number(actionable) || 0;
+  const health = scanHealth && typeof scanHealth === 'object' && typeof scanHealth.status === 'string' ? scanHealth : null;
+  const conditions = health && Array.isArray(health.conditions) ? health.conditions : [];
+  const condition = conditions[0] || (health && health.status !== 'complete' ? 'analysis did not complete cleanly' : null);
+  let decision;
+  let reason;
+  if (n > 0) { decision = 'not_deployable'; reason = `${n} actionable finding(s)${!health ? ' (no scan health recorded)' : health.status !== 'complete' ? `, and the scan is ${health.status}: ${condition}` : ''}`; }
+  else if (!health) { decision = 'unknown'; reason = 'no scan health was recorded with this result, so whether the scan completed is unknown'; }
+  else if (health.status !== 'complete') { decision = 'needs_review'; reason = `no actionable finding, but the scan is ${health.status}: ${condition}${conditions.length > 1 ? ` (+${conditions.length - 1} more)` : ''}`; }
+  else { decision = 'deployable'; reason = 'no critical or high finding and every analyzer finished'; }
+  return { decision, ...WORDING[decision], reason, actionable: n, scanStatus: health ? health.status : null, condition };
+}
+

package/src/posture/assurance/rollout.js

@@ -47,6 +47,8 @@ const FEATURE_SUITE = Object.freeze({
   'capability-enforcement': 'capabilities',
   'model-routing': 'routing',
   'portfolio-assurance': 'portfolio',
+  // the synthesis module is a CORE-004 consumer (the shared bounded call); its pins run in the foundation step
+  'detector-spec-synthesis': 'foundation',
 });
 
 // What each feature must show before opt-in. Feature specific, and quoted from the PRD's own targets
@@ -58,6 +60,7 @@ const OPT_IN_SPECIFIC = Object.freeze({
   'invariant-scenarios': [review('contract-approval-path', 'Invariant contracts are approved by an authorized reviewer, never by the generator that proposed them')],
   'capability-enforcement': [measure('backend-probes', 'Every mandatory canary-secret and escape fixture is blocked on the advertised backend with zero canary leakage; macOS stays supervise-only')],
   'model-routing': [measure('promotion-thresholds', 'At least 200 paired adjudicated tasks overall and 30 per promoted stratum, lower 95% quality bound above -0.02, median cost 20% lower or quality 0.05 higher at no higher median cost, p95 latency within 1.2x')],
+  'detector-spec-synthesis': [measure('proposal-validity', 'At least 95% schema-valid proposal completion on the frozen supported samples, safe refusal of malformed and adversarial replies, zero automatic installation, zero requests under deny and zero remote requests under local-only (the GA plan, GA-07)')],
   'portfolio-assurance': [measure('interrupted-run-convergence', 'Interrupted, duplicate-delivery and incremental runs converge to a fresh scoped result with no double-counted progress')],
 });
 

package/src/posture/custom-rules.js

@@ -39,6 +39,7 @@ import * as path from 'node:path';
 import * as yaml from '../util/yaml.js';
 import { globFiles } from '../util/glob.js';
 import { loadTrustedKeys, verifyRulePack } from './rule-pack-signing.js';
+import { isUnsafeRegex } from '../sast/redos-nfa.js';
 
 import { statePath, safeWriteState } from './state-dir.js';
 const LANG_EXTS = {
@@ -156,8 +157,19 @@ export function loadCustomRules(scanRoot) {
 // Catches (a+)+, (a*)*, (.+)+, (\w+)+, (a|b)+, (a+|b)* etc.
 // Not exhaustive but eliminates the vast majority of catastrophic patterns.
 const _REDOS_NESTED_RE = /\([^)]*[+*][^)]*\)[+*?{]/;
+// The textual heuristic above misses an ambiguous alternation under a quantifier (`(a|a)*b`) and the polynomial shapes; since
+// 0.195.23 (GA-07) the NFA-based detector the SAST layer already ships (`sast/redos-nfa.js`) is consulted as well, so a custom or
+// compiled rule is held to the same bar as the code the scanner flags for CWE-1333.
 function _isSafePattern(p) {
-  return !_REDOS_NESTED_RE.test(p);
+  if (_REDOS_NESTED_RE.test(p)) return false;
+  return !isUnsafeRegex(p).unsafe;
+}
+/** Why a pattern is refused, for the loader's message and the rule compiler's validation. Null when it is safe. */
+export function unsafePatternReason(p) {
+  if (typeof p !== 'string') return 'not a string';
+  if (_REDOS_NESTED_RE.test(p)) return 'nested quantifiers';
+  const r = isUnsafeRegex(p);
+  return r.unsafe ? (r.reason || 'superlinear matching') : null;
 }
 
 /** The loader's own rule normalizer, exported so anything that scores or validates a rule uses the SAME one the scanner loads

package/src/posture/fleet/cli.js

@@ -15,7 +15,7 @@ import { rollupFleet, renderFleetSummary } from '../fleet.js';
 import { statePath, ensureStateDir, safeWriteState } from '../state-dir.js';
 import { createSqliteJobStore } from './job-store.js';
 import { planRun, runJobs, loadArtifacts, reclaimDeadWorkers, childScan } from './job-runner.js';
-import { computeOrgHealth, renderOrgHealth } from './org-health.js';
+import { computeOrgHealth, renderOrgHealth, applyArtifactProblems } from './org-health.js';
 import { discoverEdges, splitDeclared } from './discover-edges.js';
 import { buildEnterpriseGraph, finalizeGraph, validateEnterpriseGraph, attackPaths, vulnerableSet, componentBlastRadius, renderBlastRadius, INTERNET } from './enterprise-graph.js';
 
@@ -90,9 +90,7 @@ function runOfJob(store, id) {
 async function finishRun({ args, root, store, runId, manifest, manifestFile, interrupted }) {
   const { artifacts, problems } = loadArtifacts({ store, runId, root });
   const jobs = store.listJobs(runId);
-  const health = computeOrgHealth({ manifest, jobs });
-  for (const p of problems) { const r = health.repositories.find((x) => x.id === p.repoId); if (r) { r.state = 'failed'; r.error = p.problem; } }
-  if (problems.length) { health.counts.complete -= problems.filter((p) => health.repositories.find((x) => x.id === p.repoId)).length; health.counts.failed += problems.length; if (health.assurance !== 'red' && manifest.repositories.some((r) => r.required && problems.some((p) => p.repoId === r.id))) health.assurance = 'red'; health.reasons.push(`${problems.length} result(s) could not be verified: ${problems.map((p) => `${p.repoId} (${p.problem})`).join(', ')}`); }
+  const health = applyArtifactProblems(computeOrgHealth({ manifest, jobs }), manifest, problems);
 
   let previous = null;
   const rollupFile = statePath(root, ROLLUP_FILE);

package/src/posture/fleet/fleet-manifest.js

@@ -14,7 +14,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { load as loadYaml } from '../../util/yaml.js';
 
-export const FLEET_MANIFEST_SCHEMA_KEYS = Object.freeze(['organization', 'repositories', 'workers', 'perRepoTimeout', 'retries', 'resources']);
+export const FLEET_MANIFEST_SCHEMA_KEYS = Object.freeze(['organization', 'repositories', 'workers', 'perRepoTimeout', 'retries', 'resources', 'cacheMaxAge']);
 export const REPO_KEYS = Object.freeze(['id', 'path', 'required', 'kind', 'internetFacing', 'environment', 'dataClasses', 'trustZone', 'calls', 'produces', 'consumes', 'reads', 'writes', 'providers', 'aliases']);
 export const RESOURCE_KEYS = Object.freeze(['id', 'kind', 'dataClasses', 'trustZone', 'internetFacing', 'environment', 'aliases']);
 export const REPO_KINDS = Object.freeze(['service', 'library', 'frontend', 'worker', 'gateway']);
@@ -93,12 +93,15 @@ export function validateFleetManifest(doc, { baseDir = '.' } = {}) {
   if (doc.workers != null && !(Number.isInteger(doc.workers) && doc.workers >= 1 && doc.workers <= 32)) errors.push('workers must be an integer in 1..32');
   if (doc.retries != null && !(Number.isInteger(doc.retries) && doc.retries >= 0 && doc.retries <= 5)) errors.push('retries must be an integer in 0..5');
   if (doc.perRepoTimeout != null && parseDuration(doc.perRepoTimeout, null) == null) errors.push(`perRepoTimeout is not a valid duration: ${doc.perRepoTimeout}`);
+  if (doc.cacheMaxAge != null && parseDuration(doc.cacheMaxAge, null) == null) errors.push(`cacheMaxAge is not a valid duration: ${doc.cacheMaxAge}`);
   if (errors.length) return { ok: false, errors };
   return {
     ok: true, errors: [],
     manifest: {
       organization: doc.organization, repositories: repos, resources,
       workers: doc.workers ?? 4, retries: doc.retries ?? 1, perRepoTimeoutMs: parseDuration(doc.perRepoTimeout, 20 * 60000),
+      // GA-09: a cached result older than this is stale and is not reused (the feeds it was enriched with have moved on); 7 days by default
+      cacheMaxAgeMs: parseDuration(doc.cacheMaxAge, 7 * 24 * 3600000),
     },
   };
 }

package/src/posture/fleet/job-runner.js

@@ -69,6 +69,21 @@ export function planRun({ manifest, manifestHash, store, runId = null, config =
  * Run (or continue) a planned run until no job is queued or leased by a live worker. Returns when the work is done, the signal
  * aborts, or `maxWaitMs` passes with only other workers' leases outstanding.
  */
+export const DEFAULT_CACHE_MAX_AGE_MS = 7 * 24 * 3600000;
+
+/**
+ * Is a cache hit fresh enough to reuse (GA-09)? A record with no readable `cachedAt` (written before 0.195.23) is never fresh, and a
+ * record older than `maxAgeMs` (the manifest's `cacheMaxAge`, 7 days by default) is stale. Returns `{ fresh, cacheAgeMs }`.
+ */
+export function cacheFreshness(hit, maxAgeMs, nowMs) {
+  if (!hit) return { fresh: false, cacheAgeMs: null };
+  const t = typeof hit.cachedAt === 'string' ? Date.parse(hit.cachedAt) : NaN;
+  if (Number.isNaN(t)) return { fresh: false, cacheAgeMs: null };
+  const cacheAgeMs = Math.max(0, nowMs - t);
+  const max = Number.isFinite(maxAgeMs) && maxAgeMs > 0 ? maxAgeMs : DEFAULT_CACHE_MAX_AGE_MS;
+  return { fresh: cacheAgeMs <= max, cacheAgeMs };
+}
+
 export async function runJobs({ manifest, store, runId, root, scan = childScan, scanOptions = {}, workers = manifest.workers, leaseMs = DEFAULTS.leaseMs, heartbeatMs = DEFAULTS.heartbeatMs, retryDelayMs = DEFAULTS.retryDelayMs, pollMs = DEFAULTS.pollMs, maxWaitMs = null, signal, now = () => Date.now(), onEvent = () => {}, cacheDir = null, artifactDir = null, useCache = true }) {
   const repoById = new Map(manifest.repositories.map((r) => [r.id, r]));
   const cacheD = cacheDir ?? statePath(root, 'fleet', 'cache');
@@ -78,7 +93,11 @@ export async function runJobs({ manifest, store, runId, root, scan = childScan,
   const writeArtifact = (job, payload) => {
     const text = JSON.stringify({ schema: 'agentic-security/fleet-scan-artifact', version: 1, runId, repoId: job.repoId, epoch: job.epoch, commit: job.commit, ...payload });
     const file = path.join(artD, `${job.repoId}.${job.epoch}.json`);
-    fs.writeFileSync(file, text, { mode: 0o600 });
+    // written whole or not at all (GA-09): a worker killed mid-write leaves no half artifact for the hash check to find, only a
+    // stray temp file, and the job stays leased until the lease expires and another worker redoes it
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, text, { mode: 0o600 });
+    fs.renameSync(tmp, file);
     return { file, sha256: sha(text) };
   };
 
@@ -100,11 +119,16 @@ export async function runJobs({ manifest, store, runId, root, scan = childScan,
       idleSince = null;
       const repo = repoById.get(job.repoId);
       onEvent({ type: 'start', repo: job.repoId, attempt: job.attempts });
-      const cached = useCache ? readCache(cacheD, job.cacheKey) : null;
+      const hit = useCache ? readCache(cacheD, job.cacheKey) : null;
+      // GA-09: a hit is reused only while it is fresh. A result with no recorded time (written before 0.195.23) or older than the
+      // manifest's `cacheMaxAge` is stale: it is scanned again, never folded into a green organization as if it were current.
+      const { fresh, cacheAgeMs } = cacheFreshness(hit, manifest.cacheMaxAgeMs, now());
+      const cached = fresh ? hit : null;
+      if (hit && !cached) onEvent({ type: 'cache-stale', repo: job.repoId, cacheAgeMs });
       if (cached) {
-        const a = writeArtifact(job, { entry: cached.entry, findings: cached.findings, findingsTruncated: !!cached.findingsTruncated, lineage: cached.lineage ?? null, cached: true });
+        const a = writeArtifact(job, { entry: cached.entry, findings: cached.findings, findingsTruncated: !!cached.findingsTruncated, lineage: cached.lineage ?? null, cached: true, cachedAt: cached.cachedAt, cacheAgeMs });
         const status = cached.entry?.scanHealth && cached.entry.scanHealth.status !== 'complete' ? 'partial' : 'succeeded';
-        if (store.complete(job.jobId, job.epoch, { status, artifactSha256: a.sha256, summary: { total: cached.entry?.total ?? null, cached: true, artifact: path.basename(a.file) }, now: now() })) onEvent({ type: 'done', repo: job.repoId, cached: true, status });
+        if (store.complete(job.jobId, job.epoch, { status, artifactSha256: a.sha256, summary: { total: cached.entry?.total ?? null, cached: true, cacheAgeMs, artifact: path.basename(a.file) }, now: now() })) onEvent({ type: 'done', repo: job.repoId, cached: true, status });
         continue;
       }
       const ac = new AbortController();

package/src/posture/fleet/org-health.js

@@ -45,6 +45,29 @@ export function computeOrgHealth({ manifest, jobs }) {
   return { counts, assurance, reasons, repositories: repos };
 }
 
+/**
+ * Fold artifact problems (a result whose file is missing or does not match its recorded hash) into the health (GA-09). The repository
+ * becomes `failed`; a required one turns the organization red, an optional one makes it degraded (it used to stay green); the counts
+ * move from whatever state the repository had, not always from `complete`. Returns the same object, changed in place.
+ */
+export function applyArtifactProblems(health, manifest, problems) {
+  if (!Array.isArray(problems) || !problems.length) return health;
+  const stateKey = { complete: 'complete', partial: 'partial', failed: 'failed', 'timed-out': 'timedOut', cancelled: 'cancelled', 'not-run': 'notRun' };
+  let requiredHit = false; let optionalHit = false;
+  for (const p of problems) {
+    const r = health.repositories.find((x) => x.id === p.repoId);
+    if (!r) continue;
+    if (r.state !== 'failed') { health.counts[stateKey[r.state]]--; health.counts.failed++; }
+    r.state = 'failed'; r.error = p.problem;
+    const required = manifest.repositories.some((m) => m.id === p.repoId && m.required);
+    if (required) requiredHit = true; else optionalHit = true;
+  }
+  if (requiredHit) health.assurance = 'red';
+  else if (optionalHit && health.assurance === 'green') health.assurance = 'degraded';
+  health.reasons.push(`${problems.length} result(s) could not be verified: ${problems.map((p) => `${p.repoId} (${p.problem})`).join(', ')}`);
+  return health;
+}
+
 const n = (x) => x.toLocaleString('en-US');
 export function renderOrgHealth(h) {
   const c = h.counts;

package/src/posture/fleet/scan-cache.js

@@ -102,7 +102,7 @@ export function writeCache(dir, key, payload) {
   if (!key || !/^[0-9a-f]{64}$/.test(key)) return false;
   try {
     fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
-    const body = { schema: 'agentic-security/fleet-scan-cache', version: 1, key, ...payload };
+    const body = { schema: 'agentic-security/fleet-scan-cache', version: 1, key, cachedAt: new Date().toISOString(), ...payload };
     const doc = { ...body, digest: sha(JSON.stringify(body)) };
     const tmp = path.join(dir, `.${key}.${process.pid}.tmp`);
     fs.writeFileSync(tmp, JSON.stringify(doc), { mode: 0o600 });

package/src/posture/flow-narration.js

@@ -14,6 +14,8 @@
 // Fail-closed: any LLM error → template fallback, never a missing field.
 
 import { evaluateEgress } from '../egress/policy.js';
+import { modelFetch } from '../egress/transport.js';
+import { resolveProvider, buildProviderRequest } from '../llm-validator/providers.js';
 
 const TEMPLATES = {
   'sql-injection': (f) =>
@@ -63,14 +65,14 @@ function _renderTemplate(f) {
 // Optional LLM call. Disabled by default; opt-in via env. Falls back to the
 // template on any error.
 async function _renderLlm(f, scanRoot) {
-  const endpoint = process.env.AGENTIC_SECURITY_LLM_ENDPOINT;
-  if (!endpoint) return null;
+  // GA-06.3: the provider is resolved like the validator's, so the `local` preset's loopback refusal applies here too, instead of the
+  // raw endpoint variable being called regardless of the preset. The Ollama protocol is not implemented here: treated as not configured.
+  const provider = resolveProvider({ role: 'explain' });
+  if (!provider.ok || provider.config.provider === 'ollama') return null;
+  const { endpoint } = provider.config;
   // FR-601: evaluated before the prompt below is built.
   const egressDecision = evaluateEgress({ scanRoot, purpose: 'flow-narration', endpoint });
   if (!egressDecision.allowed) return null;
-  const apiKey = process.env.AGENTIC_SECURITY_LLM_API_KEY;
-  const headers = { 'Content-Type': 'application/json' };
-  if (apiKey) headers['Authorization'] = `Bearer ${apiKey}`;
   const prompt = `You are explaining a security finding to a developer in one paragraph.
 Vuln: ${f.vuln}
 CWE: ${f.cwe}
@@ -80,11 +82,11 @@ Snippet: ${(f.snippet || '').slice(0, 200)}
 
 Write ONE paragraph (5-7 sentences) covering: (1) how an attacker reaches this code, (2) what they get if exploited, (3) typical recovery cost. Plain English, no marketing language, no emoji.`;
   try {
-    const r = await fetch(endpoint, { method: 'POST', headers, body: JSON.stringify({ prompt }) });
+    const req = buildProviderRequest(provider.config, prompt, 512);
+    const r = await modelFetch(endpoint, { method: 'POST', headers: req.headers, body: JSON.stringify(req.body) });
     if (!r.ok) return null;
     const j = await r.json().catch(() => null);
-    const text = j && (j.response || j.text || j.content || j.output ||
-                       j.choices?.[0]?.message?.content || j.message?.content);
+    const text = req.extractText(j);
     if (typeof text !== 'string' || text.length < 30) return null;
     // Sanitize: strip control chars, markdown fences, HTML metachars.
     return text.replace(/[\x00-\x1f\x7f]/g, ' ').replace(/[<>&]/g, ' ')

package/src/posture/llm-redteam.js

@@ -14,6 +14,7 @@
 
 import { RED_TEAM_PROMPTS, ATTACK_STRATEGIES, PLUGIN_SEVERITY, categorizePrompts, pluginCoverage } from './llm-redteam-prompts.js';
 import { evaluateEgress } from '../egress/policy.js';
+import { modelFetch } from '../egress/transport.js';
 
 // ─── STATIC mode ─────────────────────────────────────────────────────────
 // Scan the repo for prompt files / system-prompt strings and check whether
@@ -143,7 +144,8 @@ async function sendPrompt(endpoint, apiKey, prompt) {
   if (apiKey) headers['Authorization'] = `Bearer ${apiKey}`;
   let response;
   try {
-    const r = await fetch(endpoint, {
+    // the target under test is the operator's named endpoint; the shared transport still refuses a redirect off it and caps the reply
+    const r = await modelFetch(endpoint, {
       method: 'POST',
       headers,
       body: JSON.stringify({ prompt }),