sentinelayer-cli 0.46.5 → 0.48.0

package/src/commands/skills.js

@@ -0,0 +1,45 @@
+import { installSkills, listSkills } from "../skills/service.js";
+
+export function registerSkillsCommand(program) {
+  const skills = program.command("skills").description("Install and inspect bundled Senti agent skills");
+  for (const action of ["install", "list"]) {
+    const command = skills.command(action === "install" ? "install [names...]" : action)
+      .description(action === "install"
+        ? "Install bundled skills (all, or only the named ones) without replacing local edits"
+        : "List bundled and installed skill versions and SHA-256 hashes")
+      .option("--dir <path>", "Skills directory (default: ~/.claude/skills)")
+      .option("--json", "Emit machine-readable output");
+    if (action === "install") command.option("--force", "Replace differing local files");
+    command.action(async (...args) => {
+      const invoked = args.at(-1);
+      const options = args.at(-2);
+      const names = action === "install" ? args[0] : undefined;
+      const json = Boolean(invoked.optsWithGlobals().json);
+      try {
+        const result = await (action === "install" ? installSkills({ ...options, names }) : listSkills(options));
+        if (json) {
+          console.log(JSON.stringify({ command: `skills ${action}`, ...result }, null, 2));
+          return;
+        }
+        console.log(`Skills directory: ${result.directory}`);
+        for (const skill of result.skills) {
+          if (action === "install") {
+            console.log(`${skill.name} ${skill.version}: ${skill.written} written, ${skill.unchanged} unchanged (sha256 ${skill.hash})`);
+          } else {
+            console.log(`${skill.name}: ${skill.status}`);
+            console.log(`  bundled: ${skill.bundled.version} sha256 ${skill.bundled.hash}`);
+            console.log(skill.installed ? `  installed: ${skill.installed.version || "unknown"} sha256 ${skill.installed.hash}` : "  installed: none");
+            if (skill.error) console.log(`  error: ${skill.error}`);
+          }
+        }
+      } catch (error) {
+        if (json) console.log(JSON.stringify({ command: `skills ${action}`, error: {
+          code: error.code || "SKILLS_ERROR", message: error.message,
+          ...(error.files ? { files: error.files } : {}),
+        } }, null, 2));
+        else console.error(error.message);
+        process.exitCode = 1;
+      }
+    });
+  }
+}

package/src/commands/watch.js

@@ -11,7 +11,8 @@ import {
   listRuntimeRunEvents,
   resolveActiveAuthSession,
 } from "../auth/service.js";
-import { resolveOutputRoot } from "../config/service.js";
+import { resolveOutputRoot, resolveOutputContext } from "../config/service.js";
+import { bindOutputFileSystem, requireOutputFileSystem } from "../config/output-filesystem.js";
 import { authLoginHint } from "../ui/command-hints.js";
 import { isAuthenticated } from "../auth/credential-destinations.js";
 
@@ -254,11 +255,12 @@ async function resolveWatchArtifacts({
   if (!enabled) {
     return null;
   }
-  const outputRoot = await resolveOutputRoot({
+  const { outputRoot, outputFs } = await resolveOutputContext({
     cwd: targetPath,
     outputDirOverride: outputDir,
     env: process.env,
   });
+  requireOutputFileSystem(outputFs);
   const watchStamp = stableTimestampForFile();
   const watchDir = path.join(
     outputRoot,
@@ -266,12 +268,12 @@ async function resolveWatchArtifacts({
     "runtime-watch",
     sanitizePathSegment(runId)
   );
-  await fsp.mkdir(watchDir, { recursive: true });
-  return {
+  await outputFs.mkdir(watchDir, { recursive: true });
+  return bindOutputFileSystem({
     watchDir,
     eventsPath: path.join(watchDir, `events-${watchStamp}.ndjson`),
     summaryPath: path.join(watchDir, `summary-${watchStamp}.json`),
-  };
+  }, outputFs);
 }
 
 export function registerWatchCommand(program) {
@@ -411,7 +413,7 @@ export function registerWatchCommand(program) {
             eventCount += 1;
 
             if (artifactPaths?.eventsPath) {
-              await fsp.appendFile(artifactPaths.eventsPath, `${JSON.stringify(event)}\n`, "utf-8");
+              await artifactPaths.outputFs.appendFile(artifactPaths.eventsPath, `${JSON.stringify(event)}\n`, "utf-8");
             }
 
             if (emitJson) {
@@ -478,7 +480,7 @@ export function registerWatchCommand(program) {
       };
 
       if (artifactPaths?.summaryPath) {
-        await fsp.writeFile(artifactPaths.summaryPath, `${JSON.stringify(summary, null, 2)}\n`, "utf-8");
+        await artifactPaths.outputFs.writeFile(artifactPaths.summaryPath, `${JSON.stringify(summary, null, 2)}\n`, "utf-8");
       }
 
       if (emitJson) {

package/src/config/output-filesystem.js

@@ -0,0 +1,156 @@
+import fsp from "node:fs/promises";
+import { constants } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const outputCapabilities = new WeakSet();
+
+/** Writers accept only a capability created for this operation's output policy. */
+export function requireOutputFileSystem(outputFs) {
+  if (!outputCapabilities.has(outputFs)) {
+    throw new TypeError("An output filesystem capability is required for artifact writes.");
+  }
+  return outputFs;
+}
+
+function isInside(root, candidate) {
+  const relative = path.relative(root, candidate);
+  return relative === "" || (relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
+}
+
+/** Validate the complete destination, including an existing final-file link. */
+export async function assertWorkspaceOutputPath(destination, workspaceRoot) {
+  try {
+    const value = destination instanceof URL ? fileURLToPath(destination) : destination;
+    if (typeof value !== "string") throw new Error("Unverifiable artifact destination");
+    const root = path.resolve(workspaceRoot);
+    const candidate = path.resolve(value);
+    if (!isInside(root, candidate)) throw new Error("Artifact outside workspace");
+    const realRoot = await fsp.realpath(root);
+    let ancestor = candidate;
+    for (;;) {
+      let resolved;
+      try {
+        resolved = await fsp.realpath(ancestor);
+      } catch (error) {
+        if (error.code !== "ENOENT") throw error;
+        const entry = await fsp.lstat(ancestor).catch((statError) => {
+          if (statError.code !== "ENOENT") throw statError;
+          return null;
+        });
+        if (entry) {
+          if (entry.isSymbolicLink()) throw new Error("Unresolved artifact link");
+          // A concurrent artifact writer may have created this ordinary entry
+          // after realpath saw ENOENT. Resolve it once, then apply the same real
+          // workspace check below; never treat its mere existence as authority.
+          resolved = await fsp.realpath(ancestor);
+        } else {
+          const parent = path.dirname(ancestor);
+          if (parent === ancestor) throw error;
+          ancestor = parent;
+          continue;
+        }
+      }
+      if (!isInside(realRoot, path.resolve(resolved, path.relative(ancestor, candidate)))) {
+        throw new Error("Artifact link leaves workspace");
+      }
+      return candidate;
+    }
+  } catch {
+    throw new Error("Workspace artifact destination must resolve inside the workspace.");
+  }
+}
+
+/** Per-operation capability; never stored in a process-global path registry. */
+export function createOutputFileSystem({ workspaceRoot = null } = {}) {
+  workspaceRoot = workspaceRoot ? path.resolve(workspaceRoot) : null;
+  const assertPath = async (destination) => {
+    if (workspaceRoot) return assertWorkspaceOutputPath(destination, workspaceRoot);
+    return destination;
+  };
+  const assertFilePath = async (destination) => {
+    const checked = await assertPath(destination);
+    if (workspaceRoot) {
+      const entry = await fsp.lstat(checked).catch((error) => {
+        if (error.code !== "ENOENT") throw new Error("Workspace artifact destination must resolve inside the workspace.");
+        return null;
+      });
+      if (entry?.isSymbolicLink() || (entry?.isFile() && entry.nlink > 1)) {
+        throw new Error("Workspace artifact destination must resolve inside the workspace without linked files.");
+      }
+    }
+    return checked;
+  };
+  // Expose only read operations and the mutations guarded below. Adding a new
+  // writer must not silently inherit an unchecked fs/promises method.
+  const io = { assertPath, assertFilePath };
+  for (const method of ["access", "readFile", "readdir", "readlink", "realpath", "stat", "lstat", "statfs", "opendir"]) {
+    io[method] = fsp[method];
+  }
+  for (const method of ["mkdir", "rm", "unlink", "truncate"]) {
+    io[method] = async (destination, ...args) => {
+      const checked = await (method === "mkdir" ? assertPath(destination) : assertFilePath(destination));
+      return fsp[method](checked, ...args);
+    };
+  }
+  for (const method of ["rename", "copyFile"]) {
+    io[method] = async (source, destination, ...args) => {
+      const checkedSource = method === "rename" ? await assertFilePath(source) : source;
+      const checkedDestination = await assertFilePath(destination);
+      return fsp[method](checkedSource, checkedDestination, ...args);
+    };
+  }
+  io.open = async (destination, flags, ...args) => {
+    const writeFlags = constants.O_WRONLY | constants.O_RDWR | constants.O_CREAT | constants.O_APPEND | constants.O_TRUNC;
+    if (typeof flags === "number" ? Boolean(flags & writeFlags) : /[wa+]/.test(flags || "r")) {
+      const checked = await assertFilePath(destination);
+      return fsp.open(checked, workspaceRoot ? numericOpenFlags(flags) | (constants.O_NOFOLLOW || 0) : flags, ...args);
+    }
+    return fsp.open(destination, flags, ...args);
+  };
+  for (const method of ["writeFile", "appendFile"]) {
+    io[method] = async (destination, data, options) => {
+      if (!workspaceRoot) return fsp[method](destination, data, options);
+      if (options !== undefined && options !== null && typeof options !== "string" && typeof options !== "object") {
+        throw new TypeError("Artifact file options must be an encoding string or an object.");
+      }
+      const normalizedOptions = typeof options === "string" ? { encoding: options } : options || {};
+      const flag = normalizedOptions.flag || (method === "appendFile" ? "a" : "w");
+      const checked = await assertFilePath(destination);
+      return fsp[method](checked, data, {
+        ...normalizedOptions,
+        flag: numericOpenFlags(flag) | (constants.O_NOFOLLOW || 0),
+      });
+    };
+  }
+  outputCapabilities.add(io);
+  return Object.freeze(io);
+}
+
+function numericOpenFlags(flags) {
+  if (typeof flags === "number") return flags;
+  const { O_RDONLY, O_WRONLY, O_RDWR, O_CREAT, O_TRUNC, O_APPEND, O_EXCL, O_SYNC } = constants;
+  const modes = {
+    r: O_RDONLY, rs: O_RDONLY | O_SYNC, sr: O_RDONLY | O_SYNC,
+    "r+": O_RDWR, "rs+": O_RDWR | O_SYNC, "sr+": O_RDWR | O_SYNC,
+    w: O_TRUNC | O_CREAT | O_WRONLY, wx: O_TRUNC | O_CREAT | O_WRONLY | O_EXCL,
+    xw: O_TRUNC | O_CREAT | O_WRONLY | O_EXCL,
+    "w+": O_TRUNC | O_CREAT | O_RDWR, "wx+": O_TRUNC | O_CREAT | O_RDWR | O_EXCL,
+    "xw+": O_TRUNC | O_CREAT | O_RDWR | O_EXCL,
+    a: O_APPEND | O_CREAT | O_WRONLY, ax: O_APPEND | O_CREAT | O_WRONLY | O_EXCL,
+    xa: O_APPEND | O_CREAT | O_WRONLY | O_EXCL,
+    "a+": O_APPEND | O_CREAT | O_RDWR, "ax+": O_APPEND | O_CREAT | O_RDWR | O_EXCL,
+    "xa+": O_APPEND | O_CREAT | O_RDWR | O_EXCL,
+    as: O_APPEND | O_CREAT | O_WRONLY | O_SYNC, sa: O_APPEND | O_CREAT | O_WRONLY | O_SYNC,
+    "as+": O_APPEND | O_CREAT | O_RDWR | O_SYNC, "sa+": O_APPEND | O_CREAT | O_RDWR | O_SYNC,
+  };
+  if (!Object.hasOwn(modes, flags)) throw new TypeError("Unsupported artifact file open flag.");
+  return modes[flags];
+}
+
+// Storage objects are often returned as JSON. Keep the executable capability
+// out of that public data shape while allowing explicit downstream propagation.
+export function bindOutputFileSystem(storage, outputFs) {
+  Object.defineProperty(storage, "outputFs", { value: requireOutputFileSystem(outputFs), enumerable: false });
+  return storage;
+}

package/src/config/schema.js

@@ -8,8 +8,10 @@ function emptyToUndefined(value) {
   return normalized ? normalized : undefined;
 }
 
-const optionalTrimmedString = z.preprocess(emptyToUndefined, z.string().min(1)).optional();
-const optionalUrl = z.preprocess(emptyToUndefined, z.string().url()).optional();
+// optional() sits inside preprocess: zod >=4.2 validates the preprocessed value, so a blank value
+// mapped to undefined must be accepted by the inner schema, not only by an outer optional().
+const optionalTrimmedString = z.preprocess(emptyToUndefined, z.string().min(1).optional());
+const optionalUrl = z.preprocess(emptyToUndefined, z.string().url().optional());
 const optionalStringArray = z
   .array(z.preprocess(emptyToUndefined, z.string().min(1)))
   .optional();

package/src/config/service.js

@@ -4,6 +4,7 @@ import path from "node:path";
 import { getConfigPaths } from "./paths.js";
 import { ensureConfigFile, readConfigFile, writeConfigFile } from "./io.js";
 import { CONFIG_KEYS, configSchema } from "./schema.js";
+import { assertWorkspaceOutputPath, createOutputFileSystem } from "./output-filesystem.js";
 
 const ENV_MAPPING = Object.freeze({
   SENTINELAYER_API_URL: "apiUrl",
@@ -200,7 +201,38 @@ export function listConfigKeys() {
   return [...CONFIG_KEYS];
 }
 
-export async function resolveOutputRoot({
+function isInsideRoot(root, candidate) {
+  const relative = path.relative(root, candidate);
+  return relative === "" || (relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
+}
+
+// Every workspace-local output is confined, regardless of where its setting came
+// from. Only an explicit absolute trusted-layer path outside the workspace opts out.
+async function resolveOutputSelection(value, cwd, { project = false } = {}) {
+  try {
+    const root = path.resolve(cwd);
+    const absolute = path.isAbsolute(value);
+    const foreignAbsolute = path.win32.isAbsolute(value) || /^[A-Za-z]:/.test(value);
+    if ((project && (absolute || foreignAbsolute)) || (!absolute && foreignAbsolute)) throw new Error();
+    const candidate = path.resolve(root, value);
+    if (absolute && !isInsideRoot(root, candidate)) {
+      return { outputRoot: candidate, outputFs: createOutputFileSystem() };
+    }
+    // Backslash escapes remain rejected on POSIX as well, so config is portable.
+    if (!isInsideRoot(root, candidate) || !isInsideRoot(root, path.resolve(root, value.replace(/\\/g, "/")))) {
+      throw new Error();
+    }
+    return {
+      outputRoot: await assertWorkspaceOutputPath(candidate, root),
+      outputFs: createOutputFileSystem({ workspaceRoot: root }),
+    };
+  } catch {
+    // Do not echo private configuration values or filesystem errors containing their paths.
+    throw new Error("Workspace outputDir must resolve to a relative path inside the workspace.");
+  }
+}
+
+export async function resolveOutputContext({
   cwd = process.cwd(),
   outputDirOverride = "",
   env = process.env,
@@ -208,14 +240,18 @@ export async function resolveOutputRoot({
 } = {}) {
   const overrideValue = String(outputDirOverride || "").trim();
   if (overrideValue) {
-    return path.resolve(cwd, overrideValue);
+    return resolveOutputSelection(overrideValue, cwd);
   }
 
   const config = await loadConfig({ cwd, env, homeDir });
   const configuredOutputDir = String(config.resolved.outputDir || "").trim();
   if (configuredOutputDir) {
-    return path.resolve(cwd, configuredOutputDir);
+    return resolveOutputSelection(configuredOutputDir, cwd, { project: findConfigSource(config, "outputDir") === "project" });
   }
 
-  return path.resolve(cwd, ".sentinelayer");
+  return resolveOutputSelection(".sentinelayer", cwd);
+}
+
+export async function resolveOutputRoot(options = {}) {
+  return (await resolveOutputContext(options)).outputRoot;
 }

package/src/cost/history.js

@@ -1,8 +1,9 @@
+import { requireOutputFileSystem } from "../config/output-filesystem.js";
 import fsp from "node:fs/promises";
 import path from "node:path";
 import { randomUUID } from "node:crypto";
 
-import { resolveOutputRoot } from "../config/service.js";
+import { resolveOutputContext } from "../config/service.js";
 import { rollupUsage } from "./tracker.js";
 
 const HISTORY_VERSION = 1;
@@ -60,19 +61,23 @@ function normalizeEntry(entry) {
   };
 }
 
-export async function resolveCostHistoryPath({
+async function resolveCostHistoryOutput({
   targetPath = ".",
   outputDirOverride = "",
   env,
   homeDir,
 } = {}) {
-  const outputRoot = await resolveOutputRoot({
+  const { outputRoot, outputFs } = await resolveOutputContext({
     cwd: path.resolve(targetPath),
     outputDirOverride,
     env,
     homeDir,
   });
-  return path.join(outputRoot, HISTORY_FILE_NAME);
+  return { filePath: path.join(outputRoot, HISTORY_FILE_NAME), outputFs };
+}
+
+export async function resolveCostHistoryPath(options = {}) {
+  return (await resolveCostHistoryOutput(options)).filePath;
 }
 
 export async function loadCostHistory(options = {}) {
@@ -106,25 +111,26 @@ async function readCostHistoryFile(filePath) {
   }
 }
 
-export async function saveCostHistory({ filePath, history }) {
+export async function saveCostHistory({ filePath, history, outputFs }) {
+  requireOutputFileSystem(outputFs);
   const payload = {
     version: HISTORY_VERSION,
     entries: Array.isArray(history?.entries) ? history.entries : [],
   };
-  await fsp.mkdir(path.dirname(filePath), { recursive: true });
-  await fsp.writeFile(filePath, `${JSON.stringify(payload, null, 2)}\n`, "utf-8");
+  await outputFs.mkdir(path.dirname(filePath), { recursive: true });
+  await outputFs.writeFile(filePath, `${JSON.stringify(payload, null, 2)}\n`, "utf-8");
 }
 
 export async function appendCostEntry(options = {}, entry = {}) {
   const normalizedEntry = normalizeEntry(entry);
-  const filePath = await resolveCostHistoryPath(options);
+  const { filePath, outputFs } = await resolveCostHistoryOutput(options);
   return withCostHistoryWriteQueue(filePath, async () => {
     const history = await readCostHistoryFile(filePath);
     const nextHistory = {
       version: HISTORY_VERSION,
       entries: [...history.entries, normalizedEntry],
     };
-    await saveCostHistory({ filePath, history: nextHistory });
+    await saveCostHistory({ filePath, history: nextHistory, outputFs });
     return {
       filePath,
       entry: normalizedEntry,

package/src/daemon/artifact-lineage.js

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import fsp from "node:fs/promises";
 import path from "node:path";
 
+import { bindOutputFileSystem, requireOutputFileSystem } from "../config/output-filesystem.js";
 import { listAssignments, resolveAssignmentLedgerStorage } from "./assignment-ledger.js";
 import { getBudgetHealthColor, resolveOperatorControlStorage } from "./operator-control.js";
 import { listBudgetStates, resolveBudgetGovernorStorage } from "./budget-governor.js";
@@ -215,7 +216,7 @@ export async function writeCloseoutArtifact({
   });
   const dateKey = normalizeDateKey(date, normalizedNow);
   const artifactDir = resolveWorkItemArtifactDir(storage, normalizedWorkItemId, dateKey);
-  await fsp.mkdir(artifactDir, { recursive: true });
+  await storage.outputFs.mkdir(artifactDir, { recursive: true });
   const closeoutPath = path.join(artifactDir, "closeout.json");
 
   const entries = await fsp.readdir(artifactDir, { withFileTypes: true }).catch((error) => {
@@ -273,7 +274,7 @@ export async function writeCloseoutArtifact({
     ),
     anchorSha256,
   };
-  await writeJsonFile(closeoutPath, payload);
+  await writeJsonFile(closeoutPath, payload, storage.outputFs);
   return {
     closeoutPath,
     payload,
@@ -390,14 +391,16 @@ export async function verifyArtifactChain({
   };
 }
 
-async function writeJsonFile(filePath, payload = {}) {
-  await fsp.mkdir(path.dirname(filePath), { recursive: true });
-  await fsp.writeFile(filePath, `${JSON.stringify(payload, null, 2)}\n`, "utf-8");
+async function writeJsonFile(filePath, payload = {}, outputFs) {
+  requireOutputFileSystem(outputFs);
+  await outputFs.mkdir(path.dirname(filePath), { recursive: true });
+  await outputFs.writeFile(filePath, `${JSON.stringify(payload, null, 2)}\n`, "utf-8");
 }
 
-async function appendJsonLine(filePath, payload = {}) {
-  await fsp.mkdir(path.dirname(filePath), { recursive: true });
-  await fsp.appendFile(filePath, `${JSON.stringify(payload)}\n`, "utf-8");
+async function appendJsonLine(filePath, payload = {}, outputFs) {
+  requireOutputFileSystem(outputFs);
+  await outputFs.mkdir(path.dirname(filePath), { recursive: true });
+  await outputFs.appendFile(filePath, `${JSON.stringify(payload)}\n`, "utf-8");
 }
 
 async function readJsonFile(filePath, fallbackValue) {
@@ -518,12 +521,12 @@ export async function resolveArtifactLineageStorage({
     homeDir,
   });
   const lineageDir = path.join(daemonStorage.baseDir, "lineage");
-  return {
+  return bindOutputFileSystem({
     ...daemonStorage,
     lineageDir,
     lineageIndexPath: path.join(lineageDir, "lineage-index.json"),
     lineageEventsPath: path.join(lineageDir, "lineage-events.ndjson"),
-  };
+  }, daemonStorage.outputFs);
 }
 
 export async function buildArtifactLineageIndex({
@@ -799,7 +802,7 @@ export async function buildArtifactLineageIndex({
   };
 
   await Promise.all([
-    writeJsonFile(storage.lineageIndexPath, index),
+    writeJsonFile(storage.lineageIndexPath, index, storage.outputFs),
     appendJsonLine(storage.lineageEventsPath, {
       timestamp: normalizedNow,
       eventType: "lineage_build",
@@ -809,7 +812,7 @@ export async function buildArtifactLineageIndex({
       jiraLinkedCount,
       budgetGuardedCount,
       operatorCoveredCount,
-    }),
+    }, storage.outputFs),
   ]);
 
   return {

package/src/daemon/assignment-ledger.js

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import fsp from "node:fs/promises";
 import path from "node:path";
 
+import { bindOutputFileSystem, requireOutputFileSystem } from "../config/output-filesystem.js";
 import { WORK_ITEM_STATUSES, resolveErrorDaemonStorage } from "./error-worker.js";
 
 const LEDGER_SCHEMA_VERSION = "1.0.0";
@@ -170,14 +171,16 @@ async function loadJsonFile(filePath, defaultFactory) {
   }
 }
 
-async function writeJsonFile(filePath, payload = {}) {
-  await fsp.mkdir(path.dirname(filePath), { recursive: true });
-  await fsp.writeFile(filePath, `${JSON.stringify(payload, null, 2)}\n`, "utf-8");
+async function writeJsonFile(filePath, payload = {}, outputFs) {
+  requireOutputFileSystem(outputFs);
+  await outputFs.mkdir(path.dirname(filePath), { recursive: true });
+  await outputFs.writeFile(filePath, `${JSON.stringify(payload, null, 2)}\n`, "utf-8");
 }
 
-async function appendEvent(filePath, payload = {}) {
-  await fsp.mkdir(path.dirname(filePath), { recursive: true });
-  await fsp.appendFile(filePath, `${JSON.stringify(payload)}\n`, "utf-8");
+async function appendEvent(filePath, payload = {}, outputFs) {
+  requireOutputFileSystem(outputFs);
+  await outputFs.mkdir(path.dirname(filePath), { recursive: true });
+  await outputFs.appendFile(filePath, `${JSON.stringify(payload)}\n`, "utf-8");
 }
 
 async function loadLedger(ledgerPath, nowIso = new Date().toISOString()) {
@@ -193,7 +196,8 @@ async function loadLedger(ledgerPath, nowIso = new Date().toISOString()) {
   };
 }
 
-async function writeLedger(ledgerPath, ledger = {}, nowIso = new Date().toISOString()) {
+async function writeLedger(ledgerPath, ledger = {}, nowIso = new Date().toISOString(), outputFs) {
+  requireOutputFileSystem(outputFs);
   const normalized = {
     schemaVersion: LEDGER_SCHEMA_VERSION,
     generatedAt: normalizeIsoTimestamp(nowIso, nowIso),
@@ -203,7 +207,7 @@ async function writeLedger(ledgerPath, ledger = {}, nowIso = new Date().toISOStr
           .filter((record) => normalizeString(record.workItemId))
       : [],
   };
-  await writeJsonFile(ledgerPath, normalized);
+  await writeJsonFile(ledgerPath, normalized, outputFs);
   return normalized;
 }
 
@@ -218,7 +222,8 @@ async function loadQueue(queuePath, nowIso = new Date().toISOString()) {
   };
 }
 
-async function writeQueue(queuePath, queue = {}, nowIso = new Date().toISOString()) {
+async function writeQueue(queuePath, queue = {}, nowIso = new Date().toISOString(), outputFs) {
+  requireOutputFileSystem(outputFs);
   const normalized = {
     schemaVersion: QUEUE_SCHEMA_VERSION,
     generatedAt: normalizeIsoTimestamp(nowIso, nowIso),
@@ -226,16 +231,17 @@ async function writeQueue(queuePath, queue = {}, nowIso = new Date().toISOString
       ? queue.items.map((item) => normalizeQueueItem(item, nowIso)).filter((item) => item.workItemId)
       : [],
   };
-  await writeJsonFile(queuePath, normalized);
+  await writeJsonFile(queuePath, normalized, outputFs);
   return normalized;
 }
 
 function getAssignmentStoragePaths(baseStorage = {}) {
-  return {
+  requireOutputFileSystem(baseStorage.outputFs);
+  return bindOutputFileSystem({
     ...baseStorage,
     ledgerPath: path.join(baseStorage.baseDir, "assignment-ledger.json"),
     eventsPath: path.join(baseStorage.baseDir, "assignment-events.ndjson"),
-  };
+  }, baseStorage.outputFs);
 }
 
 async function loadLedgerAndQueue(storage, nowIso) {
@@ -436,8 +442,8 @@ export async function claimAssignment({
   });
 
   const [savedLedger, savedQueue] = await Promise.all([
-    writeLedger(storage.ledgerPath, ledger, normalizedNow),
-    writeQueue(storage.queuePath, queue, normalizedNow),
+    writeLedger(storage.ledgerPath, ledger, normalizedNow, storage.outputFs),
+    writeQueue(storage.queuePath, queue, normalizedNow, storage.outputFs),
   ]);
 
   await appendEvent(storage.eventsPath, {
@@ -451,7 +457,7 @@ export async function claimAssignment({
     stage: normalizeString(stage) || "triage",
     runId: normalizeString(runId) || null,
     jiraIssueKey: normalizeString(jiraIssueKey) || null,
-  });
+  }, storage.outputFs);
 
   return {
     ...storage,
@@ -537,8 +543,8 @@ export async function heartbeatAssignment({
   });
 
   const [savedLedger, savedQueue] = await Promise.all([
-    writeLedger(storage.ledgerPath, ledger, normalizedNow),
-    writeQueue(storage.queuePath, queue, normalizedNow),
+    writeLedger(storage.ledgerPath, ledger, normalizedNow, storage.outputFs),
+    writeQueue(storage.queuePath, queue, normalizedNow, storage.outputFs),
   ]);
 
   await appendEvent(storage.eventsPath, {
@@ -549,7 +555,7 @@ export async function heartbeatAssignment({
     agentIdentity: normalizedAgentIdentity,
     stage: next.stage,
     leaseExpiresAt,
-  });
+  }, storage.outputFs);
 
   return {
     ...storage,
@@ -638,8 +644,8 @@ export async function releaseAssignment({
   });
 
   const [savedLedger, savedQueue] = await Promise.all([
-    writeLedger(storage.ledgerPath, ledger, normalizedNow),
-    writeQueue(storage.queuePath, queue, normalizedNow),
+    writeLedger(storage.ledgerPath, ledger, normalizedNow, storage.outputFs),
+    writeQueue(storage.queuePath, queue, normalizedNow, storage.outputFs),
   ]);
 
   await appendEvent(storage.eventsPath, {
@@ -650,7 +656,7 @@ export async function releaseAssignment({
     agentIdentity: next.assignedAgentIdentity,
     status: normalizedStatus,
     reason: next.releaseReason,
-  });
+  }, storage.outputFs);
 
   return {
     ...storage,
@@ -746,8 +752,8 @@ export async function reassignAssignment({
   });
 
   const [savedLedger, savedQueue] = await Promise.all([
-    writeLedger(storage.ledgerPath, ledger, normalizedNow),
-    writeQueue(storage.queuePath, queue, normalizedNow),
+    writeLedger(storage.ledgerPath, ledger, normalizedNow, storage.outputFs),
+    writeQueue(storage.queuePath, queue, normalizedNow, storage.outputFs),
   ]);
 
   await appendEvent(storage.eventsPath, {
@@ -760,7 +766,7 @@ export async function reassignAssignment({
     leaseTtlSeconds: normalizedTtl,
     leaseExpiresAt,
     stage: next.stage,
-  });
+  }, storage.outputFs);
 
   return {
     ...storage,
@@ -1073,7 +1079,7 @@ export async function ensureWorkItemQueued({
     queue.items.push(normalizedItem);
   }
 
-  const savedQueue = await writeQueue(storage.queuePath, queue, normalizedNow);
+  const savedQueue = await writeQueue(storage.queuePath, queue, normalizedNow, storage.outputFs);
   const queueItem = savedQueue.items.find((item) => item.workItemId === normalizedWorkItemId) || normalizedItem;
   return {
     ...storage,