sentinelayer-cli 0.38.0 → 0.39.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sentinelayer-cli",
-  "version": "0.38.0",
+  "version": "0.39.1",
   "description": "Scaffold Sentinelayer spec/prompt/guide artifacts with secure browser auth and token bootstrap.",
   "type": "module",
   "scripts": {

package/src/agents/code-quality/index.js

@@ -9,4 +9,5 @@ export {
   runCouplingAnalysis,
   runCycleDetect,
   runDepGraph,
+  runLayeringCheck,
 } from "./tools/index.js";

package/src/agents/code-quality/tools/index.js

@@ -4,6 +4,7 @@ import { runComplexityMeasure } from "./complexity-measure.js";
 import { runCouplingAnalysis } from "./coupling-analysis.js";
 import { runCycleDetect } from "./cycle-detect.js";
 import { runDepGraph } from "./dep-graph.js";
+import { runLayeringCheck } from "./layering-check.js";
 
 export const CODE_QUALITY_TOOLS = Object.freeze({
   "dep-graph": {
@@ -60,6 +61,20 @@ export const CODE_QUALITY_TOOLS = Object.freeze({
     },
     handler: runComplexityMeasure,
   },
+  "layering-check": {
+    id: "layering-check",
+    description:
+      "Flag lower architectural layers importing higher-level app/UI layers. Uses the dep-graph under the hood and ignores external or unknown-layer imports.",
+    schema: {
+      type: "object",
+      properties: {
+        rootPath: { type: "string" },
+        files: { type: "array", items: { type: "string" } },
+        layers: { type: "array" },
+      },
+    },
+    handler: runLayeringCheck,
+  },
 });
 
 export const CODE_QUALITY_TOOL_IDS = Object.freeze(Object.keys(CODE_QUALITY_TOOLS));
@@ -86,4 +101,5 @@ export {
   runCouplingAnalysis,
   runCycleDetect,
   runDepGraph,
+  runLayeringCheck,
 };

package/src/agents/code-quality/tools/layering-check.js

@@ -0,0 +1,195 @@
+// layering-check — flag lower architectural layers importing higher layers (#A14).
+
+import { createFinding, toPosix } from "./base.js";
+import { buildDependencyGraph } from "./dep-graph.js";
+
+const RESOLUTION_EXTENSIONS = Object.freeze([
+  ".js",
+  ".jsx",
+  ".ts",
+  ".tsx",
+  ".mjs",
+  ".cjs",
+]);
+
+export const DEFAULT_LAYER_RULES = Object.freeze([
+  Object.freeze({
+    name: "shared",
+    rank: 0,
+    prefixes: Object.freeze(["src/shared/", "src/lib/", "shared/", "lib/"]),
+  }),
+  Object.freeze({
+    name: "domain",
+    rank: 1,
+    prefixes: Object.freeze(["src/domain/", "src/core/", "domain/", "core/"]),
+  }),
+  Object.freeze({
+    name: "data",
+    rank: 2,
+    prefixes: Object.freeze([
+      "src/data/",
+      "src/db/",
+      "src/models/",
+      "data/",
+      "db/",
+      "models/",
+    ]),
+  }),
+  Object.freeze({
+    name: "services",
+    rank: 3,
+    prefixes: Object.freeze(["src/services/", "src/server/", "services/", "server/"]),
+  }),
+  Object.freeze({
+    name: "app",
+    rank: 4,
+    prefixes: Object.freeze([
+      "src/app/",
+      "src/api/",
+      "src/controllers/",
+      "src/handlers/",
+      "src/pages/",
+      "src/routes/",
+      "app/",
+      "api/",
+      "controllers/",
+      "handlers/",
+      "pages/",
+      "routes/",
+    ]),
+  }),
+  Object.freeze({
+    name: "ui",
+    rank: 5,
+    prefixes: Object.freeze(["src/components/", "src/ui/", "components/", "ui/"]),
+  }),
+]);
+
+function normalizePathKey(value) {
+  return toPosix(value).replace(/^\.\//, "").replace(/\/{2,}/g, "/");
+}
+
+function normalizePrefix(value) {
+  const normalized = normalizePathKey(value);
+  if (!normalized) {
+    return "";
+  }
+  return normalized.endsWith("/") ? normalized : `${normalized}/`;
+}
+
+function normalizeLayers(layers) {
+  const source = Array.isArray(layers) && layers.length > 0 ? layers : DEFAULT_LAYER_RULES;
+  return source
+    .map((layer, index) => ({
+      name: String(layer?.name || `layer-${index}`).trim(),
+      rank: Number.isFinite(Number(layer?.rank)) ? Number(layer.rank) : index,
+      prefixes: Array.isArray(layer?.prefixes)
+        ? layer.prefixes.map(normalizePrefix).filter(Boolean)
+        : [],
+    }))
+    .filter((layer) => layer.name && layer.prefixes.length > 0);
+}
+
+export function classifyLayer(filePath, layers = DEFAULT_LAYER_RULES) {
+  const normalized = normalizePathKey(filePath);
+  if (!normalized) {
+    return null;
+  }
+  let best = null;
+  for (const layer of normalizeLayers(layers)) {
+    for (const prefix of layer.prefixes) {
+      if (normalized.startsWith(prefix) && (!best || prefix.length > best.prefix.length)) {
+        best = { ...layer, prefix };
+      }
+    }
+  }
+  return best;
+}
+
+function isExternalEdge(edge) {
+  const normalized = normalizePathKey(edge);
+  return (
+    !normalized ||
+    normalized.startsWith("npm:") ||
+    normalized.startsWith("/") ||
+    /^[a-z][a-z0-9+.-]*:/i.test(normalized)
+  );
+}
+export function resolveLocalEdge(edge, graphKeys = []) {
+  const normalized = normalizePathKey(edge);
+  if (!normalized || isExternalEdge(normalized)) {
+    return null;
+  }
+  const keys = graphKeys instanceof Set ? graphKeys : new Set(graphKeys);
+  if (keys.size === 0 || keys.has(normalized)) {
+    return normalized;
+  }
+
+  const candidates = [];
+  const hasExtension = /\.[^/.]+$/.test(normalized);
+  if (!hasExtension) {
+    for (const ext of RESOLUTION_EXTENSIONS) {
+      candidates.push(`${normalized}${ext}`);
+    }
+    for (const ext of RESOLUTION_EXTENSIONS) {
+      candidates.push(`${normalized}/index${ext}`);
+    }
+  }
+
+  for (const candidate of candidates) {
+    if (keys.has(candidate)) {
+      return candidate;
+    }
+  }
+  return normalized;
+}
+
+export function findLayerViolations({ graph, layers = DEFAULT_LAYER_RULES } = {}) {
+  const graphKeys = new Set(Object.keys(graph || {}));
+  const violations = [];
+  for (const [source, edges] of Object.entries(graph || {}).sort(([a], [b]) =>
+    a.localeCompare(b)
+  )) {
+    const sourceLayer = classifyLayer(source, layers);
+    if (!sourceLayer || !Array.isArray(edges)) {
+      continue;
+    }
+    for (const edge of edges.slice().sort()) {
+      const target = resolveLocalEdge(edge, graphKeys);
+      if (!target) {
+        continue;
+      }
+      const targetLayer = classifyLayer(target, layers);
+      if (!targetLayer) {
+        continue;
+      }
+      if (targetLayer.rank > sourceLayer.rank) {
+        violations.push({ source, target, sourceLayer, targetLayer });
+      }
+    }
+  }
+  return violations;
+}
+
+export async function runLayeringCheck({
+  rootPath,
+  files = null,
+  layers = DEFAULT_LAYER_RULES,
+} = {}) {
+  const graph = await buildDependencyGraph({ rootPath, files });
+  return findLayerViolations({ graph, layers }).map(
+    ({ source, target, sourceLayer, targetLayer }) =>
+      createFinding({
+        tool: "layering-check",
+        kind: "code-quality.layer-violation",
+        severity: "P2",
+        file: source,
+        evidence: `${sourceLayer.name} imports higher ${targetLayer.name}: ${source} -> ${target}`,
+        rootCause:
+          "A lower-level module depends on a higher-level layer, which inverts the intended architecture boundary.",
+        recommendedFix:
+          "Move the shared contract into a lower layer or invert the dependency through an interface owned by the lower layer.",
+        confidence: 0.78,
+      })
+  );
+}

package/src/agents/mode.js

@@ -16,7 +16,7 @@
 
 // Persona tool id lists are inlined here instead of imported from each
 // persona module. Rationale: this module has to be importable before all
-// 12 persona PRs (#A13-A24) have merged to main. Once they do, a future
+// persona PRs (#A13-A24) have merged to main. Once they do, a future
 // refactor can swap these for real imports — the tool-id strings are
 // stable anyway.
 
@@ -40,11 +40,12 @@ const CODEGEN_EXTRA_TOOLS = Object.freeze([
 const DOMAIN_TOOL_IDS_BY_PERSONA = Object.freeze({
   "ai-governance": Object.freeze(["eval-regression", "hitl-audit", "prompt-drift", "provenance-check"]),
   "backend": Object.freeze(["circuit-breaker-check", "idempotency-audit", "retry-audit", "timeout-audit"]),
-  "code-quality": Object.freeze(["complexity-measure", "coupling-analysis", "cycle-detect", "dep-graph"]),
+  "code-quality": Object.freeze(["complexity-measure", "coupling-analysis", "cycle-detect", "dep-graph", "layering-check"]),
   "data-layer": Object.freeze(["index-audit", "migration-scan", "query-explain", "tenancy-scan"]),
   "documentation": Object.freeze(["api-diff", "dead-link-check", "docstring-coverage", "readme-freshness"]),
   "infrastructure": Object.freeze(["checkov-run", "drift-detect", "iam-least-priv-check", "tflint-run"]),
   "observability": Object.freeze(["alert-audit", "dashboard-gap", "log-schema-check", "span-coverage"]),
+  "performance": Object.freeze(["blocking-io-audit", "bundle-budget-check", "cache-policy-audit", "n-plus-one-detect"]),
   "release": Object.freeze(["changelog-diff", "feature-flag-audit", "rollback-verify", "semver-check"]),
   "reliability": Object.freeze(["backpressure-check", "chaos-probe", "graceful-degradation-check", "health-check-audit"]),
   "security": Object.freeze(["authz-audit", "crypto-review", "sast-scan", "secrets-scan"]),

package/src/agents/performance/index.js

@@ -0,0 +1,12 @@
+// Arjun (performance persona) - barrel export (#A16).
+
+export {
+  PERFORMANCE_TOOLS,
+  PERFORMANCE_TOOL_IDS,
+  dispatchPerformanceTool,
+  runAllPerformanceTools,
+  runBlockingIoAudit,
+  runBundleBudgetCheck,
+  runCachePolicyAudit,
+  runNPlusOneDetect,
+} from "./tools/index.js";

package/src/agents/performance/tools/base.js

@@ -0,0 +1,208 @@
+// Shared helpers for Arjun's (performance) domain tools (#A16).
+
+import fsp from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+
+import ignore from "ignore";
+
+const DEFAULT_IGNORED_DIRS = new Set([
+  ".git",
+  "node_modules",
+  ".venv",
+  ".next",
+  "dist",
+  "build",
+  "coverage",
+  ".sentinelayer",
+  ".sentinel",
+  ".turbo",
+  ".idea",
+  ".vscode",
+  "__pycache__",
+  ".cache",
+]);
+const MAX_FILE_SIZE_BYTES = 1024 * 1024;
+const SEVERITIES = Object.freeze(["P0", "P1", "P2", "P3"]);
+
+export function toPosix(value) {
+  return String(value || "").replace(/\\/g, "/");
+}
+
+export function normalizeSeverity(value) {
+  const normalized = String(value || "").trim().toUpperCase();
+  if (SEVERITIES.includes(normalized)) {
+    return normalized;
+  }
+  return "P2";
+}
+
+export function createFinding({
+  severity,
+  kind,
+  file,
+  line = 0,
+  evidence = "",
+  rootCause = "",
+  recommendedFix = "",
+  confidence = null,
+  tool = "",
+  persona = "performance",
+} = {}) {
+  return {
+    persona,
+    tool: String(tool || "").trim(),
+    kind: String(kind || "").trim() || "performance",
+    severity: normalizeSeverity(severity),
+    file: toPosix(file || ""),
+    line: Number.isFinite(Number(line)) ? Math.max(0, Math.floor(Number(line))) : 0,
+    evidence: String(evidence || "").trim().slice(0, 400),
+    rootCause: String(rootCause || "").trim(),
+    recommendedFix: String(recommendedFix || "").trim(),
+    confidence:
+      confidence === null || confidence === undefined
+        ? null
+        : Math.max(0, Math.min(1, Number(confidence) || 0)),
+  };
+}
+
+async function readIgnorePatterns(filePath) {
+  try {
+    const raw = await fsp.readFile(filePath, "utf-8");
+    return String(raw || "")
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter((line) => line && !line.startsWith("#"));
+  } catch (err) {
+    if (err && typeof err === "object" && err.code === "ENOENT") {
+      return [];
+    }
+    throw err;
+  }
+}
+
+async function createIgnoreMatcher(rootPath) {
+  const matcher = ignore();
+  const gitignore = await readIgnorePatterns(path.join(rootPath, ".gitignore"));
+  const sentinel = await readIgnorePatterns(
+    path.join(rootPath, ".sentinelayerignore")
+  );
+  matcher.add([...gitignore, ...sentinel]);
+  return (relativePath, isDirectory) => {
+    const normalized = toPosix(relativePath);
+    if (!normalized) {
+      return false;
+    }
+    const candidate = isDirectory ? `${normalized}/` : normalized;
+    return matcher.ignores(candidate);
+  };
+}
+
+export async function* walkRepoFiles({
+  rootPath = process.cwd(),
+  extensions = new Set(),
+  maxFileSize = MAX_FILE_SIZE_BYTES,
+} = {}) {
+  const resolvedRoot = path.resolve(rootPath);
+  const ignoreMatcher = await createIgnoreMatcher(resolvedRoot);
+  const wantedExtensions =
+    extensions instanceof Set
+      ? extensions
+      : new Set(Array.isArray(extensions) ? extensions : []);
+  const stack = [resolvedRoot];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    let entries = [];
+    try {
+      entries = await fsp.readdir(current, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const fullPath = path.join(current, entry.name);
+      const relativePath = toPosix(path.relative(resolvedRoot, fullPath));
+      if (entry.isDirectory()) {
+        if (!relativePath || DEFAULT_IGNORED_DIRS.has(entry.name)) {
+          continue;
+        }
+        if (ignoreMatcher(relativePath, true)) {
+          continue;
+        }
+        stack.push(fullPath);
+        continue;
+      }
+      if (!entry.isFile()) {
+        continue;
+      }
+      if (ignoreMatcher(relativePath, false)) {
+        continue;
+      }
+      const ext = path.extname(entry.name).toLowerCase();
+      if (wantedExtensions.size > 0 && !wantedExtensions.has(ext) && !wantedExtensions.has("")) {
+        continue;
+      }
+      let stat = null;
+      try {
+        stat = await fsp.stat(fullPath);
+      } catch {
+        stat = null;
+      }
+      if (!stat || stat.size > maxFileSize) {
+        continue;
+      }
+      yield { fullPath, relativePath, sizeBytes: stat.size };
+    }
+  }
+}
+
+export function findLineMatches(content, pattern) {
+  const text = String(content || "");
+  if (!pattern) {
+    return [];
+  }
+  const global = new RegExp(
+    pattern.source,
+    pattern.flags.includes("g") ? pattern.flags : `${pattern.flags}g`
+  );
+  const matches = [];
+  let match;
+  while ((match = global.exec(text)) !== null) {
+    const lineIndex = text.slice(0, match.index).split(/\r?\n/).length;
+    matches.push({ index: match.index, line: lineIndex, match: match[0] });
+  }
+  return matches;
+}
+
+export function getLineContent(content, line) {
+  const lines = String(content || "").split(/\r?\n/);
+  return (lines[Math.max(0, (Number(line) || 1) - 1)] || "").trim();
+}
+
+export async function* iterateFiles(resolvedRoot, files, extensions) {
+  if (Array.isArray(files) && files.length > 0) {
+    for (const file of files) {
+      const trimmed = String(file || "").trim();
+      if (!trimmed) {
+        continue;
+      }
+      const fullPath = path.isAbsolute(trimmed)
+        ? trimmed
+        : path.join(resolvedRoot, trimmed);
+      const relativePath = path
+        .relative(resolvedRoot, fullPath)
+        .replace(/\\/g, "/");
+      let stat = null;
+      try {
+        stat = await fsp.stat(fullPath);
+      } catch {
+        stat = null;
+      }
+      yield { fullPath, relativePath, sizeBytes: stat?.size || 0 };
+    }
+    return;
+  }
+
+  yield* walkRepoFiles({ rootPath: resolvedRoot, extensions });
+}
+
+export { DEFAULT_IGNORED_DIRS, MAX_FILE_SIZE_BYTES, SEVERITIES };

package/src/agents/performance/tools/blocking-io-audit.js

@@ -0,0 +1,85 @@
+// blocking-io-audit - flag synchronous I/O on request/runtime paths (#A16).
+
+import fsp from "node:fs/promises";
+import path from "node:path";
+
+import { createFinding, findLineMatches, getLineContent, iterateFiles, toPosix } from "./base.js";
+
+const CODE_EXTENSIONS = new Set([
+  ".js",
+  ".jsx",
+  ".ts",
+  ".tsx",
+  ".mjs",
+  ".cjs",
+  ".py",
+  ".go",
+  ".rb",
+]);
+
+const BLOCKING_IO_RULES = Object.freeze([
+  {
+    kind: "performance.blocking-sync-fs",
+    pattern:
+      /\b(?:fs\.)?(?:readFileSync|writeFileSync|appendFileSync|readdirSync|statSync|existsSync)\s*\(/,
+    severity: "P2",
+    rootCause:
+      "Synchronous filesystem call blocks the event loop or request worker while disk I/O completes.",
+    recommendedFix:
+      "Use async filesystem APIs and move startup-only reads outside hot request paths.",
+    confidence: 0.74,
+  },
+  {
+    kind: "performance.blocking-child-process",
+    pattern: /\b(?:execSync|spawnSync|execFileSync)\s*\(/,
+    severity: "P1",
+    rootCause:
+      "Synchronous child process execution blocks the runtime and can stall all concurrent requests.",
+    recommendedFix:
+      "Use async process APIs, queue the work, or precompute the artifact before serving traffic.",
+    confidence: 0.82,
+  },
+  {
+    kind: "performance.blocking-sleep",
+    pattern: /\b(?:sleepSync|Atomics\.wait|time\.sleep)\s*\(/,
+    severity: "P2",
+    rootCause:
+      "Blocking sleep pauses the worker instead of yielding, which turns transient waits into throughput loss.",
+    recommendedFix:
+      "Use async timers, scheduled jobs, or backoff that yields to the runtime event loop.",
+    confidence: 0.7,
+  },
+]);
+
+export async function runBlockingIoAudit({ rootPath, files = null } = {}) {
+  const resolvedRoot = path.resolve(String(rootPath || "."));
+  const findings = [];
+  for await (const { fullPath, relativePath } of iterateFiles(resolvedRoot, files, CODE_EXTENSIONS)) {
+    let content;
+    try {
+      content = await fsp.readFile(fullPath, "utf-8");
+    } catch {
+      continue;
+    }
+    for (const rule of BLOCKING_IO_RULES) {
+      for (const match of findLineMatches(content, rule.pattern)) {
+        findings.push(
+          createFinding({
+            tool: "blocking-io-audit",
+            kind: rule.kind,
+            severity: rule.severity,
+            file: toPosix(relativePath),
+            line: match.line,
+            evidence: getLineContent(content, match.line),
+            rootCause: rule.rootCause,
+            recommendedFix: rule.recommendedFix,
+            confidence: rule.confidence,
+          })
+        );
+      }
+    }
+  }
+  return findings;
+}
+
+export { BLOCKING_IO_RULES };

package/src/agents/performance/tools/bundle-budget-check.js

@@ -0,0 +1,93 @@
+// bundle-budget-check - flag heavy client imports and oversized assets (#A16).
+
+import fsp from "node:fs/promises";
+import path from "node:path";
+
+import { createFinding, findLineMatches, getLineContent, iterateFiles, toPosix } from "./base.js";
+
+const CLIENT_EXTENSIONS = new Set([
+  ".js",
+  ".jsx",
+  ".ts",
+  ".tsx",
+  ".mjs",
+  ".css",
+]);
+const FRONTEND_PATH_PATTERN =
+  /(?:^|\/)(?:app|pages|components|ui|frontend|client|public)(?:\/|$)/i;
+const LARGE_SOURCE_THRESHOLD_BYTES = 150 * 1024;
+const LARGE_STYLE_THRESHOLD_BYTES = 100 * 1024;
+const HEAVY_IMPORT_PATTERN =
+  /\bimport\s+[^;]*?\bfrom\s+["'](?:moment|lodash|chart\.js(?:\/auto)?|monaco-editor|mapbox-gl|three)["']|require\s*\(\s*["'](?:moment|lodash|chart\.js(?:\/auto)?|monaco-editor|mapbox-gl|three)["']\s*\)/g;
+
+function budgetForFile(relativePath) {
+  return path.extname(relativePath).toLowerCase() === ".css"
+    ? LARGE_STYLE_THRESHOLD_BYTES
+    : LARGE_SOURCE_THRESHOLD_BYTES;
+}
+
+export async function runBundleBudgetCheck({ rootPath, files = null } = {}) {
+  const resolvedRoot = path.resolve(String(rootPath || "."));
+  const findings = [];
+  for await (const { fullPath, relativePath, sizeBytes } of iterateFiles(
+    resolvedRoot,
+    files,
+    CLIENT_EXTENSIONS
+  )) {
+    const normalizedPath = toPosix(relativePath);
+    if (!FRONTEND_PATH_PATTERN.test(normalizedPath)) {
+      continue;
+    }
+    let content = "";
+    try {
+      content = await fsp.readFile(fullPath, "utf-8");
+    } catch {
+      continue;
+    }
+
+    const budget = budgetForFile(normalizedPath);
+    if (sizeBytes > budget) {
+      findings.push(
+        createFinding({
+          tool: "bundle-budget-check",
+          kind: "performance.bundle-budget-exceeded",
+          severity: "P2",
+          file: normalizedPath,
+          line: 1,
+          evidence: `size=${sizeBytes} bytes budget=${budget} bytes`,
+          rootCause:
+            "Client-side source/style file exceeds the local budget, increasing parse, transfer, and hydration cost.",
+          recommendedFix:
+            "Split the module, lazy-load non-critical code, move static data out of the client bundle, or add an explicit budget exception.",
+          confidence: 0.72,
+        })
+      );
+    }
+
+    for (const match of findLineMatches(content, HEAVY_IMPORT_PATTERN)) {
+      findings.push(
+        createFinding({
+          tool: "bundle-budget-check",
+          kind: "performance.heavy-client-import",
+          severity: "P2",
+          file: normalizedPath,
+          line: match.line,
+          evidence: getLineContent(content, match.line),
+          rootCause:
+            "Client code imports a known heavyweight package at module scope, which can inflate initial JavaScript payloads.",
+          recommendedFix:
+            "Use scoped imports, dynamic import(), route-level code splitting, or a lighter package.",
+          confidence: 0.66,
+        })
+      );
+    }
+  }
+  return findings;
+}
+
+export {
+  FRONTEND_PATH_PATTERN,
+  HEAVY_IMPORT_PATTERN,
+  LARGE_SOURCE_THRESHOLD_BYTES,
+  LARGE_STYLE_THRESHOLD_BYTES,
+};

package/src/agents/performance/tools/cache-policy-audit.js

@@ -0,0 +1,69 @@
+// cache-policy-audit - flag expensive handler work with no cache signal (#A16).
+
+import fsp from "node:fs/promises";
+import path from "node:path";
+
+import { createFinding, findLineMatches, getLineContent, iterateFiles, toPosix } from "./base.js";
+
+const CODE_EXTENSIONS = new Set([
+  ".js",
+  ".jsx",
+  ".ts",
+  ".tsx",
+  ".mjs",
+  ".cjs",
+  ".py",
+  ".go",
+  ".rb",
+]);
+
+const HANDLER_PATH_PATTERN =
+  /(?:^|\/)(?:api|app|routes|controllers|handlers|server|pages)(?:\/|$)/i;
+const EXPENSIVE_CALL_PATTERN =
+  /\b(?:fetch|axios(?:\.[a-z]+)?|got(?:\.[a-z]+)?|requests\.(?:get|post)|httpx\.(?:get|post)|db\.\w+|prisma\.\w+|repository\.\w+|query|execute)\s*\(/i;
+const CACHE_SIGNAL_PATTERN =
+  /\b(?:cache|cached|memoize|ttl|revalidate|stale-while-revalidate|Cache-Control|ETag|If-None-Match|max-age)\b/i;
+
+export async function runCachePolicyAudit({ rootPath, files = null } = {}) {
+  const resolvedRoot = path.resolve(String(rootPath || "."));
+  const findings = [];
+  for await (const { fullPath, relativePath } of iterateFiles(resolvedRoot, files, CODE_EXTENSIONS)) {
+    const normalizedPath = toPosix(relativePath);
+    if (!HANDLER_PATH_PATTERN.test(normalizedPath)) {
+      continue;
+    }
+    let content;
+    try {
+      content = await fsp.readFile(fullPath, "utf-8");
+    } catch {
+      continue;
+    }
+    if (!EXPENSIVE_CALL_PATTERN.test(content) || CACHE_SIGNAL_PATTERN.test(content)) {
+      continue;
+    }
+    const match = findLineMatches(content, EXPENSIVE_CALL_PATTERN)[0];
+    const line = match?.line || 1;
+    findings.push(
+      createFinding({
+        tool: "cache-policy-audit",
+        kind: "performance.missing-cache-policy",
+        severity: "P2",
+        file: normalizedPath,
+        line,
+        evidence: getLineContent(content, line),
+        rootCause:
+          "Request handler performs remote/database work without an explicit cache, TTL, revalidation, or HTTP cache-control signal.",
+        recommendedFix:
+          "Add an explicit cache policy: bounded TTL, request coalescing, stale-while-revalidate, ETag, or documented no-store rationale.",
+        confidence: 0.58,
+      })
+    );
+  }
+  return findings;
+}
+
+export {
+  CACHE_SIGNAL_PATTERN,
+  EXPENSIVE_CALL_PATTERN,
+  HANDLER_PATH_PATTERN,
+};

package/src/agents/performance/tools/index.js

@@ -0,0 +1,87 @@
+// Arjun (performance persona) domain-tool registry (#A16).
+
+import { runBlockingIoAudit } from "./blocking-io-audit.js";
+import { runBundleBudgetCheck } from "./bundle-budget-check.js";
+import { runCachePolicyAudit } from "./cache-policy-audit.js";
+import { runNPlusOneDetect } from "./n-plus-one-detect.js";
+
+export const PERFORMANCE_TOOLS = Object.freeze({
+  "n-plus-one-detect": {
+    id: "n-plus-one-detect",
+    description:
+      "Flag loop-scoped HTTP, database, repository, or query calls that can become N+1 fan-out under load.",
+    schema: {
+      type: "object",
+      properties: {
+        rootPath: { type: "string" },
+        files: { type: "array", items: { type: "string" } },
+      },
+    },
+    handler: runNPlusOneDetect,
+  },
+  "blocking-io-audit": {
+    id: "blocking-io-audit",
+    description:
+      "Flag synchronous filesystem, child-process, or sleep calls that block hot runtime paths.",
+    schema: {
+      type: "object",
+      properties: {
+        rootPath: { type: "string" },
+        files: { type: "array", items: { type: "string" } },
+      },
+    },
+    handler: runBlockingIoAudit,
+  },
+  "cache-policy-audit": {
+    id: "cache-policy-audit",
+    description:
+      "Flag request handlers that do expensive remote/database work without a cache, TTL, revalidation, or no-store policy.",
+    schema: {
+      type: "object",
+      properties: {
+        rootPath: { type: "string" },
+        files: { type: "array", items: { type: "string" } },
+      },
+    },
+    handler: runCachePolicyAudit,
+  },
+  "bundle-budget-check": {
+    id: "bundle-budget-check",
+    description:
+      "Flag oversized client files and heavyweight module-scope imports that can inflate frontend bundles.",
+    schema: {
+      type: "object",
+      properties: {
+        rootPath: { type: "string" },
+        files: { type: "array", items: { type: "string" } },
+      },
+    },
+    handler: runBundleBudgetCheck,
+  },
+});
+
+export const PERFORMANCE_TOOL_IDS = Object.freeze(Object.keys(PERFORMANCE_TOOLS));
+
+export async function dispatchPerformanceTool(toolId, args = {}) {
+  const tool = PERFORMANCE_TOOLS[toolId];
+  if (!tool) {
+    throw new Error(`Unknown performance tool: ${toolId}`);
+  }
+  return tool.handler(args);
+}
+
+export async function runAllPerformanceTools({ rootPath, files = null } = {}) {
+  const findings = [];
+  for (const toolId of PERFORMANCE_TOOL_IDS) {
+    const out = await dispatchPerformanceTool(toolId, { rootPath, files });
+    findings.push(...out);
+  }
+  return findings;
+}
+
+export {
+  runBlockingIoAudit,
+  runBundleBudgetCheck,
+  runCachePolicyAudit,
+  runNPlusOneDetect,
+};

package/src/agents/performance/tools/n-plus-one-detect.js

@@ -0,0 +1,54 @@
+// n-plus-one-detect - flag loop-scoped I/O and query calls (#A16).
+
+import fsp from "node:fs/promises";
+import path from "node:path";
+
+import { createFinding, findLineMatches, getLineContent, iterateFiles, toPosix } from "./base.js";
+
+const CODE_EXTENSIONS = new Set([
+  ".js",
+  ".jsx",
+  ".ts",
+  ".tsx",
+  ".mjs",
+  ".cjs",
+  ".py",
+  ".rb",
+  ".go",
+]);
+
+const LOOP_IO_PATTERN =
+  /(?:for\s*(?:await\s*)?\([^)]*\)|while\s*\([^)]*\)|\.forEach\s*\([^=]*=>)\s*\{?[\s\S]{0,650}?\b(?:await\s+)?(?:fetch|axios(?:\.[a-z]+)?|got(?:\.[a-z]+)?|requests\.(?:get|post)|httpx\.(?:get|post)|db\.\w+|prisma\.\w+|repository\.\w+|Model\.\w+|findAll|findMany|find_one|find_all|query|execute)\s*\(/gi;
+
+export async function runNPlusOneDetect({ rootPath, files = null } = {}) {
+  const resolvedRoot = path.resolve(String(rootPath || "."));
+  const findings = [];
+  for await (const { fullPath, relativePath } of iterateFiles(resolvedRoot, files, CODE_EXTENSIONS)) {
+    let content;
+    try {
+      content = await fsp.readFile(fullPath, "utf-8");
+    } catch {
+      continue;
+    }
+    for (const match of findLineMatches(content, LOOP_IO_PATTERN)) {
+      findings.push(
+        createFinding({
+          tool: "n-plus-one-detect",
+          kind: "performance.n-plus-one-loop",
+          severity: "P1",
+          file: toPosix(relativePath),
+          line: match.line,
+          evidence: getLineContent(content, match.line),
+          rootCause:
+            "Loop body performs a database, HTTP, or repository call. Runtime cost grows linearly with item count and can become an N+1 query or fan-out storm.",
+          recommendedFix:
+            "Batch the work outside the loop, prefetch related data, use `WHERE id IN (...)`, or add a bounded concurrency pool with request coalescing.",
+          confidence: 0.68,
+        })
+      );
+    }
+  }
+  return findings;
+}
+
+export { LOOP_IO_PATTERN };

package/src/agents/run-persona.js

@@ -35,6 +35,8 @@ const PERSONA_LOADERS = Object.freeze({
     (await import("./infrastructure/index.js")).runAllInfrastructureTools,
   "observability": async () =>
     (await import("./observability/index.js")).runAllObservabilityTools,
+  "performance": async () =>
+    (await import("./performance/index.js")).runAllPerformanceTools,
   "release": async () =>
     (await import("./release/index.js")).runAllReleaseTools,
   "reliability": async () =>

package/src/commands/session.js

@@ -100,6 +100,7 @@ import {
   listSessionMessageActions,
   listSessionsFromApi,
   probeSessionAccess,
+  pollHumanMessages,
   pollSessionEvents,
   pollSessionEventsBefore,
   searchSessionEvents,
@@ -237,6 +238,8 @@ const SESSION_SAY_LOCAL_ONLY_REASONS = new Set([
   "remote_sync_disabled_env",
 ]);
 const SESSION_READ_AUTO_VIEW_TIMEOUT_MS = 500;
+const SESSION_RECAP_REMOTE_REQUEST_TIMEOUT_MS = 5_000;
+const SESSION_RECAP_REMOTE_HYDRATE_MAX_PAGES = 1;
 
 function isLocalOnlySessionSayReason(reason) {
   return SESSION_SAY_LOCAL_ONLY_REASONS.has(normalizeString(reason));
@@ -5565,11 +5568,24 @@ export function registerSessionCommand(program) {
         hydration = await hydrateSessionFromRemote({
           sessionId: normalizedSessionId,
           targetPath,
+          eventPageLimit: maxEvents,
+          maxEventPages: SESSION_RECAP_REMOTE_HYDRATE_MAX_PAGES,
+          _poll: (pollSessionId, pollOptions) =>
+            pollHumanMessages(pollSessionId, {
+              ...pollOptions,
+              limit: maxEvents,
+              timeoutMs: SESSION_RECAP_REMOTE_REQUEST_TIMEOUT_MS,
+            }),
+          _pollEvents: (pollSessionId, pollOptions) =>
+            pollSessionEvents(pollSessionId, {
+              ...pollOptions,
+              timeoutMs: SESSION_RECAP_REMOTE_REQUEST_TIMEOUT_MS,
+            }),
         });
         remoteTail = await pollSessionEventsBefore(normalizedSessionId, {
           targetPath,
           limit: maxEvents,
-          timeoutMs: 15_000,
+          timeoutMs: SESSION_RECAP_REMOTE_REQUEST_TIMEOUT_MS,
         });
         if (remoteTail?.ok && Array.isArray(remoteTail.events) && remoteTail.events.length > 0) {
           remoteAppend = await appendMissingRemoteEvents(normalizedSessionId, remoteTail.events, {

package/src/review/investor-dd-persona-runner.js

@@ -1,9 +1,9 @@
 /**
  * Unified per-persona runner for investor-DD (#investor-dd-4..15).
  *
- * Wires the 13 domain personas (security, backend, code-quality, testing,
- * data-layer, reliability, release, observability, infrastructure,
- * supply-chain, frontend, documentation, ai-governance) into the review
+ * Wires the 14 domain personas (security, backend, code-quality, testing,
+ * data-layer, performance, reliability, release, observability,
+ * infrastructure, supply-chain, frontend, documentation, ai-governance) into the review
  * loop. Each persona dispatches its declared domain tools against every
  * file the router assigns to it, collects findings, and returns a
  * per-persona coverage proof.
@@ -23,6 +23,7 @@ import { DATA_LAYER_TOOLS } from "../agents/data-layer/tools/index.js";
 import { DOCUMENTATION_TOOLS } from "../agents/documentation/tools/index.js";
 import { INFRASTRUCTURE_TOOLS } from "../agents/infrastructure/tools/index.js";
 import { OBSERVABILITY_TOOLS } from "../agents/observability/tools/index.js";
+import { PERFORMANCE_TOOLS } from "../agents/performance/tools/index.js";
 import { RELEASE_TOOLS } from "../agents/release/tools/index.js";
 import { RELIABILITY_TOOLS } from "../agents/reliability/tools/index.js";
 import { SECURITY_TOOLS } from "../agents/security/tools/index.js";
@@ -44,6 +45,7 @@ export const INVESTOR_DD_PERSONA_TOOL_REGISTRY = Object.freeze({
   reliability: RELIABILITY_TOOLS,
   release: RELEASE_TOOLS,
   observability: OBSERVABILITY_TOOLS,
+  performance: PERFORMANCE_TOOLS,
   infrastructure: INFRASTRUCTURE_TOOLS,
   "supply-chain": SUPPLY_CHAIN_TOOLS,
   frontend: FRONTEND_TOOLS,