sentinelayer-cli 0.8.0 → 0.8.1

package/src/agents/infrastructure/index.js

@@ -0,0 +1,12 @@
+// Kat (infrastructure persona) — barrel export (#A21).
+
+export {
+  INFRASTRUCTURE_TOOLS,
+  INFRASTRUCTURE_TOOL_IDS,
+  dispatchInfrastructureTool,
+  runAllInfrastructureTools,
+  runCheckovRun,
+  runDriftDetect,
+  runIamLeastPrivCheck,
+  runTflintRun,
+} from "./tools/index.js";

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

@@ -0,0 +1,171 @@
+// Shared helpers for Kat's (infrastructure) domain tools (#A21).
+
+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 createFinding({
+  severity,
+  kind,
+  file,
+  line = 0,
+  evidence = "",
+  rootCause = "",
+  recommendedFix = "",
+  confidence = null,
+  tool = "",
+  persona = "infrastructure",
+} = {}) {
+  const normalizedSeverity = SEVERITIES.includes(String(severity || "").toUpperCase())
+    ? String(severity).toUpperCase()
+    : "P2";
+  return {
+    persona,
+    tool: String(tool || "").trim(),
+    kind: String(kind || "").trim() || "infrastructure",
+    severity: normalizedSeverity,
+    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 };
+    }
+  }
+}
+
+export function findLineMatches(content, pattern) {
+  const text = String(content || "");
+  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();
+}

package/src/agents/infrastructure/tools/checkov-run.js

@@ -0,0 +1,32 @@
+// checkov-run — advise when IaC is present but Checkov config is not (#A21).
+
+import path from "node:path";
+
+import { createFinding, toPosix, walkRepoFiles } from "./base.js";
+
+export async function runCheckovRun({ rootPath } = {}) {
+  const resolvedRoot = path.resolve(String(rootPath || "."));
+  let hasIac = false;
+  let hasConfig = false;
+  for await (const { relativePath } of walkRepoFiles({ rootPath: resolvedRoot })) {
+    const rel = toPosix(relativePath);
+    if (/\.tf$/i.test(rel)) hasIac = true;
+    if (/(^|\/)Dockerfile(\.[\w-]+)?$/i.test(rel)) hasIac = true;
+    if (/(^|\/)k8s\/|(^|\/)kubernetes\/|\.ya?ml$/i.test(rel) && /(deploy|statefulset|cronjob|job|daemonset)/i.test(rel)) hasIac = true;
+    if (/(^|\/)\.checkov\.ya?ml$/i.test(rel)) hasConfig = true;
+  }
+  if (!hasIac || hasConfig) return [];
+  return [
+    createFinding({
+      tool: "checkov-run",
+      kind: "infrastructure.no-checkov-config",
+      severity: "P2",
+      file: "",
+      line: 0,
+      evidence: "Terraform / Dockerfile / K8s manifests present but no .checkov.yaml config",
+      rootCause: "Without Checkov (or equivalent IaC scanner), misconfigurations (public S3 buckets, privileged containers) ship to production.",
+      recommendedFix: "Add .checkov.yaml with a baseline skip-list and run `checkov -d .` in CI before apply.",
+      confidence: 0.6,
+    }),
+  ];
+}

package/src/agents/infrastructure/tools/drift-detect.js

@@ -0,0 +1,59 @@
+// drift-detect — flag checked-in tfstate files and missing drift jobs (#A21).
+
+import fsp from "node:fs/promises";
+import path from "node:path";
+
+import { createFinding, toPosix, walkRepoFiles } from "./base.js";
+
+export async function runDriftDetect({ rootPath } = {}) {
+  const resolvedRoot = path.resolve(String(rootPath || "."));
+  const findings = [];
+  let hasTf = false;
+  let hasDriftJob = false;
+
+  for await (const { fullPath, relativePath } of walkRepoFiles({ rootPath: resolvedRoot })) {
+    const rel = toPosix(relativePath);
+    if (/\.tf$/i.test(rel)) hasTf = true;
+    if (/\.tfstate$/i.test(rel)) {
+      findings.push(
+        createFinding({
+          tool: "drift-detect",
+          kind: "infrastructure.tfstate-committed",
+          severity: "P0",
+          file: rel,
+          line: 0,
+          evidence: `.tfstate checked into source: ${rel}`,
+          rootCause: "Terraform state files contain secrets (AWS creds, TLS keys, service account JSON) and should never be in source control.",
+          recommendedFix: "Delete the file, rotate any credentials it contained, and add *.tfstate to .gitignore. Move state to a remote backend (S3 + DynamoDB lock, GCS, Azure Blob).",
+          confidence: 0.98,
+        })
+      );
+    }
+    if (/(^|\/)\.github\/workflows\//.test(rel)) {
+      try {
+        const content = await fsp.readFile(fullPath, "utf-8");
+        if (/terraform\s+plan\s+-detailed-exitcode|drift[-_]detect|tfplan[-_]diff/i.test(content)) {
+          hasDriftJob = true;
+        }
+      } catch {
+        /* ignore */
+      }
+    }
+  }
+  if (hasTf && !hasDriftJob && !findings.some((f) => f.kind === "infrastructure.tfstate-committed")) {
+    findings.push(
+      createFinding({
+        tool: "drift-detect",
+        kind: "infrastructure.no-drift-job",
+        severity: "P3",
+        file: "",
+        line: 0,
+        evidence: "Terraform in repo but no scheduled drift-detection job in .github/workflows/",
+        rootCause: "Without periodic `terraform plan`, infrastructure drifts silently when someone changes things in the console.",
+        recommendedFix: "Add a scheduled workflow (daily is typical) that runs `terraform plan -detailed-exitcode` and opens an issue on non-zero exit.",
+        confidence: 0.5,
+      })
+    );
+  }
+  return findings;
+}

package/src/agents/infrastructure/tools/iam-least-priv-check.js

@@ -0,0 +1,78 @@
+// iam-least-priv-check — flag IAM wildcards (#A21).
+
+import fsp from "node:fs/promises";
+import path from "node:path";
+
+import { createFinding, findLineMatches, getLineContent, toPosix, walkRepoFiles } from "./base.js";
+
+const EXTENSIONS = new Set([".json", ".tf", ".yaml", ".yml"]);
+
+const WILDCARD_RULES = [
+  {
+    pattern: /"Action"\s*:\s*\[?\s*"\*"/,
+    kind: "infrastructure.iam-action-wildcard",
+    severity: "P1",
+    rootCause: "IAM policy grants Action:\"*\" — allows anything the principal can be used for. Privilege escalation path.",
+    recommendedFix: "Enumerate the specific actions required (e.g. \"s3:GetObject\", \"s3:PutObject\"). Use IAM Access Analyzer to derive a least-privilege policy from CloudTrail.",
+  },
+  {
+    pattern: /"Resource"\s*:\s*\[?\s*"\*"/,
+    kind: "infrastructure.iam-resource-wildcard",
+    severity: "P1",
+    rootCause: "IAM policy grants Resource:\"*\" — permission applies to every resource in every account the principal can reach.",
+    recommendedFix: "Scope Resource to specific ARNs (arn:aws:s3:::my-bucket/*). For actions that legitimately need all, document why.",
+  },
+  {
+    pattern: /action\s*=\s*\[[^\]]*"\*"/,
+    kind: "infrastructure.iam-action-wildcard",
+    severity: "P1",
+    rootCause: "Terraform IAM policy block grants action = [\"*\"] — same risk as the JSON form.",
+    recommendedFix: "Enumerate specific actions.",
+  },
+];
+
+export async function runIamLeastPrivCheck({ rootPath, files = null } = {}) {
+  const resolvedRoot = path.resolve(String(rootPath || "."));
+  const iterator =
+    Array.isArray(files) && files.length > 0
+      ? iterateExplicitFiles(resolvedRoot, files)
+      : walkRepoFiles({ rootPath: resolvedRoot, extensions: EXTENSIONS });
+
+  const findings = [];
+  for await (const { fullPath, relativePath } of iterator) {
+    let content;
+    try {
+      content = await fsp.readFile(fullPath, "utf-8");
+    } catch {
+      continue;
+    }
+    for (const rule of WILDCARD_RULES) {
+      for (const match of findLineMatches(content, rule.pattern)) {
+        findings.push(
+          createFinding({
+            tool: "iam-least-priv-check",
+            kind: rule.kind,
+            severity: rule.severity,
+            file: toPosix(relativePath),
+            line: match.line,
+            evidence: getLineContent(content, match.line),
+            rootCause: rule.rootCause,
+            recommendedFix: rule.recommendedFix,
+            confidence: 0.8,
+          })
+        );
+      }
+    }
+  }
+  return findings;
+}
+
+async function* iterateExplicitFiles(resolvedRoot, files) {
+  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, "/");
+    yield { fullPath, relativePath };
+  }
+}

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

@@ -0,0 +1,52 @@
+// Kat (infrastructure persona) domain-tool registry (#A21).
+
+import { runCheckovRun } from "./checkov-run.js";
+import { runDriftDetect } from "./drift-detect.js";
+import { runIamLeastPrivCheck } from "./iam-least-priv-check.js";
+import { runTflintRun } from "./tflint-run.js";
+
+export const INFRASTRUCTURE_TOOLS = Object.freeze({
+  "tflint-run": {
+    id: "tflint-run",
+    description: "Advise when Terraform files are present but no .tflint.hcl config.",
+    schema: { type: "object", properties: { rootPath: { type: "string" } } },
+    handler: runTflintRun,
+  },
+  "checkov-run": {
+    id: "checkov-run",
+    description: "Advise when IaC (Terraform / Dockerfile / K8s) is present but no .checkov.yaml config.",
+    schema: { type: "object", properties: { rootPath: { type: "string" } } },
+    handler: runCheckovRun,
+  },
+  "drift-detect": {
+    id: "drift-detect",
+    description: "Flag any .tfstate committed to source and advise when no scheduled drift-detection job exists.",
+    schema: { type: "object", properties: { rootPath: { type: "string" } } },
+    handler: runDriftDetect,
+  },
+  "iam-least-priv-check": {
+    id: "iam-least-priv-check",
+    description: "Flag Action:\"*\" / Resource:\"*\" wildcards in IAM policy JSON + Terraform.",
+    schema: { type: "object", properties: { rootPath: { type: "string" }, files: { type: "array", items: { type: "string" } } } },
+    handler: runIamLeastPrivCheck,
+  },
+});
+
+export const INFRASTRUCTURE_TOOL_IDS = Object.freeze(Object.keys(INFRASTRUCTURE_TOOLS));
+
+export async function dispatchInfrastructureTool(toolId, args = {}) {
+  const tool = INFRASTRUCTURE_TOOLS[toolId];
+  if (!tool) throw new Error(`Unknown infrastructure tool: ${toolId}`);
+  return tool.handler(args);
+}
+
+export async function runAllInfrastructureTools({ rootPath, files = null } = {}) {
+  const findings = [];
+  for (const toolId of INFRASTRUCTURE_TOOL_IDS) {
+    const out = await dispatchInfrastructureTool(toolId, { rootPath, files });
+    findings.push(...out);
+  }
+  return findings;
+}
+
+export { runCheckovRun, runDriftDetect, runIamLeastPrivCheck, runTflintRun };

package/src/agents/infrastructure/tools/tflint-run.js

@@ -0,0 +1,31 @@
+// tflint-run — advise when Terraform is present but tflint config is not (#A21).
+
+import fsp from "node:fs/promises";
+import path from "node:path";
+
+import { createFinding, toPosix, walkRepoFiles } from "./base.js";
+
+export async function runTflintRun({ rootPath } = {}) {
+  const resolvedRoot = path.resolve(String(rootPath || "."));
+  let hasTf = false;
+  let hasConfig = false;
+  for await (const { relativePath } of walkRepoFiles({ rootPath: resolvedRoot })) {
+    const rel = toPosix(relativePath);
+    if (/\.tf(vars)?$/i.test(rel)) hasTf = true;
+    if (/(^|\/)\.tflint\.hcl$/i.test(rel)) hasConfig = true;
+  }
+  if (!hasTf || hasConfig) return [];
+  return [
+    createFinding({
+      tool: "tflint-run",
+      kind: "infrastructure.no-tflint-config",
+      severity: "P2",
+      file: "",
+      line: 0,
+      evidence: "Terraform files present but no .tflint.hcl config",
+      rootCause: "Without tflint, Terraform lint issues (invalid attributes, deprecated syntax) make it to production plans.",
+      recommendedFix: "Add .tflint.hcl and run tflint in CI before every terraform plan.",
+      confidence: 0.65,
+    }),
+  ];
+}

package/src/agents/jules/loop.js

@@ -1,6 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { createMultiProviderApiClient } from "../../ai/client.js";
 import { evaluateBudget } from "../../cost/budget.js";
+import { estimateTokens } from "../../cost/tokenizer.js";
 import { dispatchTool, createAgentContext, BudgetExhaustedError } from "./tools/dispatch.js";
 import { JULES_DEFINITION } from "./config/definition.js";
 import { shouldSpawnSubAgents, runJulesSwarm } from "./swarm/orchestrator.js";
@@ -223,8 +224,9 @@ export async function* julesAuditLoop(config) {
     }
 
     const responseText = response.text || "";
-    ctx.usage.outputTokens += Math.ceil(responseText.length / 4);
-    ctx.usage.costUsd += (Math.ceil(responseText.length / 4) / 1_000_000) * 15;
+    const responseTokens = estimateTokens(responseText, { provider: "anthropic" });
+    ctx.usage.outputTokens += responseTokens;
+    ctx.usage.costUsd += (responseTokens / 1_000_000) * 15;
 
     yield emit("reasoning", {
       phase: "deep_analysis",
@@ -337,8 +339,9 @@ export async function* julesAuditLoop(config) {
         });
 
         const reconcileText = reconcileResponse.text || "";
-        ctx.usage.outputTokens += Math.ceil(reconcileText.length / 4);
-        ctx.usage.costUsd += (Math.ceil(reconcileText.length / 4) / 1_000_000) * 15;
+        const reconcileTokens = estimateTokens(reconcileText, { provider: "anthropic" });
+        ctx.usage.outputTokens += reconcileTokens;
+        ctx.usage.costUsd += (reconcileTokens / 1_000_000) * 15;
 
         yield emit("reasoning", { phase: "reconciliation", summary: reconcileText.slice(0, 200) });
 

package/src/agents/jules/swarm/sub-agent.js

@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 import { createAgentContext, dispatchTool, isReadOnlyTool, BudgetExhaustedError } from "../tools/dispatch.js";
 import { createMultiProviderApiClient } from "../../../ai/client.js";
 import { createAgentEvent } from "../../../events/schema.js";
+import { estimateTokens as estimateTokensProviderAware } from "../../../cost/tokenizer.js";
 
 /**
  * JulesSubAgent — lightweight isolated agent for parallel audit work.
@@ -294,7 +295,10 @@ function formatToolResults(results) {
 }
 
 function estimateTokens(text) {
-  return Math.ceil((text || "").length / 4);
+  // Provider-aware heuristic (#A12). Jules defaults to Claude Sonnet so we
+  // bias toward the Anthropic tokenizer ratios; callers outside Jules pay
+  // the same cost since the routing goes through tracker.js anyway.
+  return estimateTokensProviderAware(text, { provider: "anthropic" });
 }
 
 function estimateCost(text) {

package/src/agents/jules/tools/auth-audit.js

@@ -504,7 +504,16 @@ function persistProviderBreakerState(nowMs = Date.now()) {
       })),
     };
     const tmpPath = `${statePath}.${process.pid}.tmp`;
-    fs.writeFileSync(tmpPath, JSON.stringify(payload), "utf-8");
+    // Write with 0600 so the breaker state file (which can log provider
+    // identifiers and failure modes) is not world-readable on multi-user
+    // machines. renameSync preserves mode.
+    fs.writeFileSync(tmpPath, JSON.stringify(payload), { encoding: "utf-8", mode: 0o600 });
+    try {
+      fs.chmodSync(tmpPath, 0o600);
+    } catch {
+      // Windows FAT volumes may not honor chmod; mode from writeFileSync
+      // still applies on POSIX.
+    }
     fs.renameSync(tmpPath, statePath);
   } catch {
     // Persistence is best-effort; in-memory safeguards remain active.

package/src/agents/mode.js

@@ -0,0 +1,113 @@
+// Persona mode selector (#A27, spec §Phase 5 / PR #A27).
+//
+// The persona envelope (PR #A8) is identical between audit and code-gen
+// modes. The only per-mode variation:
+//   1. The allowed-tools subset. Audit gets read-only tools + domain scans.
+//      Codegen gets the read-only tools PLUS file-edit + shell (sandboxed)
+//      so the persona can apply fixes.
+//   2. The system-prompt suffix. Audit mode appends "Emit findings only.
+//      Do not modify files." Codegen mode appends "Apply fixes as minimal
+//      edits with clear commit-message summaries."
+//
+// This module is the single source of truth for those two deltas. Every
+// caller that spawns a persona does so through `buildPersonaConfigForMode`;
+// same persona, same domain tools, same budget knobs — only the two deltas
+// change.
+
+// 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
+// refactor can swap these for real imports — the tool-id strings are
+// stable anyway.
+
+export const PERSONA_MODES = Object.freeze(["audit", "codegen"]);
+
+// Read-only tool ids that exist in every persona — the audit baseline.
+// When a persona is invoked in `audit` mode, it gets the union of its own
+// domain tools and these shared scanners. Code-gen mode adds the edit /
+// shell tools below on top.
+const READONLY_BASELINE = Object.freeze([
+  "FileRead",
+  "Grep",
+  "Glob",
+]);
+
+const CODEGEN_EXTRA_TOOLS = Object.freeze([
+  "FileEdit",
+  "Shell",
+]);
+
+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"]),
+  "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"]),
+  "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"]),
+  "supply-chain": Object.freeze(["attestation-check", "lockfile-integrity", "package-verify", "sbom-diff"]),
+  "testing": Object.freeze(["coverage-gap", "flake-detect", "mutation-test", "snapshot-diff"]),
+});
+
+const MODE_PROMPT_SUFFIXES = Object.freeze({
+  audit: [
+    "",
+    "You are operating in AUDIT mode.",
+    "Emit findings only. Do not modify files. Your output is structured JSON that downstream tooling will rank, dedupe, and present to the reviewer.",
+    "When you call a domain tool, the tool writes Finding objects. You decide which of those to elevate into your final report and how to prioritize them.",
+  ].join("\n"),
+  codegen: [
+    "",
+    "You are operating in CODE-GEN mode.",
+    "Apply fixes as minimal, reviewable edits. Every file you touch must compile / parse; every change should include a one-line commit-message-style rationale.",
+    "When you call a domain tool, treat the resulting Finding list as the work queue. Your output is a set of file edits plus an explanation of what you did and what you deliberately left for a human.",
+  ].join("\n"),
+});
+
+export function normalizePersonaMode(mode) {
+  const normalized = String(mode || "").trim().toLowerCase();
+  if (PERSONA_MODES.includes(normalized)) {
+    return normalized;
+  }
+  return "audit";
+}
+
+// Return { mode, allowedTools, promptSuffix, personaId } for a persona in
+// the requested mode. The only values that depend on mode are allowedTools
+// and promptSuffix; everything else (budget, identity, system prompt body)
+// is supplied by the persona's own definition.
+export function buildPersonaConfigForMode(personaId, mode) {
+  const normalizedMode = normalizePersonaMode(mode);
+  const normalizedPersona = String(personaId || "").trim().toLowerCase();
+  const domainTools = DOMAIN_TOOL_IDS_BY_PERSONA[normalizedPersona] || [];
+
+  const allowedTools = new Set([...READONLY_BASELINE, ...domainTools]);
+  if (normalizedMode === "codegen") {
+    for (const tool of CODEGEN_EXTRA_TOOLS) {
+      allowedTools.add(tool);
+    }
+  }
+  return {
+    personaId: normalizedPersona,
+    mode: normalizedMode,
+    allowedTools: Array.from(allowedTools),
+    promptSuffix: MODE_PROMPT_SUFFIXES[normalizedMode],
+  };
+}
+
+// Quick boolean for callers that just want "can this mode write files?"
+export function modeAllowsWrites(mode) {
+  return normalizePersonaMode(mode) === "codegen";
+}
+
+// Which personas does the mode selector recognize? Useful for tests /
+// diagnostics — callers can detect a typo in a persona id before they
+// dispatch.
+export function listKnownPersonaIds() {
+  return Object.keys(DOMAIN_TOOL_IDS_BY_PERSONA).slice().sort();
+}
+
+export { READONLY_BASELINE, CODEGEN_EXTRA_TOOLS, MODE_PROMPT_SUFFIXES };

package/src/agents/observability/index.js

@@ -0,0 +1,12 @@
+// Sofia (observability persona) — barrel export (#A20).
+
+export {
+  OBSERVABILITY_TOOLS,
+  OBSERVABILITY_TOOL_IDS,
+  dispatchObservabilityTool,
+  runAllObservabilityTools,
+  runAlertAudit,
+  runDashboardGap,
+  runLogSchemaCheck,
+  runSpanCoverage,
+} from "./tools/index.js";