@clear-capabilities/agentic-security-scanner 0.149.4 → 0.150.2

package/bin/agentic-security.js

@@ -127,6 +127,7 @@ Commands:
   mcp                          Start the MCP stdio server (scan_diff, query_taint, explain_finding, apply_fix)
   validator-cache stats|gc     Inspect / prune .agentic-security/llm-cache/ (use --older-than <days> --dry-run)
   verify [--finding <id>]      Re-run the verifier loop on last-scan findings (use --live --target <url> to execute PoCs)
+  ask "<question>" [target]    Bounded local-model Q&A with read-only tool access (requires AGENTIC_SECURITY_LLM_PRESET=ollama)
   reset [--yes] [--keep ...]   Right-to-delete: wipe accumulated learned state under .agentic-security/ (preserves operator-authored config)
                                --expired    only remove artifacts past their retention-class TTL
                                Every run writes a deletion-report.json proving what was planned/deleted/preserved/failed.
@@ -1452,6 +1453,77 @@ async function cmdProfile(args) {
 // /triage list | assign | transition | trend
 async function cmdTriage(args) {
   const target = path.resolve(args._[args._.length - 1] && !args._[args._.length - 1].startsWith('--') ? args._[args._.length - 1] : '.');
+  // ollama-offline-prd.md §34 — `triage --explain <finding-id>` is read-only
+  // narrative generation, not triage's own assign/transition/lock state
+  // machine, so it doesn't need the pro-tier gate below (and is checked
+  // before it for exactly that reason).
+  if (args.flags.explain) {
+    const id = String(args.flags.explain);
+    const lastScanPath = statePath(target, 'last-scan.json');
+    if (!fs.existsSync(lastScanPath)) { console.error('No prior scan found. Run `agentic-security scan` first.'); return 4; }
+    const last = JSON.parse(await fsp.readFile(lastScanPath, 'utf8'));
+    const f = (last.findings || []).find(x => x.id === id) || (last.secrets || []).find(x => x.id === id);
+    if (!f) { console.error(`Finding ${id} not found in last scan.`); return 4; }
+    console.log('Deterministic evidence');
+    console.log('-----------------------');
+    console.log(`  ${f.vuln || f.title || 'finding'}  [${f.severity || 'unknown'}]  ${f.cwe || ''}`.trim());
+    console.log(`  ${f.file}:${f.line || '?'}`);
+    if (f.description) console.log(`  ${f.description}`);
+    const { proposeOllamaExplanation, EXPLAIN_ERROR } = await import('../src/llm-validator/explain-proposal.js');
+    const proposal = await proposeOllamaExplanation({
+      finding: { file: f.file, line: f.line, vuln: f.vuln, cwe: f.cwe, severity: f.severity, confidence: f.confidence ?? f.llm_confidence },
+      contextSnippet: f.snippet || '',
+      scanRoot: target,
+    });
+    console.log('');
+    if (proposal.ok) {
+      console.log(`Model-generated explanation (${proposal.model}) — not deterministic evidence`);
+      console.log('-----------------------------------------------------------------------');
+      console.log(`  ${proposal.modelExplanation}`);
+      if (proposal.confidenceNote) console.log(`  (${proposal.confidenceNote})`);
+    } else if (proposal.code === EXPLAIN_ERROR.NOT_CONFIGURED) {
+      console.log('(No AI-assisted explanation — configure AGENTIC_SECURITY_LLM_PRESET=ollama for one.)');
+    } else {
+      console.log(`(AI-assisted explanation unavailable: ${proposal.code} — ${proposal.reason})`);
+    }
+    return 0;
+  }
+  // ollama-offline-prd.md §18.1 — `triage --poc <finding-id>` is a headless,
+  // Ollama-backed PoC SKETCH (narrative only — never executed, never written
+  // to disk) for when Claude Code's own security-poc-generator agent isn't
+  // available. Same read-only exemption from the pro-tier gate as --explain.
+  if (args.flags.poc) {
+    const id = String(args.flags.poc);
+    const lastScanPath = statePath(target, 'last-scan.json');
+    if (!fs.existsSync(lastScanPath)) { console.error('No prior scan found. Run `agentic-security scan` first.'); return 4; }
+    const last = JSON.parse(await fsp.readFile(lastScanPath, 'utf8'));
+    const f = (last.findings || []).find(x => x.id === id) || (last.secrets || []).find(x => x.id === id);
+    if (!f) { console.error(`Finding ${id} not found in last scan.`); return 4; }
+    console.log('Deterministic evidence');
+    console.log('-----------------------');
+    console.log(`  ${f.vuln || f.title || 'finding'}  [${f.severity || 'unknown'}]  ${f.cwe || ''}`.trim());
+    console.log(`  ${f.file}:${f.line || '?'}`);
+    if (f.description) console.log(`  ${f.description}`);
+    const { proposeOllamaPoc, POC_PROPOSAL_ERROR } = await import('../src/llm-validator/poc-proposal.js');
+    const proposal = await proposeOllamaPoc({
+      finding: { file: f.file, line: f.line, vuln: f.vuln, cwe: f.cwe, severity: f.severity },
+      contextSnippet: f.snippet || '',
+      scanRoot: target,
+    });
+    console.log('');
+    if (proposal.ok) {
+      console.log(`Model-generated PoC sketch (${proposal.model}) — unverified, not executed`);
+      console.log('-----------------------------------------------------------------------');
+      console.log(`  ${proposal.pocNarrative}`);
+      if (proposal.exampleInput) console.log(`  Example input: ${proposal.exampleInput}`);
+      if (proposal.expectedResult) console.log(`  Expected result: ${proposal.expectedResult}`);
+    } else if (proposal.code === POC_PROPOSAL_ERROR.NOT_CONFIGURED) {
+      console.log('(No AI-assisted PoC sketch — configure AGENTIC_SECURITY_LLM_PRESET=ollama for one.)');
+    } else {
+      console.log(`(AI-assisted PoC sketch unavailable: ${proposal.code} — ${proposal.reason})`);
+    }
+    return 0;
+  }
   const profile = loadProfile(target);
   if (profile.profile !== 'pro') {
     console.error('Triage is a pro-mode feature. Run `agentic-security profile set pro` to enable.');
@@ -1848,6 +1920,283 @@ async function cmdValidatorCache(args) {
   return 4;
 }
 
+// `agentic-security models list|status|doctor|inspect <model>`
+//
+// agentic-security-ollama-offline-prd.md §11.2/§31 — the local-AI UX. Every
+// subcommand is read-only and never itself triggers a model pull or a chat
+// call (models test/benchmark, which DO run inference, are P1/P2 scope not
+// implemented here — see the PRD coverage note in docs/guides/ollama.md).
+async function cmdModels(args) {
+  const sub = args._[1] || 'status';
+  const {
+    ollamaEndpointConfig, listOllamaModels, DEFAULT_OLLAMA_HOST,
+  } = await import('../src/llm-validator/ollama-provider.js');
+  const {
+    classifyModelFamily, capabilitiesFromFamilyHint, detectSystemMemory,
+    detectMemoryTier, recommendAdmission, MEMORY_PROFILES,
+  } = await import('../src/llm-validator/model-capabilities.js');
+  const { getModelCapabilities } = await import('../src/llm-validator/model-probe.js');
+  const { resolveProvider } = await import('../src/llm-validator/providers.js');
+  const wantsProbe = !!args.flags.probe;
+  const wantsForceProbe = !!args.flags.force;
+
+  const envOverride = {};
+  if (args.flags.host) envOverride.AGENTIC_SECURITY_OLLAMA_HOST = String(args.flags.host);
+  if (args.flags['allow-remote-ollama']) envOverride.AGENTIC_SECURITY_OLLAMA_ALLOW_REMOTE = '1';
+  const env = { ...process.env, ...envOverride };
+
+  if (sub === 'list' || sub === 'status' || sub === 'doctor') {
+    const cfg = ollamaEndpointConfig(env);
+    if (!cfg.ok) {
+      console.log(`✗ ${cfg.reason}`);
+      console.log('\nThe deterministic scanner will still run.\nNo cloud provider will be used automatically.');
+      return args.flags.json ? (writeStdout(JSON.stringify({ ok: false, code: cfg.code, reason: cfg.reason }, null, 2) + '\n'), 0) : 1;
+    }
+    const modelsResult = await listOllamaModels({ host: cfg.config.host });
+    if (!modelsResult.ok) {
+      console.log(`✗ Ollama server is not reachable at ${cfg.config.host}`);
+      console.log(`  (${modelsResult.code}: ${modelsResult.reason})`);
+      console.log('\nThe deterministic scanner will still run.\nNo cloud provider will be used automatically.');
+      if (args.flags.json) writeStdout(JSON.stringify({ ok: false, code: modelsResult.code, reason: modelsResult.reason }, null, 2) + '\n');
+      return 1;
+    }
+
+    if (sub === 'list') {
+      if (args.flags.json) {
+        writeStdout(JSON.stringify({ ok: true, host: cfg.config.host, models: modelsResult.models }, null, 2) + '\n');
+        return 0;
+      }
+      console.log(`Installed models (${cfg.config.host}):`);
+      if (modelsResult.models.length === 0) console.log('  (none installed)');
+      for (const m of modelsResult.models) {
+        const family = classifyModelFamily(m.name);
+        const caps = capabilitiesFromFamilyHint(m.name);
+        const sizeGb = Number.isFinite(m.sizeBytes) ? (m.sizeBytes / (1024 ** 3)).toFixed(1) + 'GB' : '?';
+        console.log(`  ${m.name.padEnd(24)} family=${family.padEnd(14)} size=${sizeGb.padEnd(8)} tools=${caps.tools === true ? 'yes' : caps.tools === false ? 'no' : 'not-detected'}`);
+      }
+      return 0;
+    }
+
+    // status / doctor
+    const mem = detectSystemMemory();
+    const tier = detectMemoryTier(mem.totalBytes);
+    const resolved = resolveProvider({ role: 'validate', env });
+    const model = resolved.ok ? resolved.config.model : null;
+    const totalGb = (mem.totalBytes / (1024 ** 3)).toFixed(1);
+    const freeGb = (mem.freeBytes / (1024 ** 3)).toFixed(1);
+
+    const lines = [];
+    lines.push(sub === 'doctor' ? 'agentic-security local AI doctor' : 'agentic-security models status');
+    lines.push('');
+    lines.push('✓ Ollama server reachable');
+    lines.push(cfg.config.offline ? '✓ Endpoint is loopback-only' : `↗ Endpoint is REMOTE (${cfg.config.host}) — offline guarantee does not apply`);
+    lines.push(`✓ ${modelsResult.models.length} model(s) installed`);
+    lines.push('');
+    lines.push(`System RAM: ${totalGb} GB (free: ${freeGb} GB)`);
+    lines.push(`Memory tier: ${tier}`);
+    if (model) {
+      const installed = modelsResult.models.some((m) => m.name === model);
+      lines.push(`Default model: ${model} ${installed ? '' : '(NOT currently installed)'}`);
+      const profileKey = tier === '8gb' ? '8gb' : (classifyModelFamily(model) === 'gemma4' ? '16gb-gemma' : '16gb-qwen');
+      const admission = recommendAdmission({ profile: profileKey, freeBytes: mem.freeBytes, requestedModel: model });
+      if (admission.admitted) {
+        lines.push(`  ✓ memory admission passed — context ${admission.contextTokens} tokens` +
+          (admission.fellBackToSmallerModel ? ` (fell back to ${admission.model})` : admission.reducedContext ? ' (context reduced)' : ''));
+      } else {
+        lines.push(`  ✗ memory admission FAILED — ${admission.reason}`);
+      }
+      // Adversarial-review fix (2026-09): a memory estimate that has already
+      // been proven wrong by a real OOM on this machine no longer gets
+      // presented with the same unqualified confidence.
+      if (admission.priorOOMWarning) lines.push(`  ⚠ ${admission.priorOOMWarning}`);
+      const capsResult = await getModelCapabilities({ host: cfg.config.host, model, probe: wantsProbe, force: wantsForceProbe });
+      const caps = capsResult.capabilities;
+      const capSourceLabel = caps.source?.runtimeProbe ? (capsResult.cached ? 'runtime-probed, cached' : 'runtime-probed')
+        : caps.source?.metadata ? 'Ollama metadata' : 'family hint — not runtime-probed';
+      lines.push(`  chat=${caps.chat ? 'yes' : 'no'} structuredJson=${caps.structuredJson} tools=${caps.tools} (${capSourceLabel})`);
+      if (wantsProbe) lines.push(capsResult.cached ? '  ✓ capability probe cached (pass --force to re-probe)' : '  ✓ capability probe ran (now cached)');
+      else lines.push('  ↗ run with --probe to runtime-verify structured output / tool calling (consumes inference time)');
+    } else {
+      lines.push('Default model: (none resolved)');
+    }
+    lines.push('');
+    lines.push('Cloud fallback: disabled');
+    lines.push('Deterministic scanner: enabled');
+
+    if (args.flags.json) {
+      writeStdout(JSON.stringify({
+        ok: true, host: cfg.config.host, offline: cfg.config.offline, egress: cfg.config.egress,
+        installedModels: modelsResult.models.map((m) => m.name), systemRamGb: Number(totalGb), freeRamGb: Number(freeGb),
+        memoryTier: tier, defaultModel: model, cloudFallback: false,
+      }, null, 2) + '\n');
+    } else {
+      console.log(lines.join('\n'));
+    }
+    return 0;
+  }
+
+  if (sub === 'inspect') {
+    const name = args._[2];
+    if (!name) { console.error('Usage: agentic-security models inspect <model>'); return 4; }
+    const cfg = ollamaEndpointConfig(env);
+    if (!cfg.ok) { console.log(`✗ ${cfg.reason}`); return 1; }
+    const modelsResult = await listOllamaModels({ host: cfg.config.host });
+    if (!modelsResult.ok) { console.log(`✗ Ollama server is not reachable at ${cfg.config.host} (${modelsResult.code})`); return 1; }
+    const info = modelsResult.models.find((m) => m.name === name);
+    const family = classifyModelFamily(name);
+    const capsResult = await getModelCapabilities({ host: cfg.config.host, model: name, probe: wantsProbe, force: wantsForceProbe });
+    const caps = capsResult.capabilities;
+    const out = { name, installed: !!info, family, capabilities: caps, cached: capsResult.cached, metadata: info || null };
+    if (args.flags.json) { writeStdout(JSON.stringify(out, null, 2) + '\n'); return 0; }
+    const capSourceLabel = caps.source?.runtimeProbe ? (capsResult.cached ? 'runtime-probed, cached' : 'runtime-probed')
+      : caps.source?.metadata ? 'Ollama metadata' : 'hint only';
+    console.log(`${name}`);
+    console.log(`  installed: ${out.installed ? 'yes' : 'no'}`);
+    console.log(`  family (hint): ${family}`);
+    console.log(`  capabilities (${capSourceLabel}): chat=${caps.chat} structuredJson=${caps.structuredJson} tools=${caps.tools} thinking=${caps.thinking}`);
+    if (!wantsProbe) console.log('  (run with --probe to runtime-verify structured output / tool calling)');
+    if (info) {
+      console.log(`  size: ${info.sizeBytes ? (info.sizeBytes / (1024 ** 3)).toFixed(1) + 'GB' : '?'}`);
+      console.log(`  parameters: ${info.parameterSize || '?'}  quantization: ${info.quantization || '?'}`);
+    }
+    return 0;
+  }
+
+  if (sub === 'test') {
+    // ollama-offline-prd.md §11.2 — `models test <model>` always runs the
+    // real Layer C runtime probes (structured output + tool calling), unlike
+    // doctor/inspect where --probe is opt-in: the whole point of `test` is
+    // to spend the inference time and get a definitive answer, cached
+    // afterward the same as any other probe.
+    const name = args._[2];
+    if (!name) { console.error('Usage: agentic-security models test <model>'); return 4; }
+    const cfg = ollamaEndpointConfig(env);
+    if (!cfg.ok) { console.log(`✗ ${cfg.reason}`); return 1; }
+    const modelsResult = await listOllamaModels({ host: cfg.config.host });
+    if (!modelsResult.ok) { console.log(`✗ Ollama server is not reachable at ${cfg.config.host} (${modelsResult.code})`); return 1; }
+    if (!modelsResult.models.some((m) => m.name === name)) {
+      console.log(`✗ Model '${name}' is not installed. Run \`ollama pull ${name}\` first.`);
+      return 1;
+    }
+    // ollama-offline-prd.md premortem fix (2026-09): the capability cache has
+    // no expiry beyond its version+digest+name key, which doesn't always
+    // change on a same-tag re-pull — `--force` is the documented way to get
+    // a definitively fresh answer right now, mirroring the existing
+    // `validator-cache stats|gc --older-than <days>` convention rather than
+    // leaving `test` unable to ever overrule its own past result.
+    const capsResult = await getModelCapabilities({ host: cfg.config.host, model: name, probe: true, force: !!args.flags.force });
+    const caps = capsResult.capabilities;
+    if (args.flags.json) {
+      writeStdout(JSON.stringify({ ok: true, name, capabilities: caps, cached: capsResult.cached }, null, 2) + '\n');
+      return 0;
+    }
+    console.log(`agentic-security models test ${name}${args.flags.force ? ' --force' : ''}`);
+    console.log('');
+    console.log(`  chat:            ${caps.chat ? '✓ yes' : '✗ no'}`);
+    console.log(`  structured JSON: ${caps.structuredJson === true ? '✓ yes' : caps.structuredJson === false ? '✗ no' : '? unknown (probe inconclusive)'}`);
+    console.log(`  tool calling:    ${caps.tools === true ? '✓ yes' : caps.tools === false ? '✗ no' : '? unknown (probe inconclusive)'}`);
+    if (caps.contextTokens) console.log(`  context window:  ${caps.contextTokens} tokens`);
+    console.log(`  ${capsResult.cached ? '✓ capability probe cached (already ran before — pass --force to re-probe)' : '✓ capability probe ran (now cached)'}`);
+    return 0;
+  }
+
+  if (sub === 'pull') {
+    // ollama-offline-prd.md §11.2/§24: "models pull must be REFUSED when
+    // strict offline mode is active because pulling a model requires network
+    // access." This CLI treats loopback-enforced Ollama as the default,
+    // always-on safety posture (see ollama-provider.js's header) rather than
+    // a separately-toggled "strict mode", so `models pull` refuses
+    // unconditionally and points at the real `ollama pull` instead of
+    // silently shelling out to it — downloading model weights is
+    // deliberately not something this CLI does on a user's behalf.
+    const name = args._[2] || '<model>';
+    console.log(
+      `Model '${name}' is not installed, or you asked to pull it.\n\n` +
+      'agentic-security never downloads model weights on your behalf — that keeps ' +
+      '"offline mode" honest (no surprise egress the moment you run a scan).\n\n' +
+      'Install it yourself, before disconnecting:\n' +
+      `  ollama pull ${name === '<model>' ? '<model>' : name}`,
+    );
+    return 1;
+  }
+
+  console.error('Usage: agentic-security models <list|status|doctor|inspect <model>|test <model>|pull <model>> [--host <url>] [--json] [--probe] [--force]');
+  console.error(`Default Ollama host: ${DEFAULT_OLLAMA_HOST}`);
+  return 4;
+}
+
+// `agentic-security ask "<question>" [target] [--max-iterations N]`
+//
+// ollama-offline-prd.md §18.2 — the one CLI surface for the bounded local
+// tool-calling agent loop (src/llm-validator/agent-loop.js). Deliberately a
+// separate command from `hunt` (structured candidate discovery, its own
+// propose/confirm/refute/judge pipeline) and `triage --explain/--poc`
+// (single-finding narrative, no tool access at all) — this is free-form Q&A
+// over the scanned project with READ-ONLY tool access, for questions that
+// don't map to either of those shapes ("which files touch this env var",
+// "does this project have a rate limiter").
+async function cmdAsk(args) {
+  const goal = args._[1];
+  if (!goal) { console.error('Usage: agentic-security ask "<question>" [target] [--max-iterations N] [--timeout-ms N]'); return 4; }
+  const target = path.resolve(args._[2] && !args._[2].startsWith('--') ? args._[2] : '.');
+  const { runAgentLoop, AGENT_LOOP_ERROR, DEFAULT_MAX_TOOL_ITERATIONS } = await import('../src/llm-validator/agent-loop.js');
+
+  const envOverride = {};
+  if (args.flags.host) envOverride.AGENTIC_SECURITY_OLLAMA_HOST = String(args.flags.host);
+  if (args.flags['allow-remote-ollama']) envOverride.AGENTIC_SECURITY_OLLAMA_ALLOW_REMOTE = '1';
+  // ollama-offline-prd.md premortem fix (2026-09): --timeout-ms sets the
+  // LOOP's own wall-clock budget (AGENTIC_SECURITY_LLM_AGENT_TIMEOUT_MS),
+  // which used to be a fixed 5 minutes no matter how high
+  // AGENTIC_SECURITY_LLM_TIMEOUT_MS (the PER-CALL timeout, still the right
+  // knob for "this one model reply is slow") was raised — raising only the
+  // per-call setting could not extend the loop, since a single slow call
+  // could already exceed the whole fixed budget.
+  if (args.flags['timeout-ms']) envOverride.AGENTIC_SECURITY_LLM_AGENT_TIMEOUT_MS = String(args.flags['timeout-ms']);
+  const env = { ...process.env, ...envOverride };
+  const maxToolIterations = args.flags['max-iterations'] ? parseInt(args.flags['max-iterations'], 10) : DEFAULT_MAX_TOOL_ITERATIONS;
+
+  const r = await runAgentLoop({ goal, scanRoot: target, env, maxToolIterations });
+  // Adversarial-review fix (2026-09): surfaced here, not just in `models
+  // doctor`, so a user who never runs `doctor` still sees it before/after
+  // the exact command that would otherwise repeat a known OOM.
+  if (r.priorOOMWarning) console.log(`⚠ ${r.priorOOMWarning}`);
+
+  if (!r.ok) {
+    if (r.code === AGENT_LOOP_ERROR.NOT_CONFIGURED) {
+      console.log('No local model configured for tool use — set AGENTIC_SECURITY_LLM_PRESET=ollama (see `agentic-security models doctor`).');
+    } else if (r.code === AGENT_LOOP_ERROR.TOOLS_UNSUPPORTED) {
+      console.log(`✗ ${r.reason}`);
+    } else {
+      console.log(`✗ ${r.code}: ${r.reason}`);
+    }
+    return 1;
+  }
+
+  if (args.flags.json) {
+    writeStdout(JSON.stringify(r, null, 2) + '\n');
+    return r.stopReason === 'complete' ? 0 : 1;
+  }
+
+  for (const call of r.toolCalls) {
+    console.log(`  → ${call.name}(${JSON.stringify(call.args)})  ${call.ok ? 'ok' : `failed: ${call.code}`}`);
+  }
+  console.log('');
+  if (r.stopReason === 'complete') {
+    console.log(r.finalText || '(no answer)');
+    return 0;
+  }
+  if (r.stopReason === 'policy-violation') {
+    console.log('✗ Stopped: the model requested a tool it was never offered.');
+    return 1;
+  }
+  if (r.stopReason === 'max-iterations') {
+    console.log(`✗ Stopped after the ${DEFAULT_MAX_TOOL_ITERATIONS}-iteration bound without a final answer. Try narrowing the question.`);
+    return 1;
+  }
+  console.log('✗ Stopped: wall-clock timeout reached without a final answer. Try --timeout-ms <N> for a slow/cold-loading model (raising AGENTIC_SECURITY_LLM_TIMEOUT_MS alone does not extend this budget).');
+  return 1;
+}
+
 // `agentic-security verify [--finding <id>] [--target <url>] [--live]`
 //
 // Re-runs the verifier loop over the most-recent scan. Without --live, it
@@ -3080,11 +3429,44 @@ async function cmdFix(args) {
     }
   }
 
+  let ollamaFixMeta = null;
   if (newContent === null) {
-    console.error('No mechanical fix is available for this finding. Use the security-fixer subagent (default `fix` mode) and apply with `--apply` after it produces a replacement.');
+    // ollama-offline-prd.md §33 — when no stored/deterministic patch exists,
+    // AND an Ollama provider is configured for the fix role, ask it for a
+    // proposal. Whatever comes back goes through the EXACT SAME
+    // applyVerifiedFix() rescan/lint/test gate below as a deterministic
+    // patch — this branch only ever changes where `newContent` came from,
+    // never how it's verified.
+    const { proposeOllamaFix, FIX_PROPOSAL_ERROR } = await import('../src/llm-validator/fix-proposal.js');
+    const proposal = await proposeOllamaFix({
+      finding: { file: f.file, line: f.line, vuln: f.vuln, cwe: f.cwe, severity: f.severity },
+      fileContent: originalContent,
+      scanRoot,
+    });
+    if (proposal.ok) {
+      newContent = proposal.replacement;
+      ollamaFixMeta = { model: proposal.model, rationale: proposal.rationale, expectedSecurityEffect: proposal.expectedSecurityEffect };
+    } else if (proposal.code !== FIX_PROPOSAL_ERROR.NOT_CONFIGURED) {
+      // A configured Ollama fix attempt that failed is worth surfacing
+      // distinctly from "nothing was configured" — the operator asked for
+      // AI-assisted fix and it didn't work, which is different from never
+      // having asked.
+      console.error(`Ollama fix proposal unavailable (${proposal.code}): ${proposal.reason}`);
+    }
+  }
+
+  if (newContent === null) {
+    console.error('No mechanical fix is available for this finding. Use the security-fixer subagent (default `fix` mode), or configure AGENTIC_SECURITY_LLM_PRESET=ollama for an AI-assisted proposal, then apply with `--apply`.');
     return 4;
   }
 
+  if (ollamaFixMeta) {
+    console.log(`AI-assisted proposal (model: ${ollamaFixMeta.model}) — not yet mechanically verified:`);
+    if (ollamaFixMeta.rationale) console.log(`  rationale: ${ollamaFixMeta.rationale}`);
+    if (ollamaFixMeta.expectedSecurityEffect) console.log(`  expected effect: ${ollamaFixMeta.expectedSecurityEffect}`);
+    console.log('');
+  }
+
   if (isPreview) {
     console.log(previewDiff(originalContent, newContent, f.file));
     console.log('\nRun with --apply to write this change. Use `agentic-security undo` to revert.');
@@ -3116,12 +3498,51 @@ async function cmdFix(args) {
   const fixMeta = (approvedBy || approvalReason || patchAuthor)
     ? { approval: { approvedBy: approvedBy || '', reason: approvalReason || '' }, ...(patchAuthor ? { author: patchAuthor } : {}) }
     : null;
-  const result = await applyVerifiedFix({
+  let result = await applyVerifiedFix({
     scanRoot,
     finding: { file: f.file, id: f.id, stableId: f.stableId || null, ruleId: f.cwe || f.title, vuln: f.vuln || f.title },
     files: { [f.file]: newContent },
     fixMeta,
   });
+  // Adversarial-review fix (2026-09): an Ollama-sourced patch that gets
+  // rejected used to just fail outright — at temperature 0, a bare re-run
+  // of `fix` would almost certainly ask the identical question and get the
+  // identical bad patch back, burning the finite retry budget
+  // (applyVerifiedFix's own maxAttempts) with no chance of a better outcome.
+  // Orchestration test coverage: test/cli/fix-retry.test.js (real spawned
+  // CLI + fake Ollama server; statically skipped in this sandbox's
+  // documented child-process-loopback limitation, same as
+  // test/cli/models.test.js — flip to `test` where a spawned child can
+  // reach the parent's loopback server).
+  // ONE bounded retry, feeding the gate's own rejection reason back into the
+  // prompt so the model has an actual reason to propose something different
+  // — never more than one, matching this codebase's existing "exactly one
+  // retry" philosophy for model output elsewhere (callOllamaStructured's
+  // schema retry). A deterministic/stored patch (no ollamaFixMeta) is never
+  // retried — asking the same static template again cannot produce a
+  // different answer.
+  if (!result.ok && ollamaFixMeta && !result.budgetExceeded) {
+    console.log(`AI-assisted proposal was rejected (${result.reason}) — asking for one revised attempt...`);
+    const { proposeOllamaFix } = await import('../src/llm-validator/fix-proposal.js');
+    const retryProposal = await proposeOllamaFix({
+      finding: { file: f.file, line: f.line, vuln: f.vuln, cwe: f.cwe, severity: f.severity },
+      fileContent: originalContent,
+      scanRoot,
+      rejectionFeedback: result.reason,
+    });
+    if (retryProposal.ok) {
+      const retryResult = await applyVerifiedFix({
+        scanRoot,
+        finding: { file: f.file, id: f.id, stableId: f.stableId || null, ruleId: f.cwe || f.title, vuln: f.vuln || f.title },
+        files: { [f.file]: retryProposal.replacement },
+        fixMeta,
+      });
+      result = retryResult;
+      if (retryResult.ok) {
+        console.log(`  revised proposal accepted (rationale: ${retryProposal.rationale || 'n/a'})`);
+      }
+    }
+  }
   if (!result.ok) {
     console.error(`Refusing to apply: ${result.reason}`);
     if (result.budgetExceeded) console.error(`  (${result.attempts}/${result.maxAttempts} attempts already made for this finding)`);
@@ -3180,7 +3601,105 @@ async function cmdUndo(args) {
   return 0;
 }
 
+// ollama-offline-prd.md §11.1's example transcript is an INTERACTIVE numbered
+// menu. This codebase has no interactive-prompt precedent anywhere else —
+// every other command here is flag-driven and scriptable, deliberately (CI
+// use is the primary case). Rather than introduce the first readline-based
+// prompt in the CLI, `setup --llm ollama` follows the PRD's own explicitly-
+// supported NONINTERACTIVE shape as the only shape: discover, pick a sane
+// memory-tier default when `--model` is omitted (recommend-and-proceed, not
+// block-and-ask), confirm the offline guarantee, print exactly what to
+// export. `--offline` is accepted for parity with the PRD's example command
+// line but is confirmatory only — Ollama's loopback enforcement is already
+// always-on by default (ollama-provider.js), not a mode this flag toggles.
+async function cmdSetupLlmOllama(args) {
+  const {
+    ollamaEndpointConfig, listOllamaModels, DEFAULT_OLLAMA_HOST,
+  } = await import('../src/llm-validator/ollama-provider.js');
+  const { detectSystemMemory, detectMemoryTier, recommendAdmission, classifyModelFamily } = await import('../src/llm-validator/model-capabilities.js');
+
+  const envOverride = {};
+  if (args.flags.host) envOverride.AGENTIC_SECURITY_OLLAMA_HOST = String(args.flags.host);
+  const env = { ...process.env, ...envOverride };
+  const cfg = ollamaEndpointConfig(env);
+  console.log('Local LLM provider: Ollama');
+  if (!cfg.ok) {
+    console.log(`✗ ${cfg.reason}`);
+    return 1;
+  }
+  console.log(`Server: ${cfg.config.host}`);
+
+  const modelsResult = await listOllamaModels({ host: cfg.config.host });
+  if (!modelsResult.ok) {
+    console.log(`✗ Ollama server is not reachable at ${cfg.config.host} (${modelsResult.code}: ${modelsResult.reason})`);
+    console.log('\nInstall Ollama and pull a model first — see docs/guides/ollama.md.');
+    console.log('The deterministic scanner will still run. No cloud provider will be used automatically.');
+    return 1;
+  }
+  console.log('Status: reachable');
+  console.log('');
+  if (modelsResult.models.length === 0) {
+    console.log('No models installed. Pull one first, e.g.:');
+    console.log('  ollama pull qwen3.5:4b');
+    return 1;
+  }
+  console.log('Installed models:');
+  for (const m of modelsResult.models) {
+    const sizeGb = Number.isFinite(m.sizeBytes) ? (m.sizeBytes / (1024 ** 3)).toFixed(1) + 'GB' : '?';
+    console.log(`  ${m.name.padEnd(24)} ${sizeGb}`);
+  }
+  console.log('');
+
+  let chosen = args.flags.model ? String(args.flags.model) : null;
+  if (chosen && !modelsResult.models.some((m) => m.name === chosen)) {
+    console.log(`↗ '${chosen}' is not currently installed — pull it first with \`ollama pull ${chosen}\`. Continuing with this choice anyway.`);
+  }
+  if (!chosen) {
+    // Recommend-and-proceed: pick the memory-tier's preferred model if it's
+    // installed, else the first installed model, rather than blocking on an
+    // interactive prompt this CLI has no precedent for.
+    const mem = detectSystemMemory();
+    const tier = detectMemoryTier(mem.totalBytes);
+    const installedNames = new Set(modelsResult.models.map((m) => m.name));
+    const preferredByTier = tier === '8gb' ? 'qwen3.5:4b'
+      : modelsResult.models.some((m) => classifyModelFamily(m.name) === 'gemma4') ? null : 'qwen3.5:9b';
+    chosen = (preferredByTier && installedNames.has(preferredByTier)) ? preferredByTier : modelsResult.models[0].name;
+    console.log(`Choose default model: ${chosen}  (auto-selected for your ${tier === 'unknown' ? 'detected' : tier} memory tier — pass --model to choose a different installed model)`);
+  } else {
+    console.log(`Choose default model: ${chosen}`);
+  }
+  console.log('');
+
+  const mem = detectSystemMemory();
+  const tier = detectMemoryTier(mem.totalBytes);
+  const profileKey = tier === '8gb' ? '8gb' : (classifyModelFamily(chosen) === 'gemma4' ? '16gb-gemma' : '16gb-qwen');
+  const admission = recommendAdmission({ profile: profileKey, freeBytes: mem.freeBytes, requestedModel: chosen });
+
+  console.log('Offline LLM mode:');
+  console.log('  ✓ Only loopback model requests are allowed');
+  console.log('  ✓ No cloud fallback');
+  console.log('  ✓ Missing local model falls back to deterministic-only scanning');
+  if (!admission.admitted) {
+    console.log(`  ↗ Memory admission check: ${admission.reason}`);
+  }
+  if (admission.priorOOMWarning) console.log(`  ⚠ ${admission.priorOOMWarning}`);
+  console.log('');
+  console.log('To use this configuration, export:');
+  console.log('  export AGENTIC_SECURITY_LLM_PRESET=ollama');
+  console.log(`  export AGENTIC_SECURITY_LLM_MODEL=${chosen}`);
+  if (cfg.config.host !== DEFAULT_OLLAMA_HOST) console.log(`  export AGENTIC_SECURITY_OLLAMA_HOST=${cfg.config.host}`);
+  console.log('');
+  console.log('Then verify with: agentic-security models doctor');
+  return 0;
+}
+
 async function cmdSetup(args) {
+  if (args.flags.llm) {
+    const provider = String(args.flags.llm).toLowerCase();
+    if (provider === 'ollama') return cmdSetupLlmOllama(args);
+    console.error(`agentic-security setup --llm: unsupported provider "${provider}" (only "ollama" runs a discovery/config flow here — other providers (anthropic/openai/gemini/local) configure via their AGENTIC_SECURITY_LLM_* env vars directly, no setup step needed).`);
+    return 4;
+  }
   const projectDir = path.resolve(args._[1] || '.');
   const commandsDir = path.join(projectDir, '.claude', 'commands');
   await fsp.mkdir(commandsDir, { recursive: true });
@@ -6353,6 +6872,16 @@ async function main() {
   checkNodeVersionOrExit();
   const args = parseArgs(process.argv.slice(2));
   const cmd = args._[0];
+  // ollama-offline-prd.md §11.3/§10.2 — CLI flags win over every other
+  // configuration layer. A generic bridge here (rather than per-command
+  // flag parsing in cmdHunt/cmdSecure/etc.) means `--llm`/`--model` work
+  // the same way on any command without duplicating the same six lines —
+  // commands that don't consult an LLM provider simply never read the env
+  // vars this sets, so this is a no-op for them.
+  if (args.flags.llm) process.env.AGENTIC_SECURITY_LLM_PRESET = String(args.flags.llm);
+  if (args.flags.model) process.env.AGENTIC_SECURITY_LLM_MODEL = String(args.flags.model);
+  if (args.flags['allow-remote-ollama']) process.env.AGENTIC_SECURITY_OLLAMA_ALLOW_REMOTE = '1';
+  if (args.flags['ollama-host']) process.env.AGENTIC_SECURITY_OLLAMA_HOST = String(args.flags['ollama-host']);
   try {
     switch (cmd) {
       case 'scan':     process.exit(await cmdScan(args));
@@ -6370,6 +6899,8 @@ async function main() {
       case 'secure':   process.exit(await cmdSecure(args));
       case 'packs':    process.exit(await cmdPacks(args));
       case 'validator-cache': process.exit(await cmdValidatorCache(args));
+      case 'models':   process.exit(await cmdModels(args));
+      case 'ask':      process.exit(await cmdAsk(args));
       case 'verify':   process.exit(await cmdVerify(args));
       case 'reset':    process.exit(await cmdReset(args));
       case 'export':   process.exit(await cmdExport(args));