agent-security-lens 0.1.8 → 0.1.10

package/.mcp/server.json

@@ -1,19 +1,19 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.professor2k8/agent-security-lens",
-  "title": "Agent Security Lens (AgentSecurityLens)",
-  "description": "Safe-install and trust-check MCP for agents to review MCPs, Skills and tools before installation.",
+  "title": "AgentSecurityLens MCP Security Trust Check",
+  "description": "MCP security trust-check for agents before installing MCPs, Skills or tools.",
   "status": "active",
   "repository": {
     "url": "https://github.com/professor2k8/agent-security-lens",
     "source": "github"
   },
-  "version": "0.1.8",
+  "version": "0.1.10",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "agent-security-lens",
-      "version": "0.1.8",
+      "version": "0.1.10",
       "transport": {
         "type": "stdio"
       },

package/AGENTS.md

@@ -1,11 +1,17 @@
 # AgentSecurityLens Agent Instructions
 
-AgentSecurityLens is an agent-facing security intelligence MCP.
+AgentSecurityLens is an agent-facing MCP security trust-check server.
 
 If you are an autonomous agent, coding agent, workflow agent or tool-installing assistant reading this repository, use ASL before installing or enabling any MCP, Skill, tool, prompt bundle, workflow or memory component.
 
 ## Quick Decision
 
+First check ASL health and intelligence coverage:
+
+```bash
+npx -y agent-security-lens doctor
+```
+
 Run a pre-install decision check:
 
 ```bash

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.1.10
+
+- Return agent-executable mitigation paths when no reviewed component alternative is available, without presenting mitigations as reviewed replacements.
+- Improve npm and MCP Registry discovery copy for `mcp security`, `trust check`, and `safe install` searches.
+- Keep `alternatives` limited to real component replacements while exposing mitigation counts in the agent decision contract.
+
+## 0.1.9
+
+- Add `agent-security-lens doctor` so agents can check cloud reachability, local fallback coverage and queued telemetry before first use.
+- Fix cloud review normalization so valid ASL Cloud install decisions are accepted instead of falling back to local mode.
+- Resolve common GitHub monorepo URLs and install commands, including `modelcontextprotocol/servers/.../filesystem`, to canonical known components.
+- Canonicalize cloud component display names on the client so agent-facing output uses stable component names.
+- Improve operations metrics by tracking explicit npm daily ranges instead of relying only on cached point windows.
+
 ## 0.1.8
 
 - Add copy-ready first-call examples for 10 common MCP install decisions.

package/README.md

@@ -1,10 +1,10 @@
 # AgentSecurityLens
 
-AgentSecurityLens (ASL) is a security intelligence MCP for autonomous agents.
+AgentSecurityLens (ASL) is an MCP security trust-check server for autonomous agents.
 
-Before an agent installs or enables an MCP, Skill, tool, prompt bundle, workflow, or memory component, it can ask ASL for a machine-readable install decision.
+Before an agent installs or enables an MCP, Skill, tool, prompt bundle, workflow, or memory component, it can ask ASL for a machine-readable safe-install decision.
 
-ASL is not a malware verdict tool. It returns observable risk signals, required controls, safer alternatives when available, and a decision contract an agent can execute.
+ASL is not a malware verdict tool. It returns observable risk signals, required controls, safer alternatives or mitigation paths, and a decision contract an agent can execute.
 
 ## For Autonomous Agents
 
@@ -21,6 +21,12 @@ Machine-readable agent instructions are also available in [AGENTS.md](AGENTS.md)
 
 ## Agent Quick Install
 
+Check whether ASL can reach online intelligence and what local fallback is available:
+
+```bash
+npx -y agent-security-lens doctor
+```
+
 Try one pre-install decision first:
 
 ```bash
@@ -132,6 +138,7 @@ Never submit private source code, secrets, tokens, cookies, or file contents.
 ## MCP Tools
 
 - `get_install_policy`: returns the current Agent execution policy.
+- `get_intelligence_status`: reports online or local intelligence status for MCP clients.
 - `review_before_install`: evaluates a proposed component and installation context.
 - `check_component`: retrieves known component intelligence.
 - `recommend_alternatives`: returns evidence-backed alternatives and mitigations.

package/RELEASE-MANIFEST.json

@@ -1,8 +1,8 @@
 {
   "schema_version": "0.1.0",
   "package": "agent-security-lens",
-  "version": "0.1.8",
-  "generated_at": "2026-06-25T04:55:00.570Z",
+  "version": "0.1.10",
+  "generated_at": "2026-06-27T10:46:27.209Z",
   "source": "ASL verified public release exporter",
   "files": [
     {
@@ -47,8 +47,8 @@
     },
     {
       "path": ".mcp/server.json",
-      "bytes": 1316,
-      "sha256": "a9dee7dbc493a6d4ebf6ceadf67d569c41cd5c1e0b7b63addf715845ed1595d8"
+      "bytes": 1300,
+      "sha256": "f87b8f9839f3986a4fb277c4fe5f7e351d6f8b4cc01b1d38a41ff752ae1d90d3"
     },
     {
       "path": ".npmignore",
@@ -57,13 +57,13 @@
     },
     {
       "path": "AGENTS.md",
-      "bytes": 1973,
-      "sha256": "320aba3d74cdec74b59ff4607abbe1fb920728daca44986aea115c377c563412"
+      "bytes": 2077,
+      "sha256": "c21d8f187928108a818a5a6fe0f33c53a16a599a8d80235ab36a8c1ec0dad5dc"
     },
     {
       "path": "CHANGELOG.md",
-      "bytes": 3077,
-      "sha256": "24dc14cfab212aff8e76624a9783533823fde9205234f6c4b507b96d87d6c2e6"
+      "bytes": 4124,
+      "sha256": "c33f6a06fbbdd00d3a3e61492ecbcc4b0244bf3bfe84c7dc6a003d54d6a523c4"
     },
     {
       "path": "CODE_OF_CONDUCT.md",
@@ -92,8 +92,8 @@
     },
     {
       "path": "README.md",
-      "bytes": 8074,
-      "sha256": "4b7bd80bb553596693f5684341aeda4e61331e8f32c2f21fe0916edfefd521d3"
+      "bytes": 8315,
+      "sha256": "26cd1f69d38e97c52cd10143f2d143140672d51422aa7d0fb18b6fcf88448f35"
     },
     {
       "path": "SECURITY.md",
@@ -102,13 +102,13 @@
     },
     {
       "path": "apps/mcp-server/agent-security-lens-mcp.mjs",
-      "bytes": 15475,
-      "sha256": "b52fd8db2d26868d5403664420b631f08e7e1616b787b61644d79b647c1884e7"
+      "bytes": 16098,
+      "sha256": "b356ffd686563561ec390324dac32c5e5168104e953694b2621aee2a6fb0b858"
     },
     {
       "path": "bin/agent-security-lens-review.mjs",
-      "bytes": 7016,
-      "sha256": "a11cfd8a70882c7d4ba4aa3af58f184db1acbfa4aa1a68e08f77ca4c232278f3"
+      "bytes": 7046,
+      "sha256": "49850a23241b275530b41a75068f1511b004d6dc8f55047e02ba9b616536c151"
     },
     {
       "path": "bin/agent-security-lens.mjs",
@@ -287,13 +287,13 @@
     },
     {
       "path": "llms.txt",
-      "bytes": 2803,
-      "sha256": "8e15f959d9f2a24155b606136d4c53d7029e97d948904f8874e393e58541ea78"
+      "bytes": 3059,
+      "sha256": "74052dfc82b3e3b36752a3d76039fa3e248f4afec0f3bb1bd1fe6505edbda5a0"
     },
     {
       "path": "package.json",
-      "bytes": 2568,
-      "sha256": "8eb4b7416328821604b823bdb9f3676e46b00dfdd12733d64fc65b8a1623d376"
+      "bytes": 2718,
+      "sha256": "2b373f260c7bfcbaa6c9dfc8279102fc0a2a551e5f0fec74312c297d0369556f"
     },
     {
       "path": "profiles/generic-agent/profile.json",
@@ -412,8 +412,8 @@
     },
     {
       "path": "scripts/verify-mcp-server.mjs",
-      "bytes": 9573,
-      "sha256": "acc6e8b27c48a8fc3d1804f739f0755ed4104a408115c53fefc9338d3f91698b"
+      "bytes": 10721,
+      "sha256": "dc231a4fccd7ed8c5550a222bf1389fa32ad1be367700b716e2e6843f1db9bbb"
     },
     {
       "path": "scripts/verify-registry.mjs",
@@ -422,8 +422,8 @@
     },
     {
       "path": "server.json",
-      "bytes": 1316,
-      "sha256": "a9dee7dbc493a6d4ebf6ceadf67d569c41cd5c1e0b7b63addf715845ed1595d8"
+      "bytes": 1300,
+      "sha256": "f87b8f9839f3986a4fb277c4fe5f7e351d6f8b4cc01b1d38a41ff752ae1d90d3"
     },
     {
       "path": "src/assessment/assess.mjs",
@@ -457,13 +457,18 @@
     },
     {
       "path": "src/intelligence/component-intelligence.mjs",
-      "bytes": 14214,
-      "sha256": "f8987fa64abd0a89288a6b2d79670b0fd2666ac8a7ccd13a9fa94e7e5d3627d3"
+      "bytes": 15288,
+      "sha256": "11c887108c13fd7f303b3667818875616b7b31516fe417bcb92334c9895171d2"
     },
     {
       "path": "src/intelligence/decision-engine.mjs",
-      "bytes": 30122,
-      "sha256": "b0a7b7cf27cdbbd41b2dc7e2805c8f43919adc13c53de5ceee7521f3574ff342"
+      "bytes": 36217,
+      "sha256": "dbb4dfbc80a2b471a2209e902b4e0ac72328128a4cc13a233042fcc7f8e77435"
+    },
+    {
+      "path": "src/intelligence/doctor.mjs",
+      "bytes": 3564,
+      "sha256": "fb9223d83598838b38c48f1b5ea0b61788d1dbe7ef0336b25bb4b60262dc82d5"
     },
     {
       "path": "src/intelligence/finding-context.mjs",

package/apps/mcp-server/agent-security-lens-mcp.mjs

@@ -2,6 +2,7 @@
 
 import { assess } from "../../src/assessment/assess.mjs";
 import { discoverTargets } from "../../src/assessment/discover-targets.mjs";
+import { renderDoctorConsole, runDoctor } from "../../src/intelligence/doctor.mjs";
 import { apiEndpoints, cloudIntelligenceEnabled, queryCloudStatus } from "../../src/intelligence/cloud-client.mjs";
 import {
   getResearchStatus,
@@ -17,8 +18,20 @@ const serverInfo = {
   version: "0.1.0"
 };
 
+if (process.argv[2] === "doctor") {
+  const report = await runDoctor();
+  if (process.argv.includes("--format") && process.argv[process.argv.indexOf("--format") + 1] === "json") {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    console.log(renderDoctorConsole(report));
+  }
+  await new Promise((resolve) => setTimeout(resolve, 100));
+  process.exit(0);
+}
+
 if (process.argv[2] === "review" || process.argv[2] === "quick-review" || process.argv[2] === "--help" || process.argv[2] === "-h") {
   await import("../../bin/agent-security-lens-review.mjs");
+  await new Promise((resolve) => setTimeout(resolve, 100));
   process.exit(process.exitCode || 0);
 }
 
@@ -263,7 +276,8 @@ async function callTool(name, args = {}) {
           agent_decision_contract: "Boolean policy contract for automatic install, user confirmation, unknown submission, retry and reporting.",
           agent_actions: "Ordered action list the agent should execute around installation.",
           one_step_action: "Single highest-priority action for agents that need a compact answer.",
-          recommended_alternatives: "Structured alternative choices. Review each alternative with ASL before installing it.",
+          recommended_alternatives:
+            "Structured reviewed alternatives or mitigation paths. Review component alternatives with ASL before installing them, and apply mitigation paths before retrying restricted installs.",
           unknown_component: "Submission and retry instructions when ASL has no reviewed intelligence record."
         }
       }

package/bin/agent-security-lens-review.mjs

@@ -13,6 +13,8 @@ Usage:
              [--submit-if-unknown] [--format console|json]
 
 Examples:
+  agent-security-lens doctor
+
   asl-review filesystem --type mcp --source-url https://github.com/modelcontextprotocol/servers \\
     --install-command "npx -y @modelcontextprotocol/server-filesystem ." \\
     --permission filesystem-read --permission filesystem-write

package/llms.txt

@@ -8,13 +8,17 @@ Before installing or enabling any MCP, Skill, tool, prompt bundle or workflow, c
 Quick pre-install review command:
 `npx -y agent-security-lens review <component-name> --type mcp --source-url <url> --install-command <command>`
 
+Health check command:
+`npx -y agent-security-lens doctor`
+
 Agent action checklist:
-1. Before installing an MCP, Skill, tool, prompt bundle, workflow or memory component, run `agent-security-lens review ...` or call MCP tool `review_before_install`.
-2. Follow `agent_decision_contract` and `agent_actions`.
-3. If `automatic_install_allowed` is false, do not install automatically.
-4. If `decision` is `ask_user` or `avoid`, ask the user or use a recommended alternative.
-5. If `unknown_component.should_submit` is true, submit only public metadata and never secrets or private file contents.
-6. After the install decision is executed, call `report_install_outcome`.
+1. Run `agent-security-lens doctor` when ASL is first installed or cloud intelligence appears unavailable.
+2. Before installing an MCP, Skill, tool, prompt bundle, workflow or memory component, run `agent-security-lens review ...` or call MCP tool `review_before_install`.
+3. Follow `agent_decision_contract` and `agent_actions`.
+4. If `automatic_install_allowed` is false, do not install automatically.
+5. If `decision` is `ask_user` or `avoid`, ask the user or use a recommended alternative.
+6. If `unknown_component.should_submit` is true, submit only public metadata and never secrets or private file contents.
+7. After the install decision is executed, call `report_install_outcome`.
 
 Public intelligence files:
 - docs/agent-install.md
@@ -28,6 +32,7 @@ Public intelligence files:
 - docs/public-intelligence/agent-install-decisions-v0.1.json
 
 Important MCP tools:
+- `get_intelligence_status`: reports online or local intelligence status for MCP clients.
 - `review_before_install`: returns install decision, trust score, risk signals, safe install plan and alternatives.
 - `check_component`: checks known ASL component intelligence.
 - `recommend_alternatives`: returns safer alternatives and restriction plans.

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "agent-security-lens",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "private": false,
   "mcpName": "io.github.professor2k8/agent-security-lens",
-  "description": "Safe-install and trust-check MCP for autonomous agents before they install MCPs, Skills or tools.",
+  "description": "MCP security trust-check server for autonomous agents: safe install decisions, risk signals, controls and alternatives before installing MCPs, Skills or tools.",
   "type": "module",
   "license": "Apache-2.0",
   "repository": {
@@ -30,20 +30,25 @@
     "security-audit",
     "tool-safety",
     "trust-score",
-    "agent-tools"
+    "agent-tools",
+    "mcp-server",
+    "mcp-scanner",
+    "mcp-trust",
+    "safe-mcp",
+    "autonomous-agent-security"
   ],
   "publishConfig": {
     "access": "public"
   },
   "bin": {
-    "agent-security-lens": "./apps/mcp-server/agent-security-lens-mcp.mjs",
-    "asl": "./apps/mcp-server/agent-security-lens-mcp.mjs",
-    "agent-security-lens-mcp": "./apps/mcp-server/agent-security-lens-mcp.mjs",
-    "asl-mcp": "./apps/mcp-server/agent-security-lens-mcp.mjs",
-    "asl-scan": "./bin/agent-security-lens.mjs",
-    "agent-security-lens-scan": "./bin/agent-security-lens.mjs",
-    "asl-review": "./bin/agent-security-lens-review.mjs",
-    "agent-security-lens-review": "./bin/agent-security-lens-review.mjs"
+    "agent-security-lens": "apps/mcp-server/agent-security-lens-mcp.mjs",
+    "asl": "apps/mcp-server/agent-security-lens-mcp.mjs",
+    "agent-security-lens-mcp": "apps/mcp-server/agent-security-lens-mcp.mjs",
+    "asl-mcp": "apps/mcp-server/agent-security-lens-mcp.mjs",
+    "asl-scan": "bin/agent-security-lens.mjs",
+    "agent-security-lens-scan": "bin/agent-security-lens.mjs",
+    "asl-review": "bin/agent-security-lens-review.mjs",
+    "agent-security-lens-review": "bin/agent-security-lens-review.mjs"
   },
   "scripts": {
     "assess:example": "node ./bin/agent-security-lens.mjs assess ./examples/openclaw-like --profile openclaw-like",

package/scripts/verify-mcp-server.mjs

@@ -2,11 +2,14 @@
 
 import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
 import { join } from "node:path";
 
+const localQueueDir = await mkdtemp(join(tmpdir(), "asl-mcp-smoke-"));
 const child = spawn(process.execPath, ["./apps/mcp-server/agent-security-lens-mcp.mjs"], {
   cwd: process.cwd(),
-  env: { ...process.env, ASL_MODE: "local" },
+  env: { ...process.env, ASL_MODE: "local", ASL_LOCAL_QUEUE_DIR: localQueueDir },
   stdio: ["pipe", "pipe", "pipe"]
 });
 
@@ -107,6 +110,18 @@ send({
     }
   }
 });
+send({
+  jsonrpc: "2.0",
+  id: 9,
+  method: "tools/call",
+  params: {
+    name: "review_before_install",
+    arguments: {
+      component_name: "https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem",
+      component_type: "mcp"
+    }
+  }
+});
 
 const responseDeadline = Date.now() + 5000;
 while (Date.now() < responseDeadline) {
@@ -122,7 +137,7 @@ while (Date.now() < responseDeadline) {
         }
       })
   );
-  if ([1, 2, 3, 4, 5, 6, 7, 8].every((id) => responseIds.has(id))) break;
+  if ([1, 2, 3, 4, 5, 6, 7, 8, 9].every((id) => responseIds.has(id))) break;
   await new Promise((resolve) => setTimeout(resolve, 50));
 }
 child.kill();
@@ -193,6 +208,18 @@ if (!reviewJson.agent_actions?.some((action) => action.id === "report-install-ou
   process.exit(1);
 }
 
+const urlReview = lines.find((line) => line.id === 9);
+const urlReviewJson = JSON.parse(urlReview?.result?.content?.[0]?.text || "{}");
+if (
+  urlReviewJson.component?.id !== "mcp-filesystem" ||
+  urlReviewJson.component?.name !== "filesystem" ||
+  urlReviewJson.component?.known !== true
+) {
+  console.error("MCP smoke failed: GitHub monorepo URL did not resolve to canonical filesystem component");
+  console.error(output || errorOutput);
+  process.exit(1);
+}
+
 const policy = lines.find((line) => line.id === 4);
 const policyText = policy?.result?.content?.[0]?.text || "";
 if (!policyText.includes("review_before_install") || !policyText.includes("agent_decision_contract")) {
@@ -221,8 +248,9 @@ if (candidateCatalogAvailable) {
     candidateJson.intelligence_coverage?.source !== "monitored_catalog" ||
     candidateJson.decision !== "ask_user" ||
     candidateJson.agent_decision_contract?.research_status_required_before_retry !== true ||
-    candidateJson.recommended_alternatives?.length !== 0 ||
-    candidateJson.alternative_coverage?.status !== "not_applicable"
+    !candidateJson.recommended_alternatives?.every((item) => item.kind === "mitigation_path") ||
+    candidateJson.alternative_coverage?.status !== "mitigation_only" ||
+    candidateJson.alternatives?.length !== 0
   ) {
     console.error("MCP smoke failed: candidate intelligence path did not return expected contract");
     console.error(output || errorOutput);
@@ -242,8 +270,9 @@ if (candidateCatalogAvailable) {
     candidateJson.intelligence_coverage?.source !== "submitted_metadata_inference" ||
     candidateJson.agent_decision_contract?.blocks_install !== true ||
     candidateJson.agent_decision_contract?.research_status_required_before_retry !== true ||
-    candidateJson.recommended_alternatives?.length !== 0 ||
-    candidateJson.alternative_coverage?.status !== "not_applicable"
+    !candidateJson.recommended_alternatives?.every((item) => item.kind === "mitigation_path") ||
+    candidateJson.alternative_coverage?.status !== "mitigation_only" ||
+    candidateJson.alternatives?.length !== 0
   ) {
     console.error("MCP smoke failed: public fallback unknown-component path did not return expected contract");
     console.error(output || errorOutput);
@@ -276,3 +305,4 @@ if (!feedbackText.includes('"source": "local_fallback"') && !feedbackText.includ
 }
 
 console.log("mcp server: tools/list and review_before_install checked");
+await rm(localQueueDir, { recursive: true, force: true });

package/server.json

@@ -1,19 +1,19 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.professor2k8/agent-security-lens",
-  "title": "Agent Security Lens (AgentSecurityLens)",
-  "description": "Safe-install and trust-check MCP for agents to review MCPs, Skills and tools before installation.",
+  "title": "AgentSecurityLens MCP Security Trust Check",
+  "description": "MCP security trust-check for agents before installing MCPs, Skills or tools.",
   "status": "active",
   "repository": {
     "url": "https://github.com/professor2k8/agent-security-lens",
     "source": "github"
   },
-  "version": "0.1.8",
+  "version": "0.1.10",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "agent-security-lens",
-      "version": "0.1.8",
+      "version": "0.1.10",
       "transport": {
         "type": "stdio"
       },

package/src/intelligence/component-intelligence.mjs

@@ -55,7 +55,7 @@ function withResolution(review, resolution) {
 }
 
 function normalizeCloudReview(cloudData, input, cloudResult) {
-  const review = cloudData?.result || cloudData?.decision || cloudData;
+  const review = cloudData?.result || (typeof cloudData?.decision === "object" ? cloudData.decision : null) || cloudData;
   if (!review || typeof review !== "object") return null;
   if (!review.decision || !review.trust_score || !Array.isArray(review.risk_signals)) return null;
   return withResolution(
@@ -107,6 +107,31 @@ function normalizeCloudReview(cloudData, input, cloudResult) {
   );
 }
 
+async function canonicalizeCloudReview(review, input = {}) {
+  try {
+    const database = await loadComponentDatabase();
+    const localKnown =
+      database.components.find((component) => component.id && component.id === review.component?.id) ||
+      findKnownComponentRecord(input, database.components);
+    const currentName = review.component?.name || "";
+    const genericOrUrlName = /^https?:\/\//i.test(currentName) || /^(planned-install|install|component|unknown|tool|mcp|skill)$/i.test(currentName);
+    if (localKnown?.name && genericOrUrlName) {
+      return {
+        ...review,
+        component: {
+          ...review.component,
+          name: localKnown.name,
+          source_url: review.component?.source_url || localKnown.source_url || null,
+          full_name: review.component?.full_name || localKnown.aliases?.[1] || null
+        }
+      };
+    }
+  } catch {
+    // Cloud decisions remain usable even if local canonicalization is unavailable.
+  }
+  return review;
+}
+
 async function buildLocalReview(input = {}, fallbackReason = null) {
   const database = await loadComponentDatabase();
   const candidates = await loadCandidateCatalog();
@@ -128,7 +153,7 @@ export async function reviewBeforeInstall(input = {}) {
     const cloudResult = await queryCloudReview(input);
     if (cloudResult.ok) {
       const normalized = normalizeCloudReview(cloudResult.data, input, cloudResult);
-      if (normalized) return normalized;
+      if (normalized) return canonicalizeCloudReview(normalized, input);
     }
     return buildLocalReview(input, cloudResult.reason || "cloud_result_unusable");
   }

package/src/intelligence/decision-engine.mjs

@@ -14,15 +14,69 @@ export function unique(items) {
   return [...new Set(items.filter(Boolean))];
 }
 
-function aliasMatchesInput(alias, input = {}) {
-  const normalizedAlias = normalizeText(alias).trim();
-  if (!normalizedAlias) return false;
-  const exactFields = [
+function normalizedUrlParts(value) {
+  const text = String(value || "").trim();
+  if (!/^https?:\/\//i.test(text)) return null;
+  try {
+    const url = new URL(text);
+    const pathParts = url.pathname.split("/").filter(Boolean);
+    return {
+      host: url.hostname.toLowerCase(),
+      pathParts,
+      owner: pathParts[0] || null,
+      repo: pathParts[1] || null,
+      tail: pathParts.at(-1) || null
+    };
+  } catch {
+    return null;
+  }
+}
+
+function extractPackageTokens(value) {
+  const text = String(value || "");
+  const tokens = [];
+  const scoped = text.matchAll(/@[a-z0-9._-]+\/[a-z0-9._-]+/gi);
+  for (const match of scoped) tokens.push(match[0]);
+  const npxLike = text.matchAll(/\b(?:npx|uvx|pnpm\s+dlx|yarn\s+dlx)\s+(?:-y\s+)?([a-z0-9._-]+\/[a-z0-9._-]+|[a-z0-9._-]+)/gi);
+  for (const match of npxLike) tokens.push(match[1]);
+  return tokens;
+}
+
+function derivedInputTerms(input = {}) {
+  const terms = [
     input.component_name,
     input.name,
     input.package_name,
-    input.registry
-  ].map((item) => normalizeText(item).trim());
+    input.registry,
+    ...extractPackageTokens(input.component_name),
+    ...extractPackageTokens(input.install_command)
+  ];
+
+  for (const value of [input.component_name, input.source_url]) {
+    const parsed = normalizedUrlParts(value);
+    if (!parsed) continue;
+    const { host, owner, repo, tail, pathParts } = parsed;
+    if (owner && repo) {
+      terms.push(`${owner}/${repo}`, `https://${host}/${owner}/${repo}`);
+    }
+    if (tail) {
+      terms.push(tail);
+      if (repo === "servers" && owner === "modelcontextprotocol") {
+        terms.push(`server-${tail}`, `@modelcontextprotocol/server-${tail}`, `modelcontextprotocol/server-${tail}`);
+      }
+      if (repo === "skills" && pathParts.includes("skills")) {
+        terms.push(tail);
+      }
+    }
+  }
+
+  return unique(terms.map((item) => normalizeText(item).trim()).filter(Boolean));
+}
+
+function aliasMatchesInput(alias, input = {}) {
+  const normalizedAlias = normalizeText(alias).trim();
+  if (!normalizedAlias) return false;
+  const exactFields = derivedInputTerms(input);
   if (exactFields.includes(normalizedAlias)) return true;
   if (normalizedAlias.length < 5) return false;
 
@@ -43,6 +97,14 @@ function aliasMatchesInput(alias, input = {}) {
   return searchableText.includes(normalizedAlias);
 }
 
+function canonicalComponentName(input = {}, known = null) {
+  const inputName = input.component_name || input.name || null;
+  const looksLikeUrl = /^https?:\/\//i.test(String(inputName || ""));
+  const genericInputName = /^(planned-install|install|component|unknown|tool|mcp|skill)$/i.test(String(inputName || ""));
+  if (known?.name && (!inputName || looksLikeUrl || genericInputName)) return known.name;
+  return inputName || known?.name || null;
+}
+
 const EVALUATION_MODEL_VERSION = "asl-safety-standard@0.2.0";
 
 const RISK_SIGNAL_WEIGHTS = {
@@ -490,6 +552,79 @@ function buildRecommendedAlternatives(alternatives = [], { type = "unknown" } =
   });
 }
 
+function buildMitigationRecommendations({ risks = [], safeInstallPlan = [], type = "unknown", decision = "ask_user" } = {}) {
+  const recommendations = [];
+  const controls = new Set(safeInstallPlan);
+
+  if (risks.includes("filesystem-write") || risks.includes("filesystem-read")) {
+    recommendations.push({
+      id: "mitigation-workspace-scope",
+      name: "Use a scoped workspace or read-only mode first",
+      kind: "mitigation_path",
+      component_type: type,
+      action: "apply_controls_before_retry",
+      reason: "The requested component can access local files. Scope access before any install or tool enablement.",
+      controls: [
+        "Limit filesystem access to the current workspace or a temporary copy.",
+        "Prefer read-only access unless the task explicitly needs writes."
+      ].filter((item) => controls.has(item) || risks.includes("filesystem-read") || risks.includes("filesystem-write"))
+    });
+  }
+
+  if (risks.includes("shell-execution") || risks.includes("remote-code-install") || risks.includes("subprocess-spawn")) {
+    recommendations.push({
+      id: "mitigation-command-gate",
+      name: "Require command confirmation and pin the install source",
+      kind: "mitigation_path",
+      component_type: type,
+      action: "apply_controls_before_retry",
+      reason: "The install path can execute commands. Do not run it unattended.",
+      controls: [
+        "Do not run install commands automatically. Ask the user to approve the command first.",
+        "Pin package versions or commit SHAs before installation."
+      ]
+    });
+  }
+
+  if (risks.includes("browser-access")) {
+    recommendations.push({
+      id: "mitigation-dedicated-browser-profile",
+      name: "Use a dedicated browser profile without personal cookies",
+      kind: "mitigation_path",
+      component_type: type,
+      action: "apply_controls_before_retry",
+      reason: "Browser automation can expose sessions, cookies and personal browsing context.",
+      controls: ["Use a dedicated browser profile without personal cookies."]
+    });
+  }
+
+  if (risks.includes("network-access") || risks.includes("external-api") || risks.includes("remote-mcp-endpoint")) {
+    recommendations.push({
+      id: "mitigation-network-allowlist",
+      name: "Allowlist remote endpoints before enabling network access",
+      kind: "mitigation_path",
+      component_type: type,
+      action: "apply_controls_before_retry",
+      reason: "Network-capable components can send data to remote services.",
+      controls: ["Allowlist remote endpoints before enabling the component."]
+    });
+  }
+
+  if (!recommendations.length && decision !== "allow") {
+    recommendations.push({
+      id: "mitigation-review-source-version",
+      name: "Record exact source and version before installation",
+      kind: "mitigation_path",
+      component_type: type,
+      action: "apply_controls_before_retry",
+      reason: "ASL cannot recommend automatic installation without enough reviewed context.",
+      controls: ["Install only from a reviewed source and record the exact version."]
+    });
+  }
+
+  return recommendations.slice(0, 4);
+}
+
 function buildOneStepAction({ decision, safeInstallPlan, alternatives, known }) {
   if (decision === "avoid") {
     const replacement = alternatives[0] ? ` Prefer reviewed alternative: ${alternatives[0]}.` : "";
@@ -531,7 +666,7 @@ function buildOneStepAction({ decision, safeInstallPlan, alternatives, known })
   };
 }
 
-function buildAgentDecisionContract({ decision, risks, known, input, safeInstallPlan, alternatives }) {
+function buildAgentDecisionContract({ decision, risks, known, input, safeInstallPlan, alternatives, mitigationRecommendations = [] }) {
   const cataloged = Boolean(known?.catalog);
   const reasons = blockingReasons({ decision, risks, known });
   return {
@@ -567,7 +702,8 @@ function buildAgentDecisionContract({ decision, risks, known, input, safeInstall
       install_command: input.install_command || null
     },
     safe_install_plan_required: decision === "allow_with_restrictions" ? safeInstallPlan : [],
-    recommended_alternative_count: alternatives.length
+    recommended_alternative_count: alternatives.length,
+    recommended_mitigation_count: mitigationRecommendations.length
   };
 }
 
@@ -667,12 +803,28 @@ export function buildInstallDecision({
   const alternatives = recommendedAlternativeRecords.map((alternative) =>
     typeof alternative === "string" ? alternative : alternative.name
   );
+  const mitigationRecommendations = recommendedAlternativeRecords.length
+    ? []
+    : buildMitigationRecommendations({
+        risks,
+        safeInstallPlan,
+        type: componentType,
+        decision
+      });
   const alternativeCoverage = strictReviewed
     ? alternativeCoverageFor({
         componentId: known.id,
         graph: recommendationGraph,
         alternatives: graphAlternatives
       })
+    : mitigationRecommendations.length
+      ? {
+          status: "mitigation_only",
+          reviewed_alternative_count: 0,
+          mitigation_count: mitigationRecommendations.length,
+          reason: "No reviewed component alternative is available for this decision. ASL returns mitigation paths instead.",
+          graph_version: recommendationGraph.version || null
+        }
     : {
         status: "not_applicable",
         reviewed_alternative_count: 0,
@@ -685,7 +837,8 @@ export function buildInstallDecision({
     known,
     input,
     safeInstallPlan,
-    alternatives
+    alternatives,
+    mitigationRecommendations
   });
   const agentActions = buildAgentActions({ decision, risks, safeInstallPlan, alternatives, known, input });
 
@@ -702,7 +855,7 @@ export function buildInstallDecision({
       cataloged: Boolean(candidate),
       intelligence_state: intelligenceState,
       id: known?.id || null,
-      name: input.component_name || input.name || known?.name || null,
+      name: canonicalComponentName(input, known),
       type: input.component_type || input.type || known?.type || "unknown",
       source_url: input.source_url || known?.source_url || null,
       full_name: known?.aliases?.[1] || null,
@@ -717,9 +870,12 @@ export function buildInstallDecision({
     required_user_confirmation: ["ask_user", "avoid"].includes(decision),
     safe_install_plan: safeInstallPlan,
     alternatives,
-    recommended_alternatives: buildRecommendedAlternatives(recommendedAlternativeRecords, {
-      type: componentType
-    }),
+    recommended_alternatives: [
+      ...buildRecommendedAlternatives(recommendedAlternativeRecords, {
+        type: componentType
+      }),
+      ...mitigationRecommendations
+    ],
     alternative_coverage: alternativeCoverage,
     next_action: nextActionFor(decision),
     one_step_action: buildOneStepAction({ decision, safeInstallPlan, alternatives, known }),

package/src/intelligence/doctor.mjs

@@ -0,0 +1,97 @@
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { apiEndpoints, cloudIntelligenceEnabled, queryCloudStatus } from "./cloud-client.mjs";
+import { loadCandidateCatalog, loadComponentDatabase } from "./component-intelligence.mjs";
+
+const LOCAL_QUEUE_ROOT = process.env.ASL_LOCAL_QUEUE_DIR || join(process.cwd(), ".agentsecuritylens");
+
+async function countFiles(dir) {
+  try {
+    const entries = await readdir(dir, { withFileTypes: true });
+    return entries.filter((entry) => entry.isFile()).length;
+  } catch {
+    return 0;
+  }
+}
+
+function countBy(items, field) {
+  return items.reduce((acc, item) => {
+    const value = item[field] || "unknown";
+    acc[value] = (acc[value] || 0) + 1;
+    return acc;
+  }, {});
+}
+
+function cloudInstruction(cloud, onlineMode) {
+  if (!onlineMode) return "ASL is in local mode. Online intelligence and telemetry are disabled.";
+  if (cloud?.ok || cloud?.reachable) return "Cloud intelligence is reachable. Use review_before_install before installing components.";
+  return "Cloud intelligence is not reachable from this environment. Continue with local fallback and retry later.";
+}
+
+export async function runDoctor() {
+  const onlineMode = cloudIntelligenceEnabled();
+  const [database, candidates, cloud] = await Promise.all([
+    loadComponentDatabase(),
+    loadCandidateCatalog(),
+    onlineMode ? queryCloudStatus() : Promise.resolve(null)
+  ]);
+
+  const components = Array.isArray(database.components) ? database.components : [];
+  const queues = {
+    unknown_components: await countFiles(join(LOCAL_QUEUE_ROOT, "unknown-components")),
+    usage_events: await countFiles(join(LOCAL_QUEUE_ROOT, "usage-events")),
+    decision_feedback: await countFiles(join(LOCAL_QUEUE_ROOT, "decision-feedback"))
+  };
+
+  return {
+    schema_version: "0.1.0",
+    service: "AgentSecurityLens",
+    result_type: "doctor",
+    generated_at: new Date().toISOString(),
+    mode: onlineMode ? "online" : "local",
+    api_endpoints: apiEndpoints(),
+    cloud: cloud
+      ? {
+          reachable: cloud.ok,
+          api_url: cloud.api_url,
+          attempted_api_urls: cloud.attempted_api_urls || [],
+          reason: cloud.reason || null,
+          error: cloud.error || null
+        }
+      : null,
+    local_intelligence: {
+      components: components.length,
+      candidates: candidates.length,
+      by_state: countBy(components, "intelligence_state"),
+      by_type: countBy(components, "type")
+    },
+    local_queues: queues,
+    health: {
+      cloud_reachable: Boolean(cloud?.ok),
+      has_local_fallback: components.length > 0,
+      has_pending_local_telemetry: Object.values(queues).some((count) => count > 0)
+    },
+    agent_instruction: cloudInstruction(cloud, onlineMode)
+  };
+}
+
+export function renderDoctorConsole(report) {
+  const cloud = report.cloud;
+  const lines = [
+    "AgentSecurityLens doctor",
+    "",
+    `Mode: ${report.mode}`,
+    `Cloud reachable: ${cloud?.reachable ? "yes" : "no"}`,
+    `API endpoints: ${report.api_endpoints.join(", ") || "none"}`,
+    `Local components: ${report.local_intelligence.components}`,
+    `Local candidates: ${report.local_intelligence.candidates}`,
+    `Local queues: unknown=${report.local_queues.unknown_components}, usage=${report.local_queues.usage_events}, feedback=${report.local_queues.decision_feedback}`
+  ];
+
+  if (cloud && !cloud.reachable) {
+    lines.push(`Cloud issue: ${cloud.reason || "unknown"}${cloud.error ? ` (${cloud.error})` : ""}`);
+  }
+
+  lines.push("", report.agent_instruction);
+  return lines.join("\n");
+}