sentinelayer-cli 0.46.4 → 0.48.0

package/src/plugin/manifest.js

@@ -3,7 +3,8 @@ import path from "node:path";
 
 import { ZodError, z } from "zod";
 
-import { resolveOutputRoot } from "../config/service.js";
+import { resolveOutputContext } from "../config/service.js";
+import { requireOutputFileSystem } from "../config/output-filesystem.js";
 
 export const PLUGIN_MANIFEST_SCHEMA_VERSION = "1.0.0";
 export const PLUGIN_MANIFEST_KIND = "sentinelayer.cli.plugin";
@@ -284,11 +285,13 @@ export function stringifyJson(value) {
   return `${JSON.stringify(value, null, 2)}\n`;
 }
 
-export async function writeJsonFile(filePath, value, { force = false } = {}) {
+export async function writeJsonFile(filePath, value, { force = false, outputFs } = {}) {
+  requireOutputFileSystem(outputFs);
   const resolvedPath = path.resolve(filePath);
+  await outputFs.assertPath(resolvedPath);
   if (!force) {
     try {
-      await fsp.access(resolvedPath);
+      await outputFs.access(resolvedPath);
       throw new Error(`File already exists: ${resolvedPath}. Use --force to overwrite.`);
     } catch (error) {
       if (error && typeof error === "object" && error.code === "ENOENT") {
@@ -301,8 +304,8 @@ export async function writeJsonFile(filePath, value, { force = false } = {}) {
     }
   }
 
-  await fsp.mkdir(path.dirname(resolvedPath), { recursive: true });
-  await fsp.writeFile(resolvedPath, stringifyJson(value), "utf-8");
+  await outputFs.mkdir(path.dirname(resolvedPath), { recursive: true });
+  await outputFs.writeFile(resolvedPath, stringifyJson(value), "utf-8");
   return resolvedPath;
 }
 
@@ -315,8 +318,8 @@ export async function readJsonFile(filePath) {
   };
 }
 
-export async function resolvePluginsDirectoryPath({ cwd, outputDir, env } = {}) {
-  const outputRoot = await resolveOutputRoot({
+export async function resolvePluginsDirectoryPath({ cwd, outputDir, env, outputContext } = {}) {
+  const { outputRoot } = outputContext || await resolveOutputContext({
     cwd,
     outputDirOverride: outputDir,
     env,
@@ -324,11 +327,12 @@ export async function resolvePluginsDirectoryPath({ cwd, outputDir, env } = {})
   return path.join(outputRoot, "plugins");
 }
 
-export async function resolveDefaultPluginManifestPath({ cwd, outputDir, env, pluginId } = {}) {
+export async function resolveDefaultPluginManifestPath({ cwd, outputDir, env, pluginId, outputContext } = {}) {
   const pluginsRoot = await resolvePluginsDirectoryPath({
     cwd,
     outputDir,
     env,
+    outputContext,
   });
   const normalizedId = normalizePluginId(pluginId);
   return path.join(pluginsRoot, normalizedId, "plugin.json");

package/src/review/ai-review.js

@@ -10,11 +10,12 @@ import {
 import { computeProviderCost } from "../billing/price-book.js";
 import { buildBillingRunId, buildCallIdempotencyKey, sanitizeBillingMetadata } from "../billing/ledger-entry.js";
 import { recordSessionUsage } from "../billing/session-usage.js";
-import { loadConfig, userConfigValues } from "../config/service.js";
+import { loadConfig, resolveOutputContext, userConfigValues } from "../config/service.js";
 import { evaluateBudget } from "../cost/budget.js";
-import { appendCostEntry, summarizeCostHistory } from "../cost/history.js";
+import { appendCostEntry, summarizeCostHistory, loadCostHistory } from "../cost/history.js";
 import { estimateTokens } from "../cost/tokenizer.js";
-import { appendRunEvent, deriveStopClassFromBudget } from "../telemetry/ledger.js";
+import { evaluateSeverityClassification, normalizeSeverityClassifier, withSeverityEvaluationQueue, severityResourceTotals, parseSeverityEvaluationMaxCost, TYPESAFE_SEVERITY_MODEL, SEVERITY_DICTIONARY_VERSION } from "./typesafe-severity.js";
+import { appendRunEvent, loadRunEvents, deriveStopClassFromBudget } from "../telemetry/ledger.js";
 
 const AI_SEVERITIES = new Set(["P0", "P1", "P2", "P3"]);
 const DEFAULT_AI_MAX_FINDINGS = 20;
@@ -199,13 +200,51 @@ function summarizeFindings(findings = []) {
   };
 }
 
+// Normalization remains permissive for legacy reports. Completion requires a
+// structured review, so error envelopes and invented defaults cannot prove it.
+function validateReviewResponse(text) {
+  const raw = String(text || "").trim();
+  const fenced = raw.match(/^```(?:json)?\s*([\s\S]*?)```\s*$/i);
+  let parsed;
+  try {
+    parsed = JSON.parse(fenced ? fenced[1] : raw);
+  } catch {
+    return { valid: false, reason: "unstructured_response" };
+  }
+  if (Array.isArray(parsed)) parsed = { findings: parsed };
+  if (!parsed || typeof parsed !== "object") return { valid: false, reason: "invalid_review_envelope" };
+  const hasError = (value) => value !== undefined && value !== null && value !== false && value !== "" &&
+    !(Array.isArray(value) && value.length === 0);
+  const invalidStatus = Object.hasOwn(parsed, "status") &&
+    (typeof parsed.status !== "string" || !["ok", "success", "complete", "completed", "passed"].includes(parsed.status.trim().toLowerCase()));
+  if (hasError(parsed.error) || hasError(parsed.errors) || hasError(parsed.refusal) || invalidStatus ||
+      parsed.ok === false || parsed.success === false || parsed.complete === false) {
+    return { valid: false, reason: "error_response" };
+  }
+  if (!Array.isArray(parsed.findings)) return { valid: false, reason: "missing_or_invalid_findings" };
+  const malformed = parsed.findings.some((finding) => {
+    if (!finding || typeof finding !== "object" || Array.isArray(finding)) return true;
+    const message = finding.title || finding.message;
+    const line = typeof finding.line === "string" && /^\d+$/.test(finding.line) ? Number(finding.line) : finding.line;
+    return typeof message !== "string" || !message.trim() ||
+      typeof finding.file !== "string" || !finding.file.trim() ||
+      typeof finding.severity !== "string" || !AI_SEVERITIES.has(finding.severity.trim().toUpperCase()) ||
+      !Number.isSafeInteger(line) || line < 1 ||
+      (finding.confidence !== undefined && finding.confidence !== null &&
+        (typeof finding.confidence !== "number" || !Number.isFinite(finding.confidence) || finding.confidence < 0 || finding.confidence > 1));
+  });
+  return { valid: !malformed, reason: malformed ? "malformed_findings" : "structured_review" };
+}
+
 export function parseAiReviewResponse({ text, maxFindings = DEFAULT_AI_MAX_FINDINGS } = {}) {
   const parsed = extractJsonPayload(text);
+  const reviewValidity = validateReviewResponse(text);
   const normalizedMaxFindings = Math.max(1, Math.floor(Number(maxFindings || DEFAULT_AI_MAX_FINDINGS)));
 
   if (!parsed) {
     return {
       parser: "fallback_text",
+      reviewValidity,
       summary:
         sanitizeExcerpt(text) || "AI response could not be parsed as JSON; no structured findings extracted.",
       findings: [],
@@ -229,6 +268,7 @@ export function parseAiReviewResponse({ text, maxFindings = DEFAULT_AI_MAX_FINDI
 
   return {
     parser: "json",
+    reviewValidity,
     summary: summary || "Structured AI response parsed successfully.",
     findings,
   };
@@ -355,12 +395,14 @@ function composeAiReviewMarkdown({
   runId,
   mode,
   parser,
+  reviewValidity,
   summary,
   provider,
   model,
   dryRun,
   findings = [],
   usage,
+  severityClassification = null,
   combinedSummary,
 } = {}) {
   const findingLines =
@@ -374,7 +416,8 @@ function composeAiReviewMarkdown({
               (finding.userImpact ? `   user_impact: ${finding.userImpact}\n` : "") +
               (finding.trafficLight ? `   traffic_light: ${finding.trafficLight}\n` : "") +
               `   suggested_fix: ${finding.suggestedFix}` +
-              (finding.confidence === null ? "" : `\n   confidence: ${finding.confidence.toFixed(2)}`)
+              (finding.confidence === null ? "" : `\n   confidence: ${finding.confidence.toFixed(2)}`) +
+              (finding.severityClassification ? `\n   severity_evaluation: ${finding.severityClassification.status} / ${finding.severityClassification.reason}; candidate=${finding.severityClassification.severity || "unverified"}; category=${finding.severityClassification.category || "unverified"}; authority=evaluation_only` : "")
           )
           .join("\n")
       : "- none";
@@ -389,12 +432,14 @@ function composeAiReviewMarkdown({
     `Model: ${model}`,
     `Dry run: ${dryRun ? "yes" : "no"}`,
     `Parser: ${parser}`,
+    `Structured review: ${reviewValidity?.valid ? "valid" : "incomplete"} (${reviewValidity?.reason || "unknown"})`,
     "",
+    ...(severityClassification ? [`TypeSafe classification evaluation: ${severityClassification.status} / ${severityClassification.reason}; schema validation only, original gate severities unchanged.`, `Classifier usage: ${severityClassification.usage ? JSON.stringify(severityClassification.usage) : "unknown/not submitted (not zero cost)"}; attempted=${severityClassification.attempted}`, ""] : []),
     "Summary:",
     `- ${summary || "No summary provided."}`,
     `- Combined findings: P0=${combinedSummary.P0} P1=${combinedSummary.P1} P2=${combinedSummary.P2} P3=${combinedSummary.P3}`,
     `- Blocking: ${combinedSummary.blocking ? "yes" : "no"}`,
-    `- Usage: input_tokens=${usage.inputTokens} output_tokens=${usage.outputTokens} cost_usd=${usage.costUsd.toFixed(6)} duration_ms=${usage.durationMs}`,
+    `- ${severityClassification ? "Generation usage" : "Usage"}: input_tokens=${usage.inputTokens} output_tokens=${usage.outputTokens} cost_usd=${usage.costUsd.toFixed(6)} duration_ms=${usage.durationMs}`,
     "",
     "AI Findings:",
     findingLines,
@@ -486,6 +531,7 @@ export async function runAiReviewLayer({
   warningThresholdPercent = 80,
   systemPrompt = "",
   dryRun = false,
+  severityClassifier = "off",
   requireUsageLedger = false,
   usageRecorder = recordSessionUsage,
   sourceCommand = "review",
@@ -496,8 +542,11 @@ export async function runAiReviewLayer({
   usageFailureLabel = "Review AI",
   env = process.env,
 } = {}) {
+  normalizeSeverityClassifier(severityClassifier);
+  if (severityClassifier === "typesafe") maxCostUsd = parseSeverityEvaluationMaxCost(maxCostUsd, 1);
   const normalizedTargetPath = path.resolve(String(targetPath || "."));
   const normalizedRunDirectory = path.resolve(String(runDirectory || "."));
+  const { outputFs } = await resolveOutputContext({ cwd: normalizedTargetPath, outputDirOverride: outputDir, env });
   const normalizedMode = normalizeString(mode) || "full";
   const normalizedMaxFindings = Math.max(
     1,
@@ -624,7 +673,7 @@ export async function runAiReviewLayer({
     noProgressStreak: 0,
   };
 
-  const budget = evaluateBudget({
+  let budget = evaluateBudget({
     sessionSummary,
     maxCostUsd: parseNonNegativeNumber(maxCostUsd, "maxCostUsd"),
     maxOutputTokens: parseNonNegativeNumber(maxOutputTokens, "maxOutputTokens"),
@@ -718,6 +767,51 @@ export async function runAiReviewLayer({
     }
   }
 
+  let severityClassification = null;
+  if (severityClassifier === "typesafe") {
+    const historyOptions = { targetPath: normalizedTargetPath, outputDirOverride: outputDir };
+    severityClassification = await withSeverityEvaluationQueue(`${appendedCost.filePath}:${normalizedSessionId}`, async () => {
+      let reservation = false; const attemptId = crypto.randomUUID();
+      const event = (phase, metadata) => appendRunEvent(historyOptions, {
+        sessionId: normalizedSessionId, runId: normalizedRunId,
+        eventType: phase === "reserved" ? "tool_call" : "run_step",
+        metadata: { layer: "severity_classification_evaluation", version: 1, attemptId, phase, costKnown: false, outputTokensKnown: false, ...metadata },
+      });
+      let classifierBudget = budget;
+      try {
+        const [{ events }, current] = await Promise.all([loadRunEvents(historyOptions), loadCostHistory(historyOptions)]);
+        const baseline = summarizeCostHistory(current.history).sessions.find((r) => r.sessionId === normalizedSessionId) || sessionSummary;
+        const extra = severityResourceTotals(events, normalizedSessionId);
+        classifierBudget = evaluateBudget({ ...budget.limits, sessionSummary: { ...baseline, toolCalls: baseline.toolCalls + extra.toolCalls, durationMs: baseline.durationMs + extra.durationMs } });
+        if (extra.unknownRuntime && budget.limits.maxRuntimeMs > 0) return { version: 1, mode: "typesafe", authority: "evaluation_only", verification: "response_schema_only", status: "unverified", reason: "prior_runtime_unknown", requestedModel: TYPESAFE_SEVERITY_MODEL, dictionaryVersion: SEVERITY_DICTIONARY_VERSION, attempted: false, durationMs: 0, usage: null, findings: parsed.findings.map(() => ({ status: "unverified", reason: "prior_runtime_unknown", severity: null, category: null })) };
+      } catch {
+        return { version: 1, mode: "typesafe", authority: "evaluation_only", status: "unverified", reason: "accounting_unavailable", requestedModel: TYPESAFE_SEVERITY_MODEL, dictionaryVersion: SEVERITY_DICTIONARY_VERSION, attempted: false, durationMs: 0, usage: null, findings: parsed.findings.map(() => ({ status: "unverified", reason: "accounting_unavailable", severity: null, category: null })) };
+      }
+      let evaluated = await evaluateSeverityClassification({
+        mode: severityClassifier, findings: parsed.findings, env, dryRun,
+        requireUsageLedger: normalizedRequireUsageLedger, budget: classifierBudget,
+        beforeRequest: async () => { await event("reserved", { reservedRequests: 1 }); reservation = true; },
+      });
+      if (reservation) {
+        try { await event("completed", { actualRequests: evaluated.attempted ? 1 : 0, durationMs: evaluated.durationMs, status: evaluated.status, reason: evaluated.reason, costKnown: false, outputTokensKnown: Boolean(evaluated.usage), reportedUsage: evaluated.usage }); }
+        catch { evaluated = { ...evaluated, status: "unverified", reason: "accounting_unavailable" }; }
+      }
+      const resourcesAfter = evaluateBudget({ ...classifierBudget.limits, sessionSummary: {
+        costUsd: classifierBudget.usage.costUsd + (evaluated.usage?.listPriceEstimateUsd || 0),
+        outputTokens: classifierBudget.usage.outputTokens + (evaluated.usage?.outputTokens || 0),
+        durationMs: classifierBudget.usage.runtimeMs + (reservation ? evaluated.durationMs : 0),
+        toolCalls: classifierBudget.usage.toolCalls + (reservation ? 1 : 0),
+        noProgressStreak: classifierBudget.usage.noProgressStreak,
+      } });
+      if (evaluated.attempted && !evaluated.usage) resourcesAfter.classificationUsageUnknown = true;
+      return { ...evaluated, resourceAccounting: { reservedRequests: reservation ? 1 : 0, actualRequests: evaluated.attempted ? 1 : 0, durationMs: evaluated.durationMs, budgetAfter: resourcesAfter } };
+    });
+    if (severityClassification.resourceAccounting?.budgetAfter) budget = severityClassification.resourceAccounting.budgetAfter;
+    aiFindings.forEach((finding, index) => {
+      finding.severityClassification = { ...severityClassification.findings[index], authority: "evaluation_only", dictionaryVersion: severityClassification.dictionaryVersion, model: severityClassification.requestedModel };
+    });
+  }
+
   let stopTelemetry = null;
   if (budget.blocking) {
     stopTelemetry = await appendRunEvent(
@@ -755,7 +849,7 @@ export async function runAiReviewLayer({
     );
   }
 
-  await fsp.mkdir(normalizedRunDirectory, { recursive: true });
+  await outputFs.mkdir(normalizedRunDirectory, { recursive: true });
   const promptPath = path.join(normalizedRunDirectory, "REVIEW_AI_PROMPT.txt");
   const reportMarkdownPath = path.join(normalizedRunDirectory, "REVIEW_AI.md");
   const reportJsonPath = path.join(normalizedRunDirectory, "REVIEW_AI.json");
@@ -773,6 +867,7 @@ export async function runAiReviewLayer({
     runId: normalizedRunId,
     mode: normalizedMode,
     parser: parsed.parser,
+    reviewValidity: parsed.reviewValidity,
     summary: parsed.summary,
     provider: resolvedProvider,
     model: resolvedModel,
@@ -786,6 +881,7 @@ export async function runAiReviewLayer({
     aiSummary,
     combinedSummary,
     findings: aiFindings,
+    ...(severityClassification ? { severityClassification } : {}),
   };
 
   const reportMarkdown = composeAiReviewMarkdown({
@@ -793,22 +889,26 @@ export async function runAiReviewLayer({
     runId: normalizedRunId,
     mode: normalizedMode,
     parser: parsed.parser,
+    reviewValidity: parsed.reviewValidity,
     summary: parsed.summary,
     provider: resolvedProvider,
     model: resolvedModel,
     dryRun: Boolean(dryRun),
     findings: aiFindings,
     usage,
+    severityClassification,
     combinedSummary,
   });
 
-  await fsp.writeFile(promptPath, `${prompt}\n`, "utf-8");
-  await fsp.writeFile(reportMarkdownPath, `${reportMarkdown.trim()}\n`, "utf-8");
-  await fsp.writeFile(reportJsonPath, `${JSON.stringify(reportPayload, null, 2)}\n`, "utf-8");
+  await outputFs.writeFile(promptPath, `${prompt}\n`, "utf-8");
+  await outputFs.writeFile(reportMarkdownPath, `${reportMarkdown.trim()}\n`, "utf-8");
+  await outputFs.writeFile(reportJsonPath, `${JSON.stringify(reportPayload, null, 2)}\n`, "utf-8");
 
   return {
     parser: parsed.parser,
+    reviewValidity: parsed.reviewValidity,
     summary: parsed.summary,
+    ...(severityClassification ? { severityClassification } : {}),
     findings: aiFindings,
     aiSummary,
     combinedSummary,

package/src/review/investor-dd-devtestbot.js

@@ -7,10 +7,10 @@
  * writes an explicit evidence-gap artifact bundle.
  */
 
-import fsp from "node:fs/promises";
 import path from "node:path";
 import crypto from "node:crypto";
 import { spawnSync } from "node:child_process";
+import { requireOutputFileSystem } from "../config/output-filesystem.js";
 
 import { recordProvisionedIdentity } from "../ai/identity-store.js";
 import { runDevTestBotSession } from "../agents/devtestbot/tool.js";
@@ -27,9 +27,10 @@ export const DEVTESTBOT_PHASE_DEFAULT_SCOPE = "smoke";
 export const DEVTESTBOT_PHASE_DEFAULT_SWARMS = 1;
 export const DEVTESTBOT_PHASE_DEFAULT_PER_SWARM_BUDGET_USD = 0.25;
 
-async function writeJson(filePath, obj) {
-  await fsp.mkdir(path.dirname(filePath), { recursive: true });
-  await fsp.writeFile(filePath, JSON.stringify(obj, null, 2), "utf-8");
+async function writeJsonWithFs(outputFs, filePath, obj) {
+  requireOutputFileSystem(outputFs);
+  await outputFs.mkdir(path.dirname(filePath), { recursive: true });
+  await outputFs.writeFile(filePath, JSON.stringify(obj, null, 2), "utf-8");
 }
 
 function normalizeString(value) {
@@ -347,14 +348,17 @@ function makeSyntheticIdentityResponse({ runId, index }) {
 }
 
 export async function provisionDevTestBotIdentities({
+  outputFs,
   outputRoot,
   runId,
   count,
   provisionIdentity = null,
   onEvent = () => {},
 } = {}) {
+  requireOutputFileSystem(outputFs);
   if (!outputRoot) throw new TypeError("provisionDevTestBotIdentities requires outputRoot");
   if (!runId) throw new TypeError("provisionDevTestBotIdentities requires runId");
+  await outputFs.assertPath(outputRoot);
   const total = clampInt(count, { min: 0, max: DEVTESTBOT_PHASE_MAX_CONCURRENT, fallback: 0 });
   const identities = [];
 
@@ -378,6 +382,7 @@ export async function provisionDevTestBotIdentities({
       response = makeSyntheticIdentityResponse({ runId, index });
     }
     const recorded = await recordProvisionedIdentity({
+      outputFs,
       outputRoot,
       response,
       context: {
@@ -459,6 +464,7 @@ function safeErrorMessage(error) {
 }
 
 export async function runDevTestBotPhase({
+  outputFs,
   runId,
   rootPath,
   outputRoot,
@@ -470,11 +476,15 @@ export async function runDevTestBotPhase({
   options = {},
   onEvent = () => {},
 } = {}) {
+  requireOutputFileSystem(outputFs);
+  const writeJson = (...args) => writeJsonWithFs(outputFs, ...args);
   if (!runId) throw new TypeError("runDevTestBotPhase requires runId");
   if (!rootPath) throw new TypeError("runDevTestBotPhase requires rootPath");
   if (!outputRoot) throw new TypeError("runDevTestBotPhase requires outputRoot");
   if (!runRoot) throw new TypeError("runDevTestBotPhase requires runRoot");
   if (!artifactDir) throw new TypeError("runDevTestBotPhase requires artifactDir");
+  const phaseRoot = path.join(runRoot, "devtestbot");
+  await Promise.all([outputRoot, phaseRoot, artifactDir].map((destination) => outputFs.assertPath(destination)));
 
   const normalized = normalizePhaseOptions(options);
   const phaseStartedAt = Date.now();
@@ -485,8 +495,7 @@ export async function runDevTestBotPhase({
     budget,
     options: normalized,
   });
-  const phaseRoot = path.join(runRoot, "devtestbot");
-  await fsp.mkdir(phaseRoot, { recursive: true });
+  await outputFs.mkdir(phaseRoot, { recursive: true });
 
   onEvent({
     type: "phase_start",
@@ -551,6 +560,7 @@ export async function runDevTestBotPhase({
   }
 
   const identities = await provisionDevTestBotIdentities({
+    outputFs,
     outputRoot,
     runId,
     count: plan.identityCount,
@@ -612,6 +622,7 @@ export async function runDevTestBotPhase({
           execute: plan.execute,
           recordVideo: plan.recordVideo,
         }, {
+          outputFs,
           targetPath: rootPath,
           outputRoot,
           runId,

package/src/review/investor-dd-orchestrator.js

@@ -22,6 +22,8 @@
 import fsp from "node:fs/promises";
 import path from "node:path";
 import crypto from "node:crypto";
+import { resolveOutputContext } from "../config/service.js";
+import { requireOutputFileSystem } from "../config/output-filesystem.js";
 
 import { routeFilesToPersonas, summarizeRouting } from "./investor-dd-file-router.js";
 import { runAllPersonas } from "./investor-dd-persona-runner.js";
@@ -160,9 +162,10 @@ async function collectFileMetrics(rootPath, files) {
   return metrics;
 }
 
-async function writeJson(filePath, obj) {
-  await fsp.mkdir(path.dirname(filePath), { recursive: true });
-  await fsp.writeFile(filePath, JSON.stringify(obj, null, 2), "utf-8");
+async function writeJsonWithFs(outputFs, filePath, obj) {
+  requireOutputFileSystem(outputFs);
+  await outputFs.mkdir(path.dirname(filePath), { recursive: true });
+  await outputFs.writeFile(filePath, JSON.stringify(obj, null, 2), "utf-8");
 }
 
 function sha256(text) {
@@ -341,17 +344,20 @@ export async function runInvestorDd({
 
   const runId = `investor-dd-${Date.now()}-${crypto.randomUUID().slice(0, 8)}`;
   const resolvedBudget = resolveInvestorDdBudget(budgetOptions);
-  const artifactBase = outputDir
-    ? path.resolve(outputDir, runId, INVESTOR_DD_ARTIFACT_SUBDIR)
-    : path.resolve(rootPath, ".sentinelayer", "runs", runId, INVESTOR_DD_ARTIFACT_SUBDIR);
+  const explicitOutputDir = String(outputDir || "").trim();
+  const { outputRoot, outputFs } = await resolveOutputContext({
+    cwd: rootPath,
+    outputDirOverride: explicitOutputDir || ".sentinelayer",
+  });
+  const writeJson = (...args) => writeJsonWithFs(outputFs, ...args);
+  const artifactBase = explicitOutputDir
+    ? path.join(outputRoot, runId, INVESTOR_DD_ARTIFACT_SUBDIR)
+    : path.join(outputRoot, "runs", runId, INVESTOR_DD_ARTIFACT_SUBDIR);
   const runRoot = path.dirname(artifactBase);
-  const outputRoot = outputDir
-    ? path.resolve(outputDir)
-    : path.resolve(rootPath, ".sentinelayer");
-  await fsp.mkdir(artifactBase, { recursive: true });
+  await outputFs.mkdir(artifactBase, { recursive: true });
 
   const streamPath = path.join(artifactBase, "stream.ndjson");
-  const streamHandle = await fsp.open(streamPath, "w");
+  const streamHandle = await outputFs.open(streamPath, "w");
   let streamClosePromise = null;
 
   const closeStream = () => {
@@ -410,6 +416,7 @@ export async function runInvestorDd({
       maxRuntimeMs: resolvedBudget.maxRuntimeMinutes * 60_000,
     });
     const runResult = await runAllPersonas({
+      outputFs,
       routing,
       rootPath,
       budget: budgetState,
@@ -434,6 +441,7 @@ export async function runInvestorDd({
     });
 
     devTestBotPhase = await runDevTestBotPhase({
+      outputFs,
       runId,
       rootPath,
       outputRoot,
@@ -539,7 +547,7 @@ export async function runInvestorDd({
 
   const markdown = buildSummaryMarkdown({ runId, summary, routing, byPersona });
   const reportPath = path.join(artifactBase, "report.md");
-  await fsp.writeFile(reportPath, markdown, "utf-8");
+  await outputFs.writeFile(reportPath, markdown, "utf-8");
 
   const htmlReport = renderInvestorDdHtml({
     runId,
@@ -549,7 +557,7 @@ export async function runInvestorDd({
     findings,
     compliance: compliance ? compliance.packs : null,
   });
-  await fsp.writeFile(path.join(artifactBase, "report.html"), htmlReport, "utf-8");
+  await outputFs.writeFile(path.join(artifactBase, "report.html"), htmlReport, "utf-8");
 
   emit({
     type: "investor_dd_complete",

package/src/review/local-review.js

@@ -4,7 +4,8 @@ import fsp from "node:fs/promises";
 import path from "node:path";
 
 import { buildScrubbedEnv } from "../agents/shared-tools/shell.js";
-import { resolveOutputRoot } from "../config/service.js";
+import { resolveOutputContext } from "../config/service.js";
+import { bindOutputFileSystem, requireOutputFileSystem } from "../config/output-filesystem.js";
 import { resolveCodebaseIngest } from "../ingest/engine.js";
 import { runSpecBindingChecks } from "./spec-binding.js";
 
@@ -852,9 +853,10 @@ export function staticCheckEnv(env = process.env) {
   return { ...buildScrubbedEnv(env), CI: "1", FORCE_COLOR: "0" };
 }
 
-async function executeStaticCheck({ check, targetPath, runDir } = {}) {
+async function executeStaticCheck({ check, targetPath, runDir, outputFs } = {}) {
+  requireOutputFileSystem(outputFs);
   const checksDir = path.join(runDir, "checks");
-  await fsp.mkdir(checksDir, { recursive: true });
+  await outputFs.mkdir(checksDir, { recursive: true });
 
   const startedAt = Date.now();
   const result = spawnSync(check.command, check.args, {
@@ -869,8 +871,8 @@ async function executeStaticCheck({ check, targetPath, runDir } = {}) {
   const stderr = String(result.stderr || "");
   const stdoutPath = path.join(checksDir, `${check.id}.stdout.log`);
   const stderrPath = path.join(checksDir, `${check.id}.stderr.log`);
-  await fsp.writeFile(stdoutPath, stdout, "utf-8");
-  await fsp.writeFile(stderrPath, stderr, "utf-8");
+  await outputFs.writeFile(stdoutPath, stdout, "utf-8");
+  await outputFs.writeFile(stderrPath, stderr, "utf-8");
 
   if (result.error && result.error.code === "ENOENT") {
     return {
@@ -933,7 +935,8 @@ async function executeStaticCheck({ check, targetPath, runDir } = {}) {
 
 export const __localReviewForTests = Object.freeze({ executeStaticCheck });
 
-async function runStaticAnalysisLayer({ targetPath, ingest, runDir, maxFindings = MAX_FINDINGS } = {}) {
+async function runStaticAnalysisLayer({ targetPath, ingest, runDir, outputFs, maxFindings = MAX_FINDINGS } = {}) {
+  requireOutputFileSystem(outputFs);
   const checks = buildStaticChecks(ingest);
   const results = [];
   const findings = [];
@@ -943,6 +946,7 @@ async function runStaticAnalysisLayer({ targetPath, ingest, runDir, maxFindings
       check,
       targetPath,
       runDir,
+      outputFs,
     });
     results.push(result);
 
@@ -1145,12 +1149,13 @@ ${formatDeterministicFindingsMarkdown(result.findings)}
 `;
 }
 
-async function writeDeterministicReviewArtifacts({ result, runDir } = {}) {
+async function writeDeterministicReviewArtifacts({ result, runDir, outputFs } = {}) {
+  requireOutputFileSystem(outputFs);
   const markdownPath = path.join(runDir, "REVIEW_DETERMINISTIC.md");
   const jsonPath = path.join(runDir, "REVIEW_DETERMINISTIC.json");
 
-  await fsp.writeFile(markdownPath, `${buildDeterministicReviewMarkdown(result).trim()}\n`, "utf-8");
-  await fsp.writeFile(jsonPath, `${JSON.stringify(result, null, 2)}\n`, "utf-8");
+  await outputFs.writeFile(markdownPath, `${buildDeterministicReviewMarkdown(result).trim()}\n`, "utf-8");
+  await outputFs.writeFile(jsonPath, `${JSON.stringify(result, null, 2)}\n`, "utf-8");
 
   return {
     markdownPath,
@@ -1159,6 +1164,7 @@ async function writeDeterministicReviewArtifacts({ result, runDir } = {}) {
 }
 
 export async function runDeterministicReviewPipeline({
+  outputFs: inheritedOutputFs,
   targetPath,
   mode = "full",
   outputDir = "",
@@ -1170,17 +1176,19 @@ export async function runDeterministicReviewPipeline({
     allowedModes: ["full", "diff", "staged"],
   });
 
-  const outputRoot = await resolveOutputRoot({
+  const { outputRoot, outputFs: resolvedOutputFs } = await resolveOutputContext({
     cwd: normalizedTargetPath,
     outputDirOverride: outputDir,
   });
+  const outputFs = inheritedOutputFs === undefined ? resolvedOutputFs : requireOutputFileSystem(inheritedOutputFs);
   const runId = `review-${formatTimestampForFile()}-${randomUUID().slice(0, 8)}`;
   const runDir = path.join(outputRoot, "reviews", runId);
-  await fsp.mkdir(runDir, { recursive: true });
+  await outputFs.mkdir(runDir, { recursive: true });
 
   const ingestResolution = await resolveCodebaseIngest({
     rootPath: normalizedTargetPath,
     outputDir,
+    outputFs,
     refresh: Boolean(refreshIngest),
   });
   const ingest = ingestResolution.ingest;
@@ -1221,6 +1229,7 @@ export async function runDeterministicReviewPipeline({
     targetPath: normalizedTargetPath,
     ingest,
     runDir,
+    outputFs,
     maxFindings: remainingBudget,
   });
 
@@ -1302,14 +1311,15 @@ export async function runDeterministicReviewPipeline({
   const artifacts = await writeDeterministicReviewArtifacts({
     result,
     runDir,
+    outputFs,
   });
 
   return {
     ...result,
-    artifacts: {
+    artifacts: bindOutputFileSystem({
       runDirectory: runDir,
       ...artifacts,
-    },
+    }, outputFs),
   };
 }
 
@@ -1363,13 +1373,13 @@ export async function writeReviewReport({
   outputDir = "",
   reportMarkdown,
 } = {}) {
-  const outputRoot = await resolveOutputRoot({
+  const { outputRoot, outputFs } = await resolveOutputContext({
     cwd: targetPath,
     outputDirOverride: outputDir,
   });
   const reportDir = path.join(outputRoot, "reports");
-  await fsp.mkdir(reportDir, { recursive: true });
+  await outputFs.mkdir(reportDir, { recursive: true });
   const reportPath = path.join(reportDir, `review-scan-${mode}-${formatTimestampForFile()}.md`);
-  await fsp.writeFile(reportPath, `${String(reportMarkdown || "").trim()}\n`, "utf-8");
+  await outputFs.writeFile(reportPath, `${String(reportMarkdown || "").trim()}\n`, "utf-8");
   return reportPath;
 }