sentinelayer-cli 0.46.4 → 0.48.0

package/src/commands/board.js

@@ -104,10 +104,10 @@ export function registerBoardCommand(program) {
     .description("Check whether a ticket's evidence holds (done | not-done | cannot-verify)")
     .requiredOption("--file <path>", "Ticket JSON file with an `evidence` array")
     .option("--json", "Emit machine-readable output")
-    .action(async (options) => {
+    .action(async (options, command) => {
       const code = await runBoardCheck({
         file: path.resolve(process.cwd(), String(options.file)),
-        emitJson: Boolean(options.json),
+        emitJson: Boolean(options.json || command.optsWithGlobals().json),
       });
       process.exitCode = code;
     });

package/src/commands/chat.js

@@ -1,4 +1,4 @@
-import fsp from "node:fs/promises";
+import { requireOutputFileSystem } from "../config/output-filesystem.js";
 import path from "node:path";
 import process from "node:process";
 
@@ -10,7 +10,7 @@ import {
   resolveProvider,
 } from "../ai/client.js";
 import { recordCliLlmSessionUsage, usageNumber } from "../billing/llm-session-usage.js";
-import { resolveOutputRoot } from "../config/service.js";
+import { resolveOutputContext } from "../config/service.js";
 import { estimateModelCost } from "../cost/tracker.js";
 import { estimateTokens } from "../cost/tokenizer.js";
 import { normalizeSessionId } from "../session/paths.js";
@@ -43,10 +43,11 @@ async function readPromptFromStdin() {
   });
 }
 
-async function appendTranscriptEntries({ transcriptPath, entries } = {}) {
-  await fsp.mkdir(path.dirname(transcriptPath), { recursive: true });
+async function appendTranscriptEntries({ transcriptPath, entries, outputFs } = {}) {
+  requireOutputFileSystem(outputFs);
+  await outputFs.mkdir(path.dirname(transcriptPath), { recursive: true });
   const rows = entries.map((entry) => JSON.stringify(entry)).join("\n");
-  await fsp.appendFile(transcriptPath, `${rows}\n`, "utf-8");
+  await outputFs.appendFile(transcriptPath, `${rows}\n`, "utf-8");
 }
 
 export function registerChatCommand(program) {
@@ -77,7 +78,7 @@ export function registerChatCommand(program) {
       }
 
       const targetPath = path.resolve(process.cwd(), String(options.path || "."));
-      const outputRoot = await resolveOutputRoot({
+      const { outputRoot, outputFs } = await resolveOutputContext({
         cwd: targetPath,
         outputDirOverride: options.outputDir,
         env: process.env,
@@ -159,6 +160,7 @@ export function registerChatCommand(program) {
           });
 
       await appendTranscriptEntries({
+        outputFs,
         transcriptPath,
         entries: [
           {

package/src/commands/judge.js

@@ -0,0 +1,125 @@
+import fsp from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+
+import { formatJudgeVerdictErrors, renderJudgeVerdictMessage, validateJudgeVerdict } from "../judge/verdict.js";
+
+function shouldEmitJson(options, command) {
+  if (options && options.json) return true;
+  return typeof command?.optsWithGlobals === "function" ? Boolean(command.optsWithGlobals().json) : false;
+}
+
+async function readStdinText() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+async function readVerdictDocument(options) {
+  if (options.file && options.stdin) throw new Error("Use --file or --stdin, not both.");
+  if (!options.file && !options.stdin) throw new Error("Give the verdict with --file <path> or --stdin.");
+  const raw = options.stdin
+    ? await readStdinText()
+    : await fsp.readFile(path.resolve(process.cwd(), String(options.file)), "utf8");
+  try {
+    return JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`The verdict is not valid JSON: ${error.message}`);
+  }
+}
+
+function report(emitJson, payload, text) {
+  if (emitJson) {
+    process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+  } else {
+    process.stdout.write(`${text}\n`);
+  }
+}
+
+function fail(emitJson, command, error) {
+  const message = error && error.message ? error.message : String(error);
+  if (emitJson) {
+    process.stdout.write(`${JSON.stringify({ command, ok: false, reason: message }, null, 2)}\n`);
+  } else {
+    process.stderr.write(`${command} failed: ${message}\n`);
+  }
+  process.exitCode = 1;
+}
+
+export function registerJudgeCommand(program) {
+  const judge = program
+    .command("judge")
+    .description("Judge a coding agent's work and send the verdict back (LLM-as-a-judge loop)");
+
+  judge
+    .command("check")
+    .description("Validate a judge-verdict offline and print the message the coder will receive")
+    .option("--file <path>", "Verdict JSON file")
+    .option("--stdin", "Read the verdict JSON from stdin")
+    .option("--escalate-to <handle...>", "Human handle(s) to mention when the verdict escalates")
+    .option("--json", "Emit machine-readable output")
+    .action(async (options, command) => {
+      const emitJson = shouldEmitJson(options, command);
+      try {
+        const checked = validateJudgeVerdict(await readVerdictDocument(options));
+        if (!checked.ok) {
+          report(emitJson, { command: "judge check", ok: false, errors: checked.errors },
+            `Invalid verdict: ${formatJudgeVerdictErrors(checked.errors)}`);
+          process.exitCode = 1;
+          return;
+        }
+        const message = renderJudgeVerdictMessage(checked.verdict, { escalateTo: options.escalateTo || [] });
+        report(emitJson, { command: "judge check", ok: true, verdict: checked.verdict, message }, message);
+      } catch (error) {
+        fail(emitJson, "judge check", error);
+      }
+    });
+
+  judge
+    .command("verdict <sessionId>")
+    .description("Send a judge-verdict to the room: the coder is mentioned and woken, and the verdict is recorded")
+    .option("--agent <id>", "Your judge agent id (default: SENTINELAYER_AGENT_ID)")
+    .option("--file <path>", "Verdict JSON file")
+    .option("--stdin", "Read the verdict JSON from stdin")
+    .option("--via <transport>", "auto (the API route when the server has it, else a room message), api, or room", "auto")
+    .option("--escalate-to <handle...>", "Human handle(s) to mention when the verdict escalates")
+    .option("--path <path>", "Workspace path for the session", ".")
+    .option("--dry-run", "Validate and print the message without sending it")
+    .option("--json", "Emit machine-readable output")
+    .action(async (sessionId, options, command) => {
+      const emitJson = shouldEmitJson(options, command);
+      try {
+        const verdict = await readVerdictDocument(options);
+        const agentId = String(options.agent || process.env.SENTINELAYER_AGENT_ID || "").trim();
+        if (!agentId) throw new Error("Name your judge agent with --agent <id> or SENTINELAYER_AGENT_ID.");
+        const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+        // One implementation for the CLI and MCP: the native judge_verdict tool, which already runs
+        // under the admission policy every local session tool uses.
+        const { createSessionMcpToolHandlers } = await import("../mcp/session-stdio-server.js");
+        const handlers = createSessionMcpToolHandlers({ targetPath });
+        const result = await handlers.judge_verdict({
+          sessionId,
+          agentId,
+          verdict,
+          via: options.via,
+          escalateTo: options.escalateTo || [],
+          dryRun: Boolean(options.dryRun),
+        });
+        const payload = { command: "judge verdict", ...result };
+        if (!result.ok) {
+          const why = result.errors ? formatJudgeVerdictErrors(result.errors) : result.reason;
+          report(emitJson, payload, `Verdict not sent: ${why}`);
+          process.exitCode = 1;
+          return;
+        }
+        if (result.dryRun) {
+          report(emitJson, payload, result.message);
+          return;
+        }
+        report(emitJson, payload,
+          `Verdict ${result.verdict.verdict} (round ${result.verdict.round}) sent to @${result.verdict.coder} via ${result.transport}.`);
+      } catch (error) {
+        fail(emitJson, "judge verdict", error);
+      }
+    });
+}

package/src/commands/legacy-args.js

@@ -57,6 +57,7 @@ export function buildLegacyArgs(baseArgs, { commandOptions = {}, command } = {})
   appendPassthroughFlag(args, "--max-runtime-minutes", commandOptions.maxRuntimeMinutes);
   appendPassthroughFlag(args, "--model", commandOptions.model);
   appendPassthroughFlag(args, "--provider", commandOptions.provider);
+  if (commandOptions.severityClassifier && commandOptions.severityClassifier !== "off") appendPassthroughFlag(args, "--severity-classifier", commandOptions.severityClassifier);
   appendPassthroughFlag(args, "--reuse-omargate", commandOptions.reuseOmargate);
   appendPassthroughFlag(args, "--scope-mode", commandOptions.scopeMode);
   appendBooleanFlag(args, "--diff", commandOptions.diff);

package/src/commands/mcp.js

@@ -34,7 +34,8 @@ import { runMcpStdioServer } from "../mcp/session-stdio-server.js";
 import { runMcpDoctorProbes } from "../mcp/doctor.js";
 import { runHostedMcpSmoke } from "../mcp/smoke.js";
 import { resolveActiveAuthSession } from "../auth/service.js";
-import { resolveOutputRoot } from "../config/service.js";
+import { resolveOutputContext, resolveOutputRoot } from "../config/service.js";
+import { createOutputFileSystem } from "../config/output-filesystem.js";
 
 function shouldEmitJson(options, command) {
   const local = Boolean(options && options.json);
@@ -51,6 +52,27 @@ function normalizeOutputPath(rawValue, fallbackPath) {
   return path.resolve(process.cwd(), candidate);
 }
 
+async function resolveWriteDestination(options, resolveDefaultPath, { suffix, ...pathOptions } = {}) {
+  if (String(options.path || "").trim()) {
+    const { outputRoot: outputPath, outputFs } = await resolveOutputContext({
+      cwd: process.cwd(),
+      outputDirOverride: options.path,
+      env: process.env,
+    });
+    return { outputPath, outputFs };
+  }
+  const outputContext = await resolveOutputContext({
+    cwd: process.cwd(),
+    outputDirOverride: options.outputDir,
+    env: process.env,
+  });
+  const defaultPath = await resolveDefaultPath({ ...pathOptions, outputContext });
+  return {
+    outputPath: suffix ? defaultPath.replace(".schema", suffix) : defaultPath,
+    outputFs: outputContext.outputFs,
+  };
+}
+
 function zodIssueSummary(error) {
   if (!(error instanceof ZodError)) {
     return String(error instanceof Error ? error.message : error);
@@ -390,14 +412,9 @@ Docs: https://github.com/mrrCarter/create-sentinelayer/blob/main/docs/mcp.md`,
     .option("--force", "Overwrite destination file if it already exists")
     .option("--json", "Emit machine-readable output")
     .action(async (options, command) => {
-      const defaultPath = await resolveDefaultMcpOutputPath({
-        cwd: process.cwd(),
-        outputDir: options.outputDir,
-        env: process.env,
-      });
-      const outputPath = normalizeOutputPath(options.path, defaultPath);
+      const { outputPath, outputFs } = await resolveWriteDestination(options, resolveDefaultMcpOutputPath);
       const schemaPayload = buildMcpToolRegistrySchema();
-      const writtenPath = await writeJsonFile(outputPath, schemaPayload, { force: Boolean(options.force) });
+      const writtenPath = await writeJsonFile(outputPath, schemaPayload, { force: Boolean(options.force), outputFs });
 
       const payload = {
         command: "mcp schema write",
@@ -420,15 +437,10 @@ Docs: https://github.com/mrrCarter/create-sentinelayer/blob/main/docs/mcp.md`,
     .option("--force", "Overwrite destination file if it already exists")
     .option("--json", "Emit machine-readable output")
     .action(async (options, command) => {
-      const defaultPath = await resolveDefaultMcpOutputPath({
-        cwd: process.cwd(),
-        outputDir: options.outputDir,
-        env: process.env,
-      });
-      const outputPath = normalizeOutputPath(options.path, defaultPath.replace(".schema", ".aidenid-template"));
+      const { outputPath, outputFs } = await resolveWriteDestination(options, resolveDefaultMcpOutputPath, { suffix: ".aidenid-template" });
       const template = buildAidenIdRegistryTemplate();
       validateMcpToolRegistry(template);
-      const writtenPath = await writeJsonFile(outputPath, template, { force: Boolean(options.force) });
+      const writtenPath = await writeJsonFile(outputPath, template, { force: Boolean(options.force), outputFs });
       const payload = {
         command: "mcp registry init-aidenid",
         outputPath: writtenPath,
@@ -456,17 +468,12 @@ Docs: https://github.com/mrrCarter/create-sentinelayer/blob/main/docs/mcp.md`,
     .option("--force", "Overwrite destination file if it already exists")
     .option("--json", "Emit machine-readable output")
     .action(async (options, command) => {
-      const defaultPath = await resolveDefaultAidenIdAdapterContractPath({
-        cwd: process.cwd(),
-        outputDir: options.outputDir,
-        env: process.env,
-      });
-      const outputPath = normalizeOutputPath(options.path, defaultPath);
+      const { outputPath, outputFs } = await resolveWriteDestination(options, resolveDefaultAidenIdAdapterContractPath);
       const template = buildAidenIdProvisioningAdapterTemplate({
         registryFile: options.registryFile,
       });
       validateAidenIdAdapterContract(template);
-      const writtenPath = await writeJsonFile(outputPath, template, { force: Boolean(options.force) });
+      const writtenPath = await writeJsonFile(outputPath, template, { force: Boolean(options.force), outputFs });
       const payload = {
         command: "mcp registry init-aidenid-adapter",
         outputPath: writtenPath,
@@ -497,15 +504,10 @@ Docs: https://github.com/mrrCarter/create-sentinelayer/blob/main/docs/mcp.md`,
       .option("--force", "Overwrite destination file if it already exists")
       .option("--json", "Emit machine-readable output")
       .action(async (options, command) => {
-        const defaultPath = await resolveDefaultMcpOutputPath({
-          cwd: process.cwd(),
-          outputDir: options.outputDir,
-          env: process.env,
-        });
-        const outputPath = normalizeOutputPath(options.path, defaultPath.replace(".schema", outputSuffix));
+        const { outputPath, outputFs } = await resolveWriteDestination(options, resolveDefaultMcpOutputPath, { suffix: outputSuffix });
         const template = buildSentinelayerSessionRegistryTemplate();
         validateMcpToolRegistry(template);
-        const writtenPath = await writeJsonFile(outputPath, template, { force: Boolean(options.force) });
+        const writtenPath = await writeJsonFile(outputPath, template, { force: Boolean(options.force), outputFs });
         const payload = {
           command: payloadCommand,
           outputPath: writtenPath,
@@ -553,17 +555,12 @@ Docs: https://github.com/mrrCarter/create-sentinelayer/blob/main/docs/mcp.md`,
     .option("--force", "Overwrite destination file if it already exists")
     .option("--json", "Emit machine-readable output")
     .action(async (options, command) => {
-      const defaultPath = await resolveDefaultHostedSentiSessionConnectorContractPath({
-        cwd: process.cwd(),
-        outputDir: options.outputDir,
-        env: process.env,
-      });
-      const outputPath = normalizeOutputPath(options.path, defaultPath);
+      const { outputPath, outputFs } = await resolveWriteDestination(options, resolveDefaultHostedSentiSessionConnectorContractPath);
       const template = buildHostedSentiSessionConnectorContract({
         localRegistryFile: options.registryFile,
       });
       validateHostedSentiSessionConnectorContract(template);
-      const writtenPath = await writeJsonFile(outputPath, template, { force: Boolean(options.force) });
+      const writtenPath = await writeJsonFile(outputPath, template, { force: Boolean(options.force), outputFs });
       const payload = {
         command: "mcp registry init-hosted-session-connector",
         outputPath: writtenPath,
@@ -588,15 +585,10 @@ Docs: https://github.com/mrrCarter/create-sentinelayer/blob/main/docs/mcp.md`,
     .option("--force", "Overwrite destination file if it already exists")
     .option("--json", "Emit machine-readable output")
     .action(async (options, command) => {
-      const defaultPath = await resolveDefaultMcpOutputPath({
-        cwd: process.cwd(),
-        outputDir: options.outputDir,
-        env: process.env,
-      });
-      const outputPath = normalizeOutputPath(options.path, defaultPath.replace(".schema", ".cli-tools"));
+      const { outputPath, outputFs } = await resolveWriteDestination(options, resolveDefaultMcpOutputPath, { suffix: ".cli-tools" });
       const template = await buildSentinelayerCliRegistryTemplate();
       validateMcpToolRegistry(template);
-      const writtenPath = await writeJsonFile(outputPath, template, { force: Boolean(options.force) });
+      const writtenPath = await writeJsonFile(outputPath, template, { force: Boolean(options.force), outputFs });
       const payload = {
         command: "mcp registry init-cli",
         outputPath: writtenPath,
@@ -805,19 +797,13 @@ Docs: https://github.com/mrrCarter/create-sentinelayer/blob/main/docs/mcp.md`,
       const serverId = String(options.id || "")
         .trim()
         .toLowerCase();
-      const defaultPath = await resolveDefaultMcpServerConfigPath({
-        cwd: process.cwd(),
-        outputDir: options.outputDir,
-        env: process.env,
-        serverId,
-      });
-      const outputPath = normalizeOutputPath(options.path, defaultPath);
+      const { outputPath, outputFs } = await resolveWriteDestination(options, resolveDefaultMcpServerConfigPath, { serverId });
       const template = buildMcpServerConfigTemplate({
         serverId,
         registryFile: options.registryFile,
       });
       const config = validateMcpServerConfig(template);
-      const writtenPath = await writeJsonFile(outputPath, config, { force: Boolean(options.force) });
+      const writtenPath = await writeJsonFile(outputPath, config, { force: Boolean(options.force), outputFs });
 
       const payload = {
         command: "mcp server init",
@@ -924,7 +910,14 @@ Docs: https://github.com/mrrCarter/create-sentinelayer/blob/main/docs/mcp.md`,
         serverId,
         serverConfigFile: String(options.serverConfig || "").trim(),
       });
-      const writtenPath = await writeJsonFile(outputPath, bridgePayload, { force: Boolean(options.force) });
+      const outputFs = String(options.path || "").trim()
+        ? (await resolveOutputContext({
+          cwd: process.cwd(),
+          outputDirOverride: options.path,
+          env: process.env,
+        })).outputFs
+        : createOutputFileSystem({ workspaceRoot: process.cwd() });
+      const writtenPath = await writeJsonFile(outputPath, bridgePayload, { force: Boolean(options.force), outputFs });
 
       const payload = {
         command: "mcp bridge init-vscode",

package/src/commands/omargate.js

@@ -19,7 +19,8 @@ export function registerOmarGateCommand(program, invokeLegacy) {
     .option("--max-parallel <n>", "Max concurrent persona calls (default: 4)")
     .option("--model <id>", "LLM model override (default: gpt-5.3-codex)")
     .option("--provider <name>", "LLM provider: sentinelayer, openai, anthropic")
-    .option("--max-cost <usd>", "Maximum AI layer cost in USD (default: 5.0)")
+    .option("--max-cost <usd>", "Reported AI cost stop threshold in USD (default: 5.0), not a pre-dispatch spending cap; with TypeSafe evaluation only, explicit 0 means NO monetary cap")
+    .option("--severity-classifier <mode>", "Opt-in classification evaluation: off|typesafe; sends generated finding evidence to TypeSafe, never changes gate severities (positive cost caps skip)", "off")
     .option("--notify-session <session-id>", "Write Omar Deep billing-grade usage entries into this Senti session (default: auto-detect active Senti session)")
     .option("--require-usage-ledger", "Fail if Omar Deep AI calls cannot write billing-grade session_usage")
     .option("--persona <csv>", "Only run these personas (comma-separated IDs); unknown IDs are dropped + warned")

package/src/commands/plugin.js

@@ -2,6 +2,7 @@ import path from "node:path";
 import process from "node:process";
 
 import pc from "picocolors";
+import { resolveOutputContext } from "../config/service.js";
 
 import {
   buildPluginManifestTemplate,
@@ -61,11 +62,15 @@ export function registerPluginCommand(program) {
       const pluginId = normalizePluginId(options.id);
       const packType = normalizePluginPackType(options.packType);
       const stage = normalizePluginLoadStage(options.stage);
-      const defaultPath = await resolveDefaultPluginManifestPath({
+      const explicitPath = String(options.path || "").trim();
+      const outputContext = await resolveOutputContext({
         cwd: process.cwd(),
-        outputDir: options.outputDir,
+        outputDirOverride: explicitPath || options.outputDir,
         env: process.env,
+      });
+      const defaultPath = explicitPath ? undefined : await resolveDefaultPluginManifestPath({
         pluginId,
+        outputContext,
       });
       const outputPath = normalizeOutputPath(options.path, defaultPath);
       const template = buildPluginManifestTemplate({
@@ -74,7 +79,10 @@ export function registerPluginCommand(program) {
         stage,
       });
       const manifest = validatePluginManifest(template);
-      const writtenPath = await writeJsonFile(outputPath, manifest, { force: Boolean(options.force) });
+      const writtenPath = await writeJsonFile(outputPath, manifest, {
+        force: Boolean(options.force),
+        outputFs: outputContext.outputFs,
+      });
 
       const payload = {
         command: "plugin init",

package/src/commands/review.js

@@ -1,4 +1,3 @@
-import fsp from "node:fs/promises";
 import path from "node:path";
 import process from "node:process";
 
@@ -26,6 +25,7 @@ import {
   writeReviewRunContext,
 } from "../review/replay.js";
 import { resolveActionOptions } from "./action-options.js";
+import { resolveOutputContext } from "../config/service.js";
 
 function shouldEmitJson(options, command) {
   const local = Boolean(options && options.json);
@@ -134,12 +134,14 @@ async function executeReviewRun({
     specFile,
   });
   const unifiedArtifacts = await writeUnifiedReviewArtifacts({
+    outputFs: deterministic.artifacts.outputFs,
     runDirectory: deterministic.artifacts.runDirectory,
     report: unified.report,
     markdown: unified.markdown,
   });
 
   const contextWrite = await writeReviewRunContext({
+    outputFs: deterministic.artifacts.outputFs,
     runDirectory: deterministic.artifacts.runDirectory,
     runId: deterministic.runId,
     targetPath: deterministic.targetPath,
@@ -511,6 +513,7 @@ export function registerReviewCommand(program) {
       const comparison = compareUnifiedReports(source.report, replayOutcome.unified.report);
       const artifact = await writeReviewComparisonArtifact({
         runDirectory: replayOutcome.deterministic.artifacts.runDirectory,
+        outputFs: replayOutcome.deterministic.artifacts.outputFs,
         baseRunId: source.report.runId,
         candidateRunId: replayOutcome.unified.report.runId,
         comparison,
@@ -571,6 +574,7 @@ export function registerReviewCommand(program) {
       const comparison = compareUnifiedReports(base.report, candidate.report);
       const artifact = await writeReviewComparisonArtifact({
         runDirectory: candidate.runDirectory,
+        outputFs: candidate.outputFs,
         baseRunId: base.report.runId,
         candidateRunId: candidate.report.runId,
         comparison,
@@ -578,9 +582,10 @@ export function registerReviewCommand(program) {
 
       let outputPath = artifact.artifactPath;
       if (actionOptions.outputFile) {
-        outputPath = path.resolve(targetPath, String(actionOptions.outputFile));
-        await fsp.mkdir(path.dirname(outputPath), { recursive: true });
-        await fsp.writeFile(outputPath, `${JSON.stringify(artifact.payload, null, 2)}\n`, "utf-8");
+        const outputContext = await resolveOutputContext({ cwd: targetPath, outputDirOverride: String(actionOptions.outputFile) });
+        outputPath = outputContext.outputRoot;
+        await outputContext.outputFs.mkdir(path.dirname(outputPath), { recursive: true });
+        await outputContext.outputFs.writeFile(outputPath, `${JSON.stringify(artifact.payload, null, 2)}\n`, "utf-8");
       }
 
       const payload = {

package/src/commands/scan.js

@@ -12,7 +12,7 @@ import {
   resolveProvider,
 } from "../ai/client.js";
 import { recordCliLlmSessionUsage, usageNumber } from "../billing/llm-session-usage.js";
-import { loadConfig, resolveOutputRoot, 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 { estimateModelCost } from "../cost/tracker.js";
@@ -292,15 +292,15 @@ async function resolvePreScanReportPath({
 } = {}) {
   const explicit = String(outputFile || "").trim();
   if (explicit) {
-    return path.resolve(targetPath, explicit);
+    return { reportPath: path.resolve(targetPath, explicit), outputFs: fsp };
   }
 
-  const outputRoot = await resolveOutputRoot({
+  const { outputRoot, outputFs } = await resolveOutputContext({
     cwd: targetPath,
     outputDirOverride,
     env: process.env,
   });
-  return path.join(outputRoot, "reports", `scan-precheck-${createTimestampToken()}.md`);
+  return { reportPath: path.join(outputRoot, "reports", `scan-precheck-${createTimestampToken()}.md`), outputFs };
 }
 
 function printAiPreScanSummary({ reportPath, ai }) {
@@ -610,13 +610,13 @@ export function registerScanCommand(program) {
         model: response.model,
         aiMarkdown,
       });
-      const reportPath = await resolvePreScanReportPath({
+      const { reportPath, outputFs } = await resolvePreScanReportPath({
         targetPath,
         outputDirOverride: options.outputDir,
         outputFile: options.outputFile,
       });
-      await fsp.mkdir(path.dirname(reportPath), { recursive: true });
-      await fsp.writeFile(reportPath, reportMarkdown, "utf-8");
+      await outputFs.mkdir(path.dirname(reportPath), { recursive: true });
+      await outputFs.writeFile(reportPath, reportMarkdown, "utf-8");
 
       const estimatedInputTokens = estimateTokens(prompt, { model: response.model });
       const estimatedOutputTokens = estimateTokens(aiMarkdown, { model: response.model });