sentinelayer-cli 0.4.5 → 0.8.0

package/src/review/persona-prompts.js

@@ -0,0 +1,296 @@
+/**
+ * Persona-scoped system prompts for Omar Gate AI analysis.
+ *
+ * Each persona gets a domain-focused prompt that constrains the LLM
+ * to analyze code through a specific security/quality lens.
+ */
+
+const PERSONA_PROMPTS = {
+  security: {
+    role: "Nina Patel — Security Specialist",
+    focus: `You are a security specialist reviewing code for exploitable vulnerabilities.
+
+Focus areas:
+- Authentication and authorization bypass paths
+- Secret/credential exposure in code, configs, logs, and environment
+- Injection vectors: SQL, shell, XSS, SSRF, path traversal
+- Cryptographic weaknesses: weak hashing, hardcoded keys, insecure TLS
+- Session management: fixation, token leakage, cookie misconfiguration
+- Rate limiting gaps on auth and payment endpoints
+- CORS misconfiguration allowing unauthorized origins
+- Insecure deserialization and dynamic code execution (eval, Function)
+
+Evidence standard: Every finding MUST include file:line, exploit scenario, and remediation.
+Do NOT report hypothetical issues without concrete code evidence.`,
+  },
+
+  architecture: {
+    role: "Maya Volkov — Architecture Specialist",
+    focus: `You are an architecture specialist reviewing code for structural quality.
+
+Focus areas:
+- God components/modules (>300 LOC, >10 responsibilities)
+- Circular dependencies between modules
+- Tight coupling between layers (presentation → data access)
+- Missing abstraction boundaries (business logic in route handlers)
+- State management sprawl (>15 useState in a component)
+- Missing error boundaries and fallback handling
+- Inconsistent naming/organization patterns
+- Dead code and unreachable paths
+
+Evidence standard: Every finding MUST include file:line, coupling graph or complexity metric, and refactoring guidance.`,
+  },
+
+  testing: {
+    role: "Priya Raman — Testing Specialist",
+    focus: `You are a testing specialist reviewing code for coverage gaps and test quality.
+
+Focus areas:
+- Critical paths without test coverage (auth, payment, data mutation)
+- Tests that mock too much (false confidence)
+- Missing edge case tests (empty inputs, boundary values, error paths)
+- Flaky test patterns (timing, external dependencies, shared state)
+- Missing integration tests for API endpoints
+- No E2E tests for critical user flows
+- Test data that doesn't represent production scenarios
+- Missing assertion specificity (assertTrue vs assertEquals)
+
+Evidence standard: Every finding MUST include the untested code path (file:line) and a concrete test case outline.`,
+  },
+
+  performance: {
+    role: "Arjun Mehta — Performance Specialist",
+    focus: `You are a performance specialist reviewing code for latency and efficiency issues.
+
+Focus areas:
+- N+1 query patterns (loop-based database calls)
+- Missing database indexes on WHERE/JOIN/ORDER BY columns
+- Unbounded data fetching (no LIMIT, no pagination)
+- Synchronous blocking in async contexts
+- Memory leaks (unclosed connections, event listeners, timers)
+- Bundle size bloat (large imports, no tree shaking, no code splitting)
+- Missing caching for expensive computations
+- Render performance (unnecessary re-renders, missing memoization)
+
+Evidence standard: Every finding MUST include file:line, estimated performance impact, and optimization approach.`,
+  },
+
+  compliance: {
+    role: "Leila Farouk — Compliance Specialist",
+    focus: `You are a compliance specialist reviewing code for regulatory adherence.
+
+Focus areas:
+- PII handling without encryption or access controls
+- Missing audit logging for data access and mutations
+- GDPR: data retention without deletion mechanisms
+- SOC2: missing access controls, no principle of least privilege
+- HIPAA: PHI exposure, missing BAA requirements
+- Missing consent tracking for data collection
+- Insecure data export/download without authorization
+- Missing data classification and sensitivity labels
+
+Evidence standard: Every finding MUST include the regulatory requirement, the gap, and the remediation with compliance evidence.`,
+  },
+
+  documentation: {
+    role: "Samir Okafor — Documentation Specialist",
+    focus: `You are a documentation specialist reviewing for operational clarity.
+
+Focus areas:
+- Missing or outdated README/setup instructions
+- API endpoints without documentation
+- Missing runbooks for incident response
+- Configuration options without documentation
+- Missing architecture decision records (ADRs)
+- Outdated deployment instructions
+- Missing onboarding documentation for new developers
+
+Evidence standard: Every finding MUST include what is missing, where it should live, and a draft outline.`,
+  },
+
+  reliability: {
+    role: "Noah Ben-David — Reliability Specialist",
+    focus: `You are a reliability specialist reviewing code for fault tolerance.
+
+Focus areas:
+- Missing timeout configuration on external calls
+- No retry logic or exponential backoff for transient failures
+- Missing circuit breakers on external service calls
+- No graceful degradation when dependencies are down
+- Missing health check endpoints
+- Queue backpressure handling gaps
+- Missing dead letter queue for failed jobs
+- No idempotency keys on mutation endpoints
+
+Evidence standard: Every finding MUST include the failure scenario, blast radius, and resilience pattern to apply.`,
+  },
+
+  release: {
+    role: "Omar Singh — Release Engineering Specialist",
+    focus: `You are a release engineering specialist reviewing CI/CD and deployment.
+
+Focus areas:
+- Unpinned GitHub Actions (using @main instead of SHA)
+- Missing artifact signing or provenance attestation
+- No rollback mechanism in deployment pipeline
+- Missing smoke tests after deploy
+- Secrets in CI/CD logs or artifacts
+- Missing branch protection rules
+- No canary or staged rollout strategy
+- Deploy pipeline without quality gates
+
+Evidence standard: Every finding MUST include the workflow file:line, risk, and the hardened alternative.`,
+  },
+
+  observability: {
+    role: "Sofia Alvarez — Observability Specialist",
+    focus: `You are an observability specialist reviewing telemetry and alerting.
+
+Focus areas:
+- Missing structured logging (console.log without context)
+- No request tracing (missing correlation IDs)
+- Missing error tracking integration
+- No alerting on error rate spikes
+- Missing latency tracking on critical paths
+- No dashboard for key business metrics
+- Missing SLO/SLI definitions
+- Blind spots: operations without any telemetry
+
+Evidence standard: Every finding MUST include what metric/signal is missing, where to instrument, and the alert threshold.`,
+  },
+
+  infrastructure: {
+    role: "Kat Hughes — Infrastructure Specialist",
+    focus: `You are an infrastructure specialist reviewing cloud and deployment config.
+
+Focus areas:
+- Overly permissive IAM policies (wildcard actions/resources)
+- Public-facing resources without WAF/rate limiting
+- Missing encryption at rest or in transit
+- Hardcoded infrastructure values (IPs, ARNs, account IDs)
+- Missing VPC/subnet isolation
+- No secrets rotation policy
+- Missing backup and disaster recovery configuration
+- Infrastructure drift (manual changes not in IaC)
+
+Evidence standard: Every finding MUST include the resource, the misconfiguration, blast radius, and the IaC fix.`,
+  },
+
+  "supply-chain": {
+    role: "Nora Kline — Supply Chain Specialist",
+    focus: `You are a supply chain specialist reviewing dependency security.
+
+Focus areas:
+- Dependencies with known CVEs (critical/high severity)
+- Unpinned dependency versions (using ^/~ instead of exact)
+- Dependencies from untrusted or abandoned packages
+- Missing lockfile integrity checks
+- No SBOM generation in build pipeline
+- Typosquatting risk (similar package names)
+- Excessive dependency tree depth
+- Missing license compliance checks
+
+Evidence standard: Every finding MUST include the package name, version, CVE/risk, and the pinned/patched alternative.`,
+  },
+
+  frontend: {
+    role: "Jules Tanaka — Frontend Specialist",
+    focus: `You are a frontend specialist reviewing UI code for production readiness.
+
+Focus areas:
+- XSS via dangerouslySetInnerHTML without sanitization
+- Client-side token storage in localStorage (use httpOnly cookies)
+- Missing input validation on forms
+- Accessibility failures (missing alt text, labels, keyboard navigation)
+- Bundle size > 200KB initial JS
+- Missing error boundaries around route components
+- CLS-causing patterns (images without dimensions, dynamic content injection)
+- Missing loading/error states on data fetching
+
+Evidence standard: Every finding MUST include file:line, user impact, and the specific fix.`,
+  },
+
+  "ai-governance": {
+    role: "Amina Chen — AI Governance Specialist",
+    focus: `You are an AI governance specialist reviewing AI/ML code safety.
+
+Focus areas:
+- Prompt injection vectors in user-facing LLM prompts
+- Missing input sanitization before LLM calls
+- No rate limiting on AI endpoints
+- Missing cost/token budget enforcement
+- No human-in-the-loop for high-risk AI decisions
+- Missing model versioning and eval regression checks
+- Tool/agent permission escalation risks
+- Missing audit trail for AI-generated actions
+
+Evidence standard: Every finding MUST include the injection/bypass scenario, the affected code path, and the guardrail to add.`,
+  },
+};
+
+/**
+ * Build a persona-scoped system prompt for Omar Gate AI analysis.
+ *
+ * @param {object} options
+ * @param {string} options.personaId - Agent ID (e.g., "security", "architecture")
+ * @param {string} [options.targetPath] - Repository path
+ * @param {object} [options.deterministicSummary] - Summary from deterministic scan
+ * @param {number} [options.maxFindings] - Max findings to return (default 20)
+ * @returns {string} System prompt
+ */
+export function buildPersonaReviewPrompt({
+  personaId,
+  targetPath = "",
+  deterministicSummary = {},
+  maxFindings = 20,
+} = {}) {
+  const persona = PERSONA_PROMPTS[personaId];
+  if (!persona) {
+    return buildGenericPrompt({ targetPath, deterministicSummary, maxFindings });
+  }
+
+  return `# ${persona.role}
+
+${persona.focus}
+
+## Context
+Target: ${targetPath || "(not provided)"}
+Deterministic scan: P0=${deterministicSummary.P0 || 0} P1=${deterministicSummary.P1 || 0} P2=${deterministicSummary.P2 || 0} P3=${deterministicSummary.P3 || 0}
+
+## Output Contract
+Return a JSON array of findings. Maximum ${maxFindings} findings. Each finding:
+\`\`\`json
+{
+  "severity": "P0|P1|P2|P3",
+  "file": "path/to/file.ext",
+  "line": 42,
+  "title": "Brief description",
+  "evidence": "Concrete code evidence at file:line",
+  "rootCause": "Why this is a problem",
+  "recommendedFix": "Specific fix to apply",
+  "confidence": 0.85
+}
+\`\`\`
+
+Rules:
+- Only report findings you have HIGH confidence in (>= 0.7)
+- Every finding MUST have concrete file:line evidence
+- Do NOT repeat findings already in the deterministic scan
+- Do NOT report hypothetical/speculative issues
+- Focus on REAL, EXPLOITABLE, IMPACTFUL problems in your domain
+- Return ONLY the JSON array, no other text
+`;
+}
+
+function buildGenericPrompt({ targetPath, deterministicSummary, maxFindings }) {
+  return `You are a senior code reviewer. Analyze the code for security, quality, and reliability issues.
+
+Target: ${targetPath || "(not provided)"}
+Deterministic scan: P0=${deterministicSummary.P0 || 0} P1=${deterministicSummary.P1 || 0} P2=${deterministicSummary.P2 || 0}
+
+Return a JSON array of up to ${maxFindings} findings with: severity, file, line, title, evidence, rootCause, recommendedFix, confidence.
+Only report findings with concrete evidence. Do NOT repeat deterministic findings.`;
+}
+
+export const PERSONA_IDS = Object.keys(PERSONA_PROMPTS);
+export { PERSONA_PROMPTS };

package/src/review/scan-modes.js

@@ -0,0 +1,48 @@
+/**
+ * Scan mode → persona list resolution for Omar Gate.
+ *
+ * baseline:   security only (~30s)
+ * deep:       all 13 personas (~3-5min) — alias of full-depth from v0.7+
+ * audit:      alias for full-depth
+ * full-depth: all 13 personas (~3-5min)
+ *
+ * v0.7 change (2026-04-16): `deep` was a 6-persona subset and missed
+ * domain specialists (Maya/backend, Jules/frontend, Nora/supply-chain,
+ * Samir/documentation, etc.). Users running `sl /omargate deep` expected
+ * a full dispatch. Deep now matches full-depth to prevent silent coverage
+ * gaps; run `baseline` when you only need security.
+ */
+
+const FULL_DEPTH_PERSONAS = [
+  "security",
+  "architecture",
+  "testing",
+  "performance",
+  "compliance",
+  "reliability",
+  "release",
+  "observability",
+  "infrastructure",
+  "supply-chain",
+  "frontend",
+  "documentation",
+  "ai-governance",
+];
+
+const SCAN_MODES = {
+  baseline: ["security"],
+  deep: FULL_DEPTH_PERSONAS,
+  "full-depth": FULL_DEPTH_PERSONAS,
+  audit: FULL_DEPTH_PERSONAS,
+};
+
+export function resolveScanMode(mode = "deep") {
+  const normalized = String(mode || "deep").trim().toLowerCase();
+  const personas = SCAN_MODES[normalized];
+  if (!personas) {
+    throw new Error(`Unknown scan mode '${mode}'. Use: ${Object.keys(SCAN_MODES).join(", ")}`);
+  }
+  return { mode: normalized, personas: [...personas] };
+}
+
+export const AVAILABLE_SCAN_MODES = Object.keys(SCAN_MODES);

package/src/scan/generator.js

@@ -161,7 +161,7 @@ export function buildSecurityReviewWorkflow({ secretName = DEFAULT_SCAN_SECRET_N
             required: false,
             default: profile.scanMode || "deep",
             type: "choice",
-            options: ["deep", "nightly"],
+            options: ["baseline", "deep", "audit", "full-depth"],
           },
           severity_gate: {
             description: "Severity threshold that blocks merge",

package/src/session/agent-registry.js

@@ -0,0 +1,352 @@
+import { randomBytes } from "node:crypto";
+import fsp from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+
+import { STUCK_THRESHOLDS } from "../agents/jules/pulse.js";
+import { createAgentEvent } from "../events/schema.js";
+import { resolveSessionPaths } from "./paths.js";
+import { appendToStream } from "./stream.js";
+
+const AGENT_SNAPSHOT_SCHEMA_VERSION = "1.0.0";
+
+const AGENT_ROLES = new Set([
+  "coder",
+  "reviewer",
+  "tester",
+  "daemon",
+  "observer",
+  "persona",
+]);
+
+const AGENT_STATUSES = new Set([
+  "coding",
+  "reviewing",
+  "testing",
+  "idle",
+  "blocked",
+  "watching",
+]);
+
+const LEAVE_REASONS = new Set([
+  "task_complete",
+  "error",
+  "timeout",
+  "manual",
+  "killed",
+]);
+
+function normalizeString(value) {
+  return String(value || "").trim();
+}
+
+function normalizeIsoTimestamp(value, fallbackIso = new Date().toISOString()) {
+  const normalized = normalizeString(value);
+  if (!normalized) {
+    return fallbackIso;
+  }
+  const epoch = Date.parse(normalized);
+  if (!Number.isFinite(epoch)) {
+    return fallbackIso;
+  }
+  return new Date(epoch).toISOString();
+}
+
+function normalizeRole(value) {
+  const normalized = normalizeString(value).toLowerCase();
+  if (!AGENT_ROLES.has(normalized)) {
+    throw new Error(`role must be one of: ${[...AGENT_ROLES].join(", ")}.`);
+  }
+  return normalized;
+}
+
+function normalizeStatus(value, fallbackValue = "idle") {
+  const normalized = normalizeString(value).toLowerCase();
+  if (!normalized) {
+    return fallbackValue;
+  }
+  if (!AGENT_STATUSES.has(normalized)) {
+    throw new Error(`status must be one of: ${[...AGENT_STATUSES].join(", ")}.`);
+  }
+  return normalized;
+}
+
+function normalizeLeaveReason(value) {
+  const normalized = normalizeString(value).toLowerCase();
+  if (!normalized) {
+    return "manual";
+  }
+  if (!LEAVE_REASONS.has(normalized)) {
+    throw new Error(`reason must be one of: ${[...LEAVE_REASONS].join(", ")}.`);
+  }
+  return normalized;
+}
+
+function sanitizePrefix(value) {
+  const normalized = normalizeString(value)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  if (!normalized) {
+    return "";
+  }
+  return normalized.slice(0, 12);
+}
+
+function deriveModelPrefix(modelName) {
+  const normalized = normalizeString(modelName).toLowerCase();
+  if (!normalized) {
+    return "agent";
+  }
+  if (normalized.includes("claude")) return "claude";
+  if (normalized.includes("codex")) return "codex";
+  if (normalized.includes("gpt")) return "codex";
+  if (normalized.includes("sonnet")) return "sonnet";
+  if (normalized.includes("senti") || normalized.includes("sentinel")) return "senti";
+
+  const token = normalized.split(/[\s:/_-]+/).find(Boolean) || normalized;
+  return sanitizePrefix(token) || "agent";
+}
+
+function normalizeAgentSnapshot(snapshot = {}, nowIso = new Date().toISOString()) {
+  return {
+    schemaVersion: AGENT_SNAPSHOT_SCHEMA_VERSION,
+    sessionId: normalizeString(snapshot.sessionId),
+    agentId: normalizeString(snapshot.agentId),
+    model: normalizeString(snapshot.model) || "unknown",
+    role: normalizeRole(snapshot.role || "observer"),
+    status: normalizeStatus(snapshot.status, "idle"),
+    detail: normalizeString(snapshot.detail) || "",
+    file: normalizeString(snapshot.file) || null,
+    joinedAt: normalizeIsoTimestamp(snapshot.joinedAt, nowIso),
+    lastActivityAt: normalizeIsoTimestamp(snapshot.lastActivityAt, nowIso),
+    leftAt: snapshot.leftAt ? normalizeIsoTimestamp(snapshot.leftAt, nowIso) : null,
+    leaveReason: snapshot.leaveReason ? normalizeLeaveReason(snapshot.leaveReason) : null,
+    active: snapshot.active !== false,
+    updatedAt: normalizeIsoTimestamp(snapshot.updatedAt, nowIso),
+  };
+}
+
+async function readAgentSnapshot(snapshotPath) {
+  try {
+    const raw = await fsp.readFile(snapshotPath, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return null;
+    }
+    return parsed;
+  } catch (error) {
+    if (error && typeof error === "object" && error.code === "ENOENT") {
+      return null;
+    }
+    throw error;
+  }
+}
+
+async function writeAgentSnapshot(snapshotPath, snapshot) {
+  await fsp.mkdir(path.dirname(snapshotPath), { recursive: true });
+  const tmpPath = `${snapshotPath}.${process.pid}.${Date.now()}.tmp`;
+  await fsp.writeFile(tmpPath, `${JSON.stringify(snapshot, null, 2)}\n`, "utf-8");
+  await fsp.rename(tmpPath, snapshotPath);
+}
+
+async function emitAgentEvent(sessionId, event, payload, { targetPath = process.cwd() } = {}) {
+  const envelope = createAgentEvent({
+    event,
+    agentId: payload.agentId,
+    sessionId,
+    payload,
+  });
+  await appendToStream(sessionId, envelope, { targetPath });
+}
+
+function buildAgentSnapshotPath(paths, agentId) {
+  const normalizedAgentId = normalizeString(agentId);
+  if (!normalizedAgentId) {
+    throw new Error("agentId is required.");
+  }
+  return path.join(paths.agentsDir, `${normalizedAgentId}.json`);
+}
+
+export function generateAgentId(modelName) {
+  const prefix = deriveModelPrefix(modelName);
+  const suffix = randomBytes(2).toString("hex");
+  return `${prefix}-${suffix}`;
+}
+
+export async function registerAgent(
+  sessionId,
+  { agentId = "", model = "", role = "observer", targetPath = process.cwd() } = {}
+) {
+  const paths = resolveSessionPaths(sessionId, { targetPath });
+  const nowIso = new Date().toISOString();
+  const resolvedAgentId = normalizeString(agentId) || generateAgentId(model);
+  const snapshotPath = buildAgentSnapshotPath(paths, resolvedAgentId);
+
+  const snapshot = normalizeAgentSnapshot(
+    {
+      sessionId: paths.sessionId,
+      agentId: resolvedAgentId,
+      model: normalizeString(model) || "unknown",
+      role,
+      status: "idle",
+      detail: "",
+      file: null,
+      joinedAt: nowIso,
+      lastActivityAt: nowIso,
+      leftAt: null,
+      leaveReason: null,
+      active: true,
+      updatedAt: nowIso,
+    },
+    nowIso
+  );
+
+  await writeAgentSnapshot(snapshotPath, snapshot);
+  await emitAgentEvent(paths.sessionId, "agent_join", {
+    agentId: snapshot.agentId,
+    model: snapshot.model,
+    role: snapshot.role,
+    status: snapshot.status,
+  }, { targetPath });
+
+  return {
+    ...snapshot,
+    snapshotPath,
+  };
+}
+
+export async function heartbeatAgent(
+  sessionId,
+  agentId,
+  { status = "", detail = "", file = "", targetPath = process.cwd() } = {}
+) {
+  const paths = resolveSessionPaths(sessionId, { targetPath });
+  const nowIso = new Date().toISOString();
+  const snapshotPath = buildAgentSnapshotPath(paths, agentId);
+  const existing = await readAgentSnapshot(snapshotPath);
+  if (!existing) {
+    throw new Error(`Agent '${normalizeString(agentId)}' is not registered in session '${paths.sessionId}'.`);
+  }
+
+  const snapshot = normalizeAgentSnapshot(
+    {
+      ...existing,
+      status: normalizeStatus(status, normalizeStatus(existing.status || "idle")),
+      detail: normalizeString(detail) || normalizeString(existing.detail),
+      file: normalizeString(file) || normalizeString(existing.file) || null,
+      lastActivityAt: nowIso,
+      updatedAt: nowIso,
+      active: true,
+    },
+    nowIso
+  );
+
+  await writeAgentSnapshot(snapshotPath, snapshot);
+  return {
+    ...snapshot,
+    snapshotPath,
+  };
+}
+
+export async function unregisterAgent(
+  sessionId,
+  agentId,
+  { reason = "manual", targetPath = process.cwd() } = {}
+) {
+  const paths = resolveSessionPaths(sessionId, { targetPath });
+  const nowIso = new Date().toISOString();
+  const snapshotPath = buildAgentSnapshotPath(paths, agentId);
+  const existing = await readAgentSnapshot(snapshotPath);
+  if (!existing) {
+    throw new Error(`Agent '${normalizeString(agentId)}' is not registered in session '${paths.sessionId}'.`);
+  }
+
+  const normalizedReason = normalizeLeaveReason(reason);
+  const snapshot = normalizeAgentSnapshot(
+    {
+      ...existing,
+      active: false,
+      leftAt: nowIso,
+      leaveReason: normalizedReason,
+      updatedAt: nowIso,
+    },
+    nowIso
+  );
+
+  await writeAgentSnapshot(snapshotPath, snapshot);
+  await emitAgentEvent(paths.sessionId, "agent_leave", {
+    agentId: snapshot.agentId,
+    reason: normalizedReason,
+    role: snapshot.role,
+    model: snapshot.model,
+  }, { targetPath });
+
+  return {
+    ...snapshot,
+    snapshotPath,
+  };
+}
+
+export async function listAgents(
+  sessionId,
+  { targetPath = process.cwd(), includeInactive = true } = {}
+) {
+  const paths = resolveSessionPaths(sessionId, { targetPath });
+  let entries = [];
+  try {
+    entries = await fsp.readdir(paths.agentsDir, { withFileTypes: true });
+  } catch (error) {
+    if (error && typeof error === "object" && error.code === "ENOENT") {
+      return [];
+    }
+    throw error;
+  }
+
+  const agents = [];
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith(".json")) continue;
+    const snapshotPath = path.join(paths.agentsDir, entry.name);
+    const raw = await readAgentSnapshot(snapshotPath);
+    if (!raw) continue;
+    const normalized = normalizeAgentSnapshot(raw);
+    if (normalized.sessionId !== paths.sessionId) continue;
+    if (!includeInactive && normalized.active === false) continue;
+    agents.push({
+      ...normalized,
+      snapshotPath,
+    });
+  }
+
+  agents.sort((left, right) => right.lastActivityAt.localeCompare(left.lastActivityAt));
+  return agents;
+}
+
+export function detectStaleAgents(
+  agents,
+  {
+    idleThresholdSeconds = Number(STUCK_THRESHOLDS?.noToolCallSeconds || 90),
+    nowIso = new Date().toISOString(),
+  } = {}
+) {
+  const normalizedThreshold = Math.max(1, Math.floor(Number(idleThresholdSeconds || 90)));
+  const nowEpoch = Date.parse(normalizeIsoTimestamp(nowIso, new Date().toISOString()));
+  if (!Number.isFinite(nowEpoch)) {
+    return [];
+  }
+  const list = Array.isArray(agents) ? agents : [];
+  return list
+    .map((agent) => normalizeAgentSnapshot(agent, nowIso))
+    .filter((agent) => agent.active !== false)
+    .map((agent) => {
+      const activityEpoch = Date.parse(normalizeIsoTimestamp(agent.lastActivityAt, agent.joinedAt || nowIso));
+      const idleSeconds = Number.isFinite(activityEpoch)
+        ? Math.max(0, Math.floor((nowEpoch - activityEpoch) / 1000))
+        : normalizedThreshold + 1;
+      return {
+        ...agent,
+        idleSeconds,
+      };
+    })
+    .filter((agent) => agent.idleSeconds >= normalizedThreshold);
+}