@kal-elsam/kairo-runtime 0.15.0 → 0.17.0

package/src/global/conversation/codex-sandbox.js

@@ -0,0 +1,230 @@
+// Real OS-level filesystem confinement for the Codex CLI, used ONLY for
+// Bootstrap Analysis (conversation/service.js's runBootstrapAnalysis) —
+// general ASK (intelligence/quick-ask.js's askProvider) keeps using
+// Codex's own `--sandbox read-only`, which is NOT read-confining (see
+// sanitized-snapshot.js's header: it blocks writes only, a real absolute
+// path outside cwd is still readable). This module closes that specific
+// gap with an OS-enforced boundary instead of relying on redaction alone.
+//
+// Mechanism: wrap `codex exec` in an external `sandbox-exec` (macOS SBPL)
+// profile, and pass Codex `--dangerously-bypass-approvals-and-sandbox` so
+// Codex's OWN internal sandboxing is off — Codex's `--sandbox read-only`
+// internally re-invokes sandbox-exec per tool call, and nesting an outer
+// sandbox-exec around that breaks every tool call outright (verified
+// empirically: every Codex tool invocation failed with a sandbox_apply
+// error). With Codex's own sandbox disabled, the external profile becomes
+// the sole enforcement layer.
+//
+// Empirically proven, not assumed (see engram memory
+// "Codex sandbox-exec confinement proven for Bootstrap Analyst
+// isolation"): under this exact wrapper, a real `codex exec` run reads a
+// file inside the confined root correctly, and is denied
+// ("Operation not permitted") reading a file outside it via an absolute
+// path.
+//
+// HONEST LIMIT: SBPL applies uniformly to a sandboxed process and every
+// child it execs — there is no SBPL primitive that grants Codex's own
+// process read/write access to CODEX_HOME while denying that same access
+// to tools Codex spawns. Both are required: Codex fails hard ("failed to
+// initialize in-process app-server client: Operation not permitted",
+// verified empirically) without WRITE access to CODEX_HOME too, not just
+// read. So CODEX_HOME is fully readable and writable by the whole
+// confined tree, not just Codex's top-level process. This does not
+// weaken the actual isolation goal (nothing in that tree can escape the
+// snapshot boundary either way) — it only means a per-process auth/tool
+// split, as asked for in review, cannot be built on sandbox-exec alone.
+//
+// macOS only. Any other platform returns { available: false }; callers
+// must fail closed (isolation_unavailable) and never silently fall back
+// to Codex's own non-confining --sandbox read-only for Bootstrap Analysis.
+
+import { spawn as defaultSpawn } from "node:child_process";
+import { access, mkdtemp, readFile, realpath, rm, writeFile } from "node:fs/promises";
+import { constants as fsConstants } from "node:fs";
+import { tmpdir, homedir } from "node:os";
+import { join } from "node:path";
+
+const SANDBOX_EXEC_PATH = "/usr/bin/sandbox-exec";
+
+// Bootstrap Analysis is a real project investigation, not a quick
+// question — mirrors service.js's own BOOTSTRAP_ANALYST_TIMEOUT_MS.
+const DEFAULT_TIMEOUT_MS = 180_000;
+
+const SAFE_ENV_KEYS = Object.freeze([
+  "PATH", "HOME", "USER", "LOGNAME", "SHELL", "LANG", "LC_ALL", "LC_CTYPE",
+  "TMPDIR", "TERM", "CODEX_HOME", "HTTP_PROXY", "HTTPS_PROXY", "NO_PROXY",
+  "http_proxy", "https_proxy", "no_proxy", "NODE_EXTRA_CA_CERTS"
+]);
+
+function buildSandboxedCodexEnv(sourceEnv = process.env) {
+  const env = Object.create(null);
+  for (const key of SAFE_ENV_KEYS) {
+    if (sourceEnv[key] != null && sourceEnv[key] !== "") env[key] = sourceEnv[key];
+  }
+  return env;
+}
+
+function unknown(error) {
+  return { status: "error", answer: null, error: String(error) };
+}
+
+export async function isCodexSandboxSupported(deps = {}) {
+  if ((deps.platform ?? process.platform) !== "darwin") return false;
+  try {
+    await (deps.access ?? access)(SANDBOX_EXEC_PATH, fsConstants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Real, checkable isolation status for Codex — never a hardcoded claim.
+ * `boundaryVerified` reflects that the sandbox-exec mechanism itself has
+ * been empirically proven (canary-denial test) on this platform, not that
+ * this specific call was independently re-verified.
+ */
+export async function getCodexIsolationStatus(deps = {}) {
+  const available = await isCodexSandboxSupported(deps);
+  return {
+    available,
+    platform: deps.platform ?? process.platform,
+    boundaryVerified: available,
+    reason: available
+      ? null
+      : "OS-level read confinement for Codex (sandbox-exec) is only implemented for macOS; Codex is not eligible for isolated Bootstrap Analysis on this platform."
+  };
+}
+
+async function resolvedForms(path, deps) {
+  const forms = new Set([path]);
+  try {
+    forms.add(await (deps.realpath ?? realpath)(path));
+  } catch {
+    // path may not exist yet — the literal form alone still covers it
+  }
+  return [...forms];
+}
+
+function subpathRules(paths) {
+  return paths.map((p) => `  (subpath "${p}")`).join("\n");
+}
+
+/**
+ * Builds a real SBPL profile confining reads/writes to `snapshotRoot` (the
+ * sanitized-snapshot.js temp copy the analyst investigates) plus
+ * `codexHome` (Codex's own auth config — without it the CLI can't
+ * authenticate at all) and the minimal system paths Codex needs to run.
+ * Resolves both the given path and its real path (handles macOS's
+ * /tmp -> /private/tmp and /var -> /private/var symlinks automatically,
+ * rather than hardcoding either form).
+ */
+export async function buildCodexSandboxProfile({ snapshotRoot, codexHome = join(homedir(), ".codex") }, deps = {}) {
+  const snapshotForms = await resolvedForms(snapshotRoot, deps);
+  const codexHomeForms = await resolvedForms(codexHome, deps);
+  const readableExtra = [
+    "/usr", "/System", "/bin", "/sbin", "/private/var/db/dyld", "/Library", "/opt", "/private/etc"
+  ];
+  return `(version 1)
+(deny default)
+(allow process-fork)
+(allow process-exec)
+(allow file-read-metadata (subpath "/"))
+(allow file-read-data (literal "/"))
+(allow file-read*
+${subpathRules([...snapshotForms, ...codexHomeForms, ...readableExtra])}
+  (literal "/dev/null")
+  (literal "/dev/urandom")
+  (literal "/dev/tty"))
+(allow file-write*
+${subpathRules([...snapshotForms, ...codexHomeForms, "/private/var/folders", "/private/tmp"])})
+(allow file-read-metadata (subpath "/private/var/folders"))
+(allow sysctl-read)
+(allow mach-lookup)
+(allow signal (target self))
+(allow network*)
+(allow system-socket)
+`;
+}
+
+/**
+ * Runs a real, OS-sandboxed Codex Bootstrap Analysis question. The ONLY
+ * intended caller is conversation/service.js's runBootstrapAnalysis.
+ * Fails closed with `status: "error", error: "isolation_unavailable"`
+ * (never a silent fallback to Codex's own non-confining --sandbox
+ * read-only) when this platform has no verified boundary.
+ * @param {object} args
+ * @param {string} args.question
+ * @param {string|null} [args.model]
+ * @param {string} args.snapshotRoot - sanitized-snapshot.js's temp copy
+ * @param {string} [args.codexHome]
+ */
+export async function runCodexSandboxedBootstrap({
+  question, model = null, snapshotRoot, codexHome = join(homedir(), ".codex"),
+  spawn = defaultSpawn, timeoutMs = DEFAULT_TIMEOUT_MS, sourceEnv = process.env, deps = {}
+}) {
+  const isolation = await getCodexIsolationStatus(deps);
+  if (!isolation.available) {
+    return { status: "error", answer: null, error: "isolation_unavailable", isolation };
+  }
+
+  let workDir;
+  try {
+    workDir = await (deps.mkdtemp ?? mkdtemp)(join(tmpdir(), "kairo-codex-sandbox-"));
+  } catch (error) {
+    return { ...unknown(error?.message ?? error), isolation };
+  }
+  const profilePath = join(workDir, "bootstrap.sb");
+  const outFile = join(workDir, "answer.txt");
+
+  try {
+    const profile = await buildCodexSandboxProfile({ snapshotRoot, codexHome }, deps);
+    await (deps.writeFile ?? writeFile)(profilePath, profile, "utf8");
+
+    // --skip-git-repo-check: snapshotRoot deliberately excludes .git.
+    // --ephemeral: no session files persisted to disk for this run.
+    // --ignore-user-config: doesn't load $CODEX_HOME/config.toml (auth
+    // itself still resolves via CODEX_HOME, per `codex exec --help`).
+    const args = [
+      "-f", profilePath, "codex", "exec",
+      "--dangerously-bypass-approvals-and-sandbox",
+      "--skip-git-repo-check", "--ephemeral", "--ignore-user-config",
+      "-o", outFile
+    ];
+    if (model) args.push("--model", model);
+    args.push(question);
+
+    const env = buildSandboxedCodexEnv(sourceEnv);
+    const result = await new Promise((resolve) => {
+      let child;
+      try {
+        child = spawn("sandbox-exec", args, { cwd: snapshotRoot, env, stdio: ["ignore", "pipe", "pipe"] });
+      } catch (error) {
+        resolve(unknown(error?.message ?? error));
+        return;
+      }
+      let finished = false;
+      const timer = setTimeout(() => finish(unknown("sandboxed codex exec timed out")), timeoutMs);
+      function finish(res) {
+        if (finished) return;
+        finished = true;
+        clearTimeout(timer);
+        try { child.kill?.(); } catch { /* best effort */ }
+        resolve(res);
+      }
+      child.once?.("error", (error) => finish(unknown(error?.message ?? error)));
+      child.once?.("close", async () => {
+        try {
+          const text = (await (deps.readFile ?? readFile)(outFile, "utf8")).trim();
+          if (!text) return finish(unknown("sandboxed codex exec produced no final message"));
+          finish({ status: "answered", answer: text, error: null });
+        } catch (error) {
+          finish(unknown(error?.message ?? error));
+        }
+      });
+    });
+    return { ...result, isolation };
+  } finally {
+    await (deps.rm ?? rm)(workDir, { recursive: true, force: true }).catch(() => {});
+  }
+}

package/src/global/conversation/cursor-sandbox.js

@@ -0,0 +1,215 @@
+// Real OS-level filesystem confinement for the Cursor CLI (cursor-agent),
+// used ONLY for Bootstrap Analysis, mirroring codex-sandbox.js exactly —
+// general ASK never routes Cursor through this module.
+//
+// Empirically proven necessary AND sufficient, not assumed: Cursor's own
+// `--sandbox enabled` (documented in `cursor-agent --help` as "Explicitly
+// enable or disable sandbox mode") does NOT confine file reads to
+// --workspace — a real absolute-path read outside the workspace
+// succeeded and disclosed real content under `--sandbox enabled` alone.
+// The same external sandbox-exec wrapper approach that closed this gap
+// for Codex (codex-sandbox.js) was then independently canary-tested
+// against the real cursor-agent CLI and DOES hold: wrapping `cursor-agent`
+// in an external macOS sandbox-exec profile, with Cursor's own internal
+// sandbox disabled (`--sandbox disabled`, so only the external wrapper
+// enforces anything — avoids any risk of the kind of nested-sandbox
+// conflict that broke every Codex tool call when both layers tried to
+// sandbox at once), produces a real, held boundary: an in-bounds read
+// succeeds, an out-of-bounds absolute-path read is denied
+// ("Permission denied", not a model claim in prose).
+//
+// Two real gotchas found only by testing the ACTUAL cursor-agent binary
+// (not assumed from Codex's profile):
+//  1. cursor-agent's real binary lives under `~/.local` (a wrapper script
+//     at ~/.local/bin/cursor-agent execs the real binary under
+//     ~/.local/share/cursor-agent/versions/...) — that whole tree must be
+//     readable+executable, or the CLI can't even launch.
+//  2. cursor-agent's stored auth ("Authentication tokens stored
+//     securely") lives in the macOS Keychain, not a plain file under its
+//     config home — ~/Library/Keychains must be read+write accessible or
+//     every real invocation fails with "Authentication required" even
+//     though the session is genuinely logged in. The wrapper script also
+//     writes to /dev/null, which needs explicit file-write access (unlike
+//     Codex's profile, which never needed it).
+//
+// A workspace cursor-agent has never seen before triggers an interactive
+// "Workspace Trust Required" prompt that blocks non-interactive use —
+// `--trust` is required for automation, safe here because snapshotRoot is
+// always Kairo's own freshly-generated temp directory, never an
+// arbitrary user-chosen one (same category of bypass as Codex's
+// --skip-git-repo-check for a snapshot that deliberately excludes .git).
+
+import { spawn as defaultSpawn } from "node:child_process";
+import { access, mkdtemp, realpath, rm, writeFile } from "node:fs/promises";
+import { constants as fsConstants } from "node:fs";
+import { tmpdir, homedir } from "node:os";
+import { join } from "node:path";
+
+const SANDBOX_EXEC_PATH = "/usr/bin/sandbox-exec";
+const DEFAULT_TIMEOUT_MS = 180_000;
+
+const SAFE_ENV_KEYS = Object.freeze([
+  "PATH", "HOME", "USER", "LOGNAME", "SHELL", "LANG", "LC_ALL", "LC_CTYPE",
+  "TMPDIR", "TERM", "HTTP_PROXY", "HTTPS_PROXY", "NO_PROXY",
+  "http_proxy", "https_proxy", "no_proxy", "NODE_EXTRA_CA_CERTS"
+]);
+
+function buildSandboxedCursorEnv(sourceEnv = process.env) {
+  const env = Object.create(null);
+  for (const key of SAFE_ENV_KEYS) {
+    if (sourceEnv[key] != null && sourceEnv[key] !== "") env[key] = sourceEnv[key];
+  }
+  return env;
+}
+
+function unknown(error) {
+  return { status: "error", answer: null, error: String(error) };
+}
+
+export async function isCursorSandboxSupported(deps = {}) {
+  if ((deps.platform ?? process.platform) !== "darwin") return false;
+  try {
+    await (deps.access ?? access)(SANDBOX_EXEC_PATH, fsConstants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function getCursorIsolationStatus(deps = {}) {
+  const available = await isCursorSandboxSupported(deps);
+  return {
+    available,
+    platform: deps.platform ?? process.platform,
+    boundaryVerified: available,
+    reason: available
+      ? null
+      : "OS-level read confinement for Cursor (sandbox-exec) is only implemented for macOS; Cursor is not eligible for isolated Bootstrap Analysis on this platform."
+  };
+}
+
+async function resolvedForms(path, deps) {
+  const forms = new Set([path]);
+  try {
+    forms.add(await (deps.realpath ?? realpath)(path));
+  } catch {
+    // fine — the literal form alone still covers it
+  }
+  return [...forms];
+}
+
+function subpathRules(paths) {
+  return paths.map((p) => `  (subpath "${p}")`).join("\n");
+}
+
+export async function buildCursorSandboxProfile({
+  snapshotRoot,
+  cursorHome = join(homedir(), ".cursor"),
+  cursorLocalHome = join(homedir(), ".local"),
+  keychainsHome = join(homedir(), "Library", "Keychains")
+}, deps = {}) {
+  const snapshotForms = await resolvedForms(snapshotRoot, deps);
+  const cursorHomeForms = await resolvedForms(cursorHome, deps);
+  const cursorLocalForms = await resolvedForms(cursorLocalHome, deps);
+  const keychainsForms = await resolvedForms(keychainsHome, deps);
+  const readableExtra = [
+    "/usr", "/System", "/bin", "/sbin", "/private/var/db/dyld", "/Library", "/opt", "/private/etc"
+  ];
+  return `(version 1)
+(deny default)
+(allow process-fork)
+(allow process-exec)
+(allow file-read-metadata (subpath "/"))
+(allow file-read-data (literal "/"))
+(allow file-read*
+${subpathRules([...snapshotForms, ...cursorHomeForms, ...cursorLocalForms, ...keychainsForms, ...readableExtra])}
+  (literal "/dev/null")
+  (literal "/dev/urandom")
+  (literal "/dev/tty"))
+(allow file-write*
+  (literal "/dev/null")
+${subpathRules([...snapshotForms, ...cursorHomeForms, ...keychainsForms, "/private/var/folders", "/private/tmp"])})
+(allow file-read-metadata (subpath "/private/var/folders"))
+(allow sysctl-read)
+(allow mach-lookup)
+(allow signal (target self))
+(allow network*)
+(allow system-socket)
+`;
+}
+
+/**
+ * Runs a real, OS-sandboxed Cursor Bootstrap Analysis question. The ONLY
+ * intended caller is bootstrap-analyzer-adapters.js's Cursor adapter.
+ * Fails closed with `status: "error", error: "isolation_unavailable"`
+ * (never a silent fallback to Cursor's own non-confining --sandbox
+ * enabled) when this platform has no verified boundary.
+ * @param {object} args
+ * @param {string} args.question
+ * @param {string|null} [args.model] - omit (or pass null) for Cursor Auto
+ * @param {string} args.snapshotRoot
+ */
+export async function runCursorSandboxedBootstrap({
+  question, model = null, snapshotRoot,
+  cursorHome = join(homedir(), ".cursor"), cursorLocalHome = join(homedir(), ".local"),
+  keychainsHome = join(homedir(), "Library", "Keychains"),
+  spawn = defaultSpawn, timeoutMs = DEFAULT_TIMEOUT_MS, sourceEnv = process.env, deps = {}
+}) {
+  const isolation = await getCursorIsolationStatus(deps);
+  if (!isolation.available) {
+    return { status: "error", answer: null, error: "isolation_unavailable", isolation };
+  }
+
+  let workDir;
+  try {
+    workDir = await (deps.mkdtemp ?? mkdtemp)(join(tmpdir(), "kairo-cursor-sandbox-"));
+  } catch (error) {
+    return { ...unknown(error?.message ?? error), isolation };
+  }
+  const profilePath = join(workDir, "bootstrap.sb");
+
+  try {
+    const profile = await buildCursorSandboxProfile({ snapshotRoot, cursorHome, cursorLocalHome, keychainsHome }, deps);
+    await (deps.writeFile ?? writeFile)(profilePath, profile, "utf8");
+
+    const args = [
+      "-f", profilePath, "cursor-agent", "-p", question,
+      "--output-format", "json", "--mode", "ask", "--sandbox", "disabled",
+      "--workspace", snapshotRoot, "--trust"
+    ];
+    if (model) args.push("--model", model);
+
+    const env = buildSandboxedCursorEnv(sourceEnv);
+    const result = await new Promise((resolve) => {
+      let child;
+      try {
+        child = spawn("sandbox-exec", args, { cwd: snapshotRoot, env, stdio: ["ignore", "pipe", "pipe"] });
+      } catch (error) {
+        resolve(unknown(error?.message ?? error));
+        return;
+      }
+      let stdout = "";
+      let finished = false;
+      const timer = setTimeout(() => finish(unknown("sandboxed cursor-agent -p timed out")), timeoutMs);
+      function finish(res) {
+        if (finished) return;
+        finished = true;
+        clearTimeout(timer);
+        try { child.kill?.(); } catch { /* best effort */ }
+        resolve(res);
+      }
+      child.stdout?.on("data", (chunk) => { stdout += chunk; });
+      child.once?.("error", (error) => finish(unknown(error?.message ?? error)));
+      child.once?.("close", () => {
+        let parsed;
+        try { parsed = JSON.parse(stdout); } catch { return finish(unknown("malformed JSON from sandboxed cursor-agent -p")); }
+        const answer = parsed?.result ?? parsed?.text ?? parsed?.message ?? null;
+        if (typeof answer !== "string") return finish(unknown("no result text in sandboxed cursor-agent -p response"));
+        finish({ status: "answered", answer, error: null });
+      });
+    });
+    return { ...result, isolation };
+  } finally {
+    await (deps.rm ?? rm)(workDir, { recursive: true, force: true }).catch(() => {});
+  }
+}

package/src/global/conversation/project-analysis.js

@@ -0,0 +1,204 @@
+// The real Bootstrap Analyst step: a chosen real model actually reads the
+// project (via askProvider — the same real, read-only, no-file-write path
+// ASK mode already uses; never a new execution surface) and returns a
+// structured ProjectAnalysis, validated against a real schema before
+// anything downstream trusts it. An invalid or unparseable response is
+// rejected outright — no ProjectStrategy is ever built from it.
+//
+// The deterministic step (deriveRoleRequirements) then turns that
+// validated analysis into real RoleNeed[] — sanitized against the known
+// capability vocabulary, unioned with the project's own mechanical floor
+// (real test/lint/build commands, already computed by project-profile.js)
+// so a thin or low-confidence analysis can never leave the project with
+// literally zero real role requirements.
+
+export const PROJECT_ANALYSIS_SCHEMA = "kairo.project-analysis/v1";
+
+// The only real capabilities the scoring engine (capability-scoring.js)
+// actually understands — any other token in the analyst's own output is
+// dropped rather than trusted, so a hallucinated capability name can never
+// corrupt scoring (worst case: a role with zero recognized capabilities
+// simply never activates — fails closed, not open).
+const KNOWN_CAPABILITIES = new Set(["reasoning", "coding", "terminalExecution", "softwareExecution", "instructionFollowing"]);
+const KNOWN_ROLES = new Set(["Explorer", "Architect", "Builder", "Debugger", "Tester", "Reviewer"]);
+
+/**
+ * The real, limited context package the Bootstrap Analyst receives — never
+ * the whole repo dumped in, and never anything the analyst could mistake
+ * for permission to write: just what project-profile.js already collected
+ * read-only (stack, real build/test/lint commands, real git hotspots,
+ * real workflow docs present). The analyst can still read further real
+ * files on its own (it runs inside `cwd`), but this is its starting brief.
+ * @param {object} profile - computeProjectProfile() result
+ * @returns {string}
+ */
+export function buildAnalystPrompt(profile) {
+  const lines = [
+    "You are Kairo's Bootstrap Analyst. Investigate this real project, READ-ONLY — never propose or make any file change.",
+    "You may read real files in this working directory to inform your answer, but do not modify anything.",
+    "",
+    "## Known real evidence",
+    `Project: ${profile.projectName}`,
+    `Stack: ${profile.stack.join(", ") || "unknown"}`,
+    `Architecture pattern: ${profile.architecture?.pattern ?? "unknown"}`,
+    `Build command: ${profile.quality.buildCommand ?? "none detected"}`,
+    `Test command: ${profile.quality.testCommand ?? "none detected"}`,
+    `Lint/typecheck: ${profile.quality.lintCommand ?? profile.quality.typeCheckCommand ?? "none detected"}`,
+    `Real git hotspots (most-changed files, last 90 days): ${profile.hotspots.map((h) => h.path).join(", ") || "none"}`,
+    `Workflow docs present: ${profile.workflowCapabilities.join(", ") || "none"}`,
+    `Known risks: ${profile.risks.map((r) => r.detail).join("; ") || "none"}`,
+    "",
+    "## Task",
+    "Respond with ONLY one JSON object (no prose, no markdown fences) matching exactly this shape:",
+    JSON.stringify({
+      architectureTraits: ["string"], complexitySignals: ["string"], criticalAreas: ["string"],
+      contextNeeds: ["string"], workflowNeeds: ["string"],
+      recommendedRoleNeeds: [{
+        role: "Explorer|Architect|Builder|Debugger|Tester|Reviewer",
+        capabilities: ["reasoning|coding|terminalExecution|softwareExecution|instructionFollowing"],
+        reason: "string", evidence: ["real file path you actually read that supports THIS role need"]
+      }],
+      uncertainties: ["string"], evidenceReferences: ["string"]
+    }, null, 2),
+    "",
+    "Every field must reflect something you actually observed in this project — never invent a trait, risk, or role need you have no real evidence for. If you're not sure about something, put it in `uncertainties` instead of guessing.",
+    "Each recommendedRoleNeeds entry's own `evidence` must list the real file path(s) you actually read that support THAT SPECIFIC role need — a role need with no real evidence of its own will be discarded, even if other fields in this response are well-supported."
+  ];
+  return lines.join("\n");
+}
+
+/**
+ * Extracts and validates a ProjectAnalysis from the analyst's raw text
+ * response. Fails closed: any parse failure or shape mismatch returns
+ * `{valid: false}`, never a partially-trusted guess.
+ * @param {string} rawText
+ * @returns {{valid: true, analysis: object}|{valid: false, error: string}}
+ */
+export function parseProjectAnalysis(rawText) {
+  const match = String(rawText ?? "").match(/\{[\s\S]*\}/);
+  if (!match) return { valid: false, error: "No JSON object found in the analyst's response." };
+  let parsed;
+  try {
+    parsed = JSON.parse(match[0]);
+  } catch (error) {
+    return { valid: false, error: `Analyst response is not valid JSON: ${error.message}` };
+  }
+  const arrayFields = ["architectureTraits", "complexitySignals", "criticalAreas", "contextNeeds", "workflowNeeds", "uncertainties", "evidenceReferences"];
+  for (const field of arrayFields) {
+    if (!Array.isArray(parsed[field])) return { valid: false, error: `Missing or invalid real array field "${field}".` };
+  }
+  if (!Array.isArray(parsed.recommendedRoleNeeds)) return { valid: false, error: 'Missing or invalid real array field "recommendedRoleNeeds".' };
+  for (const need of parsed.recommendedRoleNeeds) {
+    if (typeof need?.role !== "string" || !Array.isArray(need.capabilities)) {
+      return { valid: false, error: "Each recommendedRoleNeeds entry needs a real role (string) and capabilities (array)." };
+    }
+  }
+  return {
+    valid: true,
+    analysis: {
+      schema: PROJECT_ANALYSIS_SCHEMA,
+      architectureTraits: parsed.architectureTraits.map(String),
+      complexitySignals: parsed.complexitySignals.map(String),
+      criticalAreas: parsed.criticalAreas.map(String),
+      contextNeeds: parsed.contextNeeds.map(String),
+      workflowNeeds: parsed.workflowNeeds.map(String),
+      // `evidence` defaults to an empty array when the analyst omits it —
+      // never invented, and a role need with no evidence of its own
+      // fails the real per-entry gate in deriveRoleRequirements below,
+      // exactly as if it had cited nothing real.
+      recommendedRoleNeeds: parsed.recommendedRoleNeeds.map((need) => ({
+        role: String(need.role), capabilities: need.capabilities.map(String),
+        reason: typeof need.reason === "string" ? need.reason : null,
+        evidence: Array.isArray(need.evidence) ? need.evidence.map(String) : []
+      })),
+      uncertainties: parsed.uncertainties.map(String),
+      evidenceReferences: parsed.evidenceReferences.map(String)
+    }
+  };
+}
+
+function normalizePath(path) {
+  return String(path ?? "").trim().replace(/^\.\//, "").replace(/\/+$/, "");
+}
+
+/**
+ * Whether a single cited path corresponds to a real file the analyst
+ * actually had access to (the sanitized snapshot's real copied-file
+ * list) — a citation to a path that was never even in the snapshot is a
+ * real, checkable signal the analyst may be describing exploration it
+ * didn't actually do, not evidence it observed. Matching is real-path-
+ * based but tolerant of how a model might phrase a reference (a leading
+ * "./", or citing just the tail of a longer real path) — an exact
+ * string mismatch alone never disqualifies a real match.
+ * @param {string} reference
+ * @param {string[]} realFilePaths
+ * @returns {boolean}
+ */
+function referenceMatchesRealFile(reference, realFilePaths) {
+  const ref = normalizePath(reference);
+  if (!ref) return false;
+  return realFilePaths.some((path) => path === ref || path.endsWith(`/${ref}`) || ref.endsWith(`/${path}`));
+}
+
+/**
+ * Checks which of a list of citations correspond to a real file — used
+ * both for the analysis's own top-level evidenceReferences (informational)
+ * and, per-entry, for each recommendedRoleNeeds' own `evidence` (see
+ * deriveRoleRequirements, which is the one that actually gates on this).
+ * @param {string[]} references
+ * @param {string[]} realFilePaths - the sanitized snapshot's real copiedFiles
+ * @returns {{verified: string[], unverified: string[]}}
+ */
+export function validateReferences(references, realFilePaths) {
+  const real = realFilePaths.map(normalizePath);
+  const verified = [];
+  const unverified = [];
+  for (const raw of references) {
+    (referenceMatchesRealFile(raw, real) ? verified : unverified).push(raw);
+  }
+  return { verified, unverified };
+}
+
+/** Back-compat alias — validates the analysis's own top-level evidenceReferences. @deprecated prefer validateReferences for the per-RoleNeed gate in deriveRoleRequirements. */
+export function validateEvidenceReferences(analysis, realFilePaths) {
+  return validateReferences(analysis.evidenceReferences, realFilePaths);
+}
+
+/**
+ * Deterministically derives real roleRequirements from a validated
+ * ProjectAnalysis, unioned with the project's own mechanical floor (real
+ * build/test/lint commands — see project-profile.js's detectRoleRequirements)
+ * so a thin or low-confidence analysis can never leave a real project with
+ * zero role requirements. The analyst's own role/capability tokens are
+ * sanitized against the known vocabulary first — an unrecognized one is
+ * dropped, never trusted as-is.
+ *
+ * Evidence is checked PER role need, not once for the whole analysis: a
+ * recommendedRoleNeeds entry is only trusted when at least one of ITS OWN
+ * `evidence` citations verifies against a real file the analyst actually
+ * had access to — a single well-evidenced role need can no longer
+ * "vouch for" every other, unrelated role need in the same response.
+ * @param {object} analysis - parseProjectAnalysis().analysis
+ * @param {Array<{role: string, capabilities: string[], reason: string}>} mechanicalFloor - profile.roleRequirements (the pre-existing command-based detection)
+ * @param {string[]} [realFilePaths] - the sanitized snapshot's real copiedFiles; omit only when no real file list is available (falls back to trusting each role need's vocabulary alone, matching this function's pre-sanitized-snapshot behavior)
+ * @returns {Array<{role: string, capabilities: string[], reason: string}>}
+ */
+export function deriveRoleRequirements(analysis, mechanicalFloor, realFilePaths = null) {
+  const byRole = new Map(mechanicalFloor.map((requirement) => [requirement.role, { ...requirement }]));
+  for (const need of analysis.recommendedRoleNeeds) {
+    if (!KNOWN_ROLES.has(need.role)) continue;
+    const capabilities = need.capabilities.filter((c) => KNOWN_CAPABILITIES.has(c));
+    if (!capabilities.length) continue;
+    // Real-evidence-per-recommendation gate: this specific role need is
+    // only trusted when it cites at least one real file of its own.
+    if (realFilePaths && !(need.evidence ?? []).some((ref) => referenceMatchesRealFile(ref, realFilePaths))) continue;
+    const existing = byRole.get(need.role);
+    if (existing) {
+      existing.capabilities = [...new Set([...existing.capabilities, ...capabilities])];
+      existing.reason = `${existing.reason} Bootstrap Analyst: ${need.reason ?? "real project analysis"}.`;
+    } else {
+      byRole.set(need.role, { role: need.role, capabilities, reason: `Bootstrap Analyst: ${need.reason ?? "real project analysis"}.` });
+    }
+  }
+  return [...byRole.values()];
+}