sentinelayer-cli 0.46.5 → 0.48.0

package/src/session/tickets.js

@@ -207,6 +207,47 @@ export async function ticketEvents(
   });
 }
 
+/** Create with an explicit acting agent claim; the API authorizes it, never a createdBy body. */
+export async function createTicket(sessionId, {
+  title, body = "", agentId = "", assignee = "", sourceSequenceId = null,
+  idempotencyKey = `ticket-create-${randomUUID()}`, targetPath = process.cwd(),
+  resolveAuthSession = resolveActiveAuthSession, requestMutation = requestJsonMutation,
+} = {}) {
+  const cleanTitle = normalizeString(title), cleanAgent = normalizeString(agentId);
+  if (!cleanTitle || [...cleanTitle].length > 200 || typeof body !== "string" || [...body].length > 8000) throw new Error("Ticket title/body exceeds its limits.");
+  if (cleanAgent && !/^[a-zA-Z0-9._:-]{1,64}$/.test(cleanAgent)) throw new Error("Invalid agent identity.");
+  if (sourceSequenceId !== null && (!Number.isSafeInteger(sourceSequenceId) || sourceSequenceId < 1)) throw new Error("Invalid source sequence.");
+  if (typeof idempotencyKey !== "string" || !idempotencyKey.trim() || idempotencyKey.length > 128) throw new Error("Invalid idempotency key.");
+  const { credential, apiUrl } = await auth(targetPath, resolveAuthSession);
+  try {
+    const ticket = await mutate(ticketsUrl(apiUrl, sessionId), { credential, key: idempotencyKey, operation: "create", requestMutation,
+      body: { title: cleanTitle, body, ...(cleanAgent ? { agentId: cleanAgent } : {}),
+        ...(normalizeString(assignee) ? { assignee: normalizeString(assignee) } : {}),
+        ...(sourceSequenceId !== null ? { sourceSequenceId } : {}) },
+    });
+    if (typeof ticket?.id !== "string" || !ticket.id.trim()) {
+      throw new Error("The API returned no usable ticket identity; creation may have committed.");
+    }
+    // The public API projects server-authored creator/sourceMessage. Legacy
+    // createdBy and a top-level sourceSequenceId do not establish that provenance.
+    // Keep the returned ticket and retry key even when confirmation is incomplete.
+    const creator = ticket?.creator;
+    const source = ticket?.sourceMessage;
+    const provenance = {
+      agentRequested: cleanAgent || null,
+      agentRecorded: Boolean(cleanAgent) && creator?.kind === "agent" && creator.id === cleanAgent,
+      sourceRequested: sourceSequenceId,
+      sourceRecorded: sourceSequenceId !== null && source?.sequenceId === sourceSequenceId
+        && typeof source.id === "string" && /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i.test(source.id)
+        && Number.isSafeInteger(source.revision) && source.revision >= 1,
+    };
+    return { ticket, idempotencyKey, provenance };
+  } catch (error) {
+    // Retain the logical write's retry key even if the server committed but the response was lost.
+    throw new Error(`${error.message || "Ticket creation failed"} (retry with --idempotency-key ${idempotencyKey})`, { cause: error });
+  }
+}
+
 async function mutate(url, { credential, key, operation, body, requestMutation }) {
   return checkedTransport(requestMutation)(url, {
     method: "POST",

package/src/session/transcript.js

@@ -20,6 +20,7 @@
 
 import { PERSONA_VISUALS, ORCHESTRATOR_VISUALS } from "../agents/persona-visuals.js";
 import { buildSessionUsageLedger } from "./pricing-ledger.js";
+import { appendAttachmentSummary } from "./attachment-summary.js";
 
 /**
  * Avatar map for client families (the OUTSIDE-the-persona-set agents
@@ -720,7 +721,7 @@ export function buildTranscriptMarkdown({
       profile,
     });
     const ts = eventTimestamp(event);
-    const body = eventBody(event);
+    const body = appendAttachmentSummary(eventBody(event), { sessionId, ...event });
 
     if (SYSTEM_EVENT_KINDS.has(kind)) {
       const hint = body || kind.replace(/_/g, " ");

package/src/session/wake/resolve-target.js

@@ -17,6 +17,7 @@
 // here is small enough to own.
 
 import { messageRevision, sessionMessageEditSnapshot, sessionMessageRoutingEvent } from "../message-edits.js";
+import { formatAttachmentSummary } from "../attachment-summary.js";
 
 const BROADCAST_RECIPIENTS = new Set(["*", "all", "broadcast", "everyone", "anyone", "agents", "all-agents"]);
 const DEFAULT_WAKE_EVENT_TYPES = new Set(["session_message", "help_request", "session_message_edited"]);
@@ -100,9 +101,12 @@ function defaultFormatMessage(event, agentId) {
   const author = agentIdOf(event) || "unknown";
   const text = event?.payload?.message ?? event?.message ?? "";
   const body = typeof text === "string" ? text : "";
-  const head = `Senti wake for ${agentId}: ${event.event === "session_message_edited" ? "edited message" : "new message"} from ${author}.`;
-  const combined = body ? `${head}\n\n${body}` : head;
-  return combined.length > MAX_WAKE_MESSAGE_CHARS ? combined.slice(0, MAX_WAKE_MESSAGE_CHARS) : combined;
+  const head = `Senti wake for ${agentId}: ${event.event === "session_message_edited" ? "edited message" : "new message"} from ${author}.`
+    .slice(0, MAX_WAKE_MESSAGE_CHARS);
+  const attachmentBudget = Math.max(0, MAX_WAKE_MESSAGE_CHARS - head.length - 2);
+  const attachments = formatAttachmentSummary(event).slice(0, attachmentBudget);
+  const bodyBudget = Math.max(0, MAX_WAKE_MESSAGE_CHARS - head.length - 2 - (attachments ? attachments.length + 2 : 0));
+  return [head, body.slice(0, bodyBudget), attachments].filter(Boolean).join("\n\n");
 }
 
 /**

package/src/skills/listener-runtime.cjs

@@ -0,0 +1,92 @@
+const { spawn, execFile } = require("node:child_process");
+const readline = require("node:readline");
+
+// Process lifecycle for the bundled notification wrapper. Commands use argv, never a shell.
+function runListener({ me: ME, sessionId: SID, cliPath: CLI, cwd: CWD, pollCwd: POLL_CWD, wake: WAKE = null, classifier }) {
+  const { deliver, observe, rememberMine, newerThanDelivered, flushBroadcasts } = classifier;
+  const { hadReceiptAtBoot } = classifier.state();
+  let restarts = 0;
+  let startedAt = 0;
+
+  function wanted(who) {
+    if (who === ME) return false;
+    return WAKE === null || WAKE.has(who);
+  }
+
+  function handle(line) {
+    let e;
+    try { e = JSON.parse(line); } catch {
+      if (/error|Error|refused|403|401|stopped|wedged/i.test(line)) console.log("[raw] " + line.slice(0, 300));
+      return;
+    }
+    const ev = e.event || "";
+    const who = (e.agent && e.agent.id) || e.agentId || "?";
+    if (who !== ME && (ev === "session_message" || ev === "session_reply")) observe(e.ts);
+    if (who === ME) rememberMine(e.sequenceId);
+    if (!wanted(who)) return;
+    const p = e.payload || {};
+    if (ev === "session_message" || ev === "session_reply") {
+      const text = (p.message || p.note || "").replace(/\s+/g, " ");
+      deliver(ev, who, e.ts, e.sequenceId, p.replyToSequenceId || p.targetSequenceId, text);
+    } else if (ev === "daemon_alert" && p.alert && /human|directive|mention|assign|lock|stuck/i.test(p.alert) && (!p.targetAgentId || p.targetAgentId === ME)) {
+      console.log(`[alert] ${p.alert} ${p.targetAgentId || ""} ${(p.message || "").slice(0, 200)}`);
+    }
+  }
+
+  function start() {
+    startedAt = Date.now();
+    const p = spawn(process.execPath, [CLI, "session", "listen", "--session", SID, "--agent", ME,
+      "--active-interval", "15", "--active-window", "600", "--interval", "15", "--presence-interval", "60",
+      "--display-name", ME, "--force", "--from-now"],
+      { cwd: CWD, env: process.env, stdio: ["pipe", "pipe", "pipe"] });
+    readline.createInterface({ input: p.stdout }).on("line", handle);
+    readline.createInterface({ input: p.stderr }).on("line", (l) => {
+      if (/error|Error|refused|403|401|wedged|circuit/i.test(l)) console.log("[listener-stderr] " + l.slice(0, 300));
+    });
+    p.on("exit", (code, sig) => {
+      const wasHealthy = Date.now() - startedAt > 60000;
+      if (wasHealthy) restarts = 0;
+      restarts++;
+      if (!wasHealthy && (restarts === 2 || restarts % 25 === 0)) console.log(`[listener-flapping] code=${code} sig=${sig} rapid-restarts=${restarts}`);
+      if (restarts > 500) { console.log("[listener-giving-up] too many rapid restarts"); process.exit(1); }
+      setTimeout(start, 5000);
+    });
+  }
+  start();
+
+  const seenReplies = new Set();
+  let repliesPrimed = false;
+  function pollReplies() {
+    execFile(process.execPath, [CLI, "session", "read", SID, "--remote", "--agent", ME, "--tail", "40", "--json"],
+      { cwd: POLL_CWD, env: process.env, maxBuffer: 16 * 1024 * 1024 }, (err, stdout) => {
+        if (err) { console.log("[reply-poll-error] " + String(err.message).slice(0, 200)); return; }
+        let j; try { j = JSON.parse(stdout); } catch { return; }
+        const items = [];
+        for (const e of j.events || []) if (e.event === "session_reply" || e.event === "session_message")
+          items.push({ key: (e.ts || "") + "|" + ((e.payload && (e.payload.targetSequenceId || e.payload.replyToSequenceId)) || ""), who: (e.agent && e.agent.id) || "?", ts: e.ts, target: e.payload && (e.payload.targetSequenceId || e.payload.replyToSequenceId), text: (e.payload && (e.payload.message || e.payload.note)) || "" });
+        for (const a of j.recentHumanActivity || [])
+          items.push({ key: (a.createdAt || "") + "|" + (a.targetSequenceId || ""), who: a.actorId || "human", ts: a.createdAt, target: a.targetSequenceId, text: a.note || "" });
+        for (const it of items) {
+          if (seenReplies.has(it.key)) continue;
+          seenReplies.add(it.key);
+          if (it.who !== ME) observe(it.ts);
+          if (!repliesPrimed && !(hadReceiptAtBoot && newerThanDelivered(it.ts))) continue;
+          if (!wanted(it.who)) continue;
+          deliver("session_reply", it.who, it.ts, null, it.target, String(it.text).replace(/\s+/g, " "));
+        }
+        repliesPrimed = true;
+      });
+  }
+  pollReplies();
+  setInterval(pollReplies, 20000);
+  console.log(`[listener-started] ${ME} listening on ${SID.slice(0, 8)} (presence heartbeats on; reply-poll every 20s)`);
+
+  function flushAndExit(sig) {
+    try { flushBroadcasts(); } catch {}
+    process.exit(sig === "SIGINT" ? 130 : 0);
+  }
+  process.on("SIGTERM", () => flushAndExit("SIGTERM"));
+  process.on("SIGINT", () => flushAndExit("SIGINT"));
+}
+
+module.exports = { runListener };

package/src/skills/service.js

@@ -0,0 +1,207 @@
+import { createHash, randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { setTimeout as delay } from "node:timers/promises";
+import { parse } from "yaml";
+
+const BUNDLE_ROOT = fileURLToPath(new URL("../../skills/", import.meta.url));
+const SKILL_NAMES = ["senti-agent-identity", "senti-room-notifications", "sentinelayer-cli", "senti-judge", "omar-gate-setup"];
+
+function sha256(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+async function statOrNull(filePath) {
+  try {
+    return await fs.lstat(filePath);
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+function unsafePath(filePath) {
+  return Object.assign(new Error(`Expected a regular file or directory, not a link: ${filePath}`), {
+    code: "SKILLS_UNSAFE_PATH",
+  });
+}
+
+async function readTree(directory) {
+  const rootStat = await statOrNull(directory);
+  if (!rootStat) return null;
+  if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) throw unsafePath(directory);
+  const files = [];
+  async function visit(relative) {
+    const entries = await fs.readdir(path.join(directory, relative), { withFileTypes: true });
+    entries.sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0);
+    for (const entry of entries) {
+      const name = relative ? `${relative}/${entry.name}` : entry.name;
+      const fullPath = path.join(directory, name);
+      if (entry.isDirectory()) await visit(name);
+      else if (entry.isFile()) files.push({ name, content: await fs.readFile(fullPath) });
+      else throw unsafePath(fullPath);
+    }
+  }
+  await visit("");
+  return files;
+}
+
+function describe(files) {
+  const document = files.find((file) => file.name === "SKILL.md")?.content.toString("utf8") || "";
+  const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(document);
+  let version = null;
+  try {
+    const value = frontmatter ? parse(frontmatter[1])?.metadata?.version : null;
+    if (typeof value === "string") version = value;
+  } catch {
+    // Locally edited frontmatter can be invalid; its content hash still reports the change.
+  }
+  return {
+    version,
+    hash: sha256(JSON.stringify(files.map((file) => [file.name, sha256(file.content)]))),
+  };
+}
+
+function resolveDirectory(dir) {
+  if (dir === undefined) return path.join(os.homedir(), ".claude", "skills");
+  if (typeof dir !== "string" || !dir.trim()) throw new Error("--dir must be a nonempty path.");
+  return path.resolve(dir);
+}
+
+// Check every component below the chosen destination, including dangling symlinks.
+async function inspectPath(root, destination) {
+  const relative = path.relative(root, destination);
+  if (relative.startsWith(`..${path.sep}`) || relative === ".." || path.isAbsolute(relative)) {
+    throw unsafePath(destination);
+  }
+  const components = relative ? relative.split(path.sep) : [];
+  let current = root;
+  for (let index = 0; index <= components.length; index += 1) {
+    const stat = await statOrNull(current);
+    if (stat && (stat.isSymbolicLink() || (index < components.length && !stat.isDirectory()))) {
+      throw unsafePath(current);
+    }
+    if (index === components.length) return stat;
+    current = path.join(current, components[index]);
+  }
+}
+
+function selectNames(names) {
+  if (names === undefined || names === null || (Array.isArray(names) && names.length === 0)) return SKILL_NAMES;
+  const wanted = (Array.isArray(names) ? names : [names]).map((name) => String(name).trim());
+  const unknown = wanted.filter((name) => !SKILL_NAMES.includes(name));
+  if (unknown.length) {
+    throw Object.assign(new Error(`Unknown skill: ${unknown.join(", ")}. Bundled skills: ${SKILL_NAMES.join(", ")}`), {
+      code: "SKILLS_UNKNOWN",
+    });
+  }
+  // Bundle order, each once.
+  return SKILL_NAMES.filter((name) => wanted.includes(name));
+}
+
+async function loadBundle(names = SKILL_NAMES) {
+  return Promise.all(names.map(async (name) => {
+    const files = await readTree(path.join(BUNDLE_ROOT, name));
+    if (!files?.some((file) => file.name === "SKILL.md")) {
+      throw new Error(`Bundled skill is missing SKILL.md: ${name}`);
+    }
+    const metadata = describe(files);
+    if (!metadata.version) throw new Error(`Bundled skill is missing a version: ${name}`);
+    return { name, files, ...metadata };
+  }));
+}
+
+async function replaceFile(source, destination) {
+  const deadline = Date.now() + 1000;
+  for (;;) {
+    try {
+      await fs.rename(source, destination);
+      return;
+    } catch (error) {
+      if (!["EPERM", "EBUSY"].includes(error.code) || Date.now() >= deadline) throw error;
+      await delay(25);
+    }
+  }
+}
+
+export async function listSkills({ dir } = {}) {
+  const directory = resolveDirectory(dir);
+  const skills = [];
+  for (const bundle of await loadBundle()) {
+    const destination = path.join(directory, bundle.name);
+    let installed = null;
+    let error = null;
+    try {
+      await inspectPath(directory, destination);
+      const files = await readTree(destination);
+      if (files) installed = describe(files);
+    } catch (caught) {
+      error = caught.message;
+    }
+    skills.push({
+      name: bundle.name,
+      bundled: { version: bundle.version, hash: bundle.hash },
+      installed,
+      status: error ? "invalid" : !installed ? "not-installed" :
+        installed.hash === bundle.hash ? "installed" : "modified",
+      ...(error ? { error } : {}),
+    });
+  }
+  return { directory, skills };
+}
+
+export async function installSkills({ dir, force = false, names } = {}) {
+  const directory = resolveDirectory(dir);
+  // Named skills only: a local edit to one skill never blocks installing another.
+  const bundles = await loadBundle(selectNames(names));
+  const plan = [];
+  const conflicts = [];
+  // Preflight the entire bundle so a conflict in the last skill cannot leave a partial install.
+  for (const bundle of bundles) {
+    for (const file of bundle.files) {
+      const destination = path.join(directory, bundle.name, file.name);
+      const stat = await inspectPath(directory, destination);
+      if (stat && !stat.isFile()) throw unsafePath(destination);
+      const unchanged = stat ? (await fs.readFile(destination)).equals(file.content) : false;
+      if (stat && !unchanged && !force) conflicts.push(destination);
+      plan.push({ bundle, file, destination, unchanged, exists: Boolean(stat) });
+    }
+  }
+  if (conflicts.length) {
+    throw Object.assign(new Error(`Local skill files differ; use --force to replace them:\n${conflicts.join("\n")}`), {
+      code: "SKILLS_CONFLICT", files: conflicts,
+    });
+  }
+  for (const item of plan) {
+    if (item.unchanged) continue;
+    await fs.mkdir(path.dirname(item.destination), { recursive: true });
+    await inspectPath(directory, item.destination);
+    if (!item.exists) {
+      // Exclusive creation also protects a file created after preflight.
+      await fs.copyFile(path.join(BUNDLE_ROOT, item.bundle.name, item.file.name), item.destination, constants.COPYFILE_EXCL);
+    } else {
+      const temporary = path.join(path.dirname(item.destination), `.skill-${randomUUID()}.tmp`);
+      try {
+        await fs.writeFile(temporary, item.file.content, { flag: "wx" });
+        // Replace the directory entry rather than modifying another file through a hard link.
+        await replaceFile(temporary, item.destination);
+      } finally {
+        await fs.rm(temporary, { force: true });
+      }
+    }
+  }
+  return {
+    directory,
+    skills: bundles.map((bundle) => {
+      const entries = plan.filter((item) => item.bundle === bundle);
+      return {
+        name: bundle.name, version: bundle.version, hash: bundle.hash,
+        written: entries.filter((item) => !item.unchanged).length,
+        unchanged: entries.filter((item) => item.unchanged).length,
+      };
+    }),
+  };
+}

package/src/swarm/factory.js

@@ -2,7 +2,7 @@ import { randomUUID } from "node:crypto";
 import fsp from "node:fs/promises";
 import path from "node:path";
 
-import { resolveOutputRoot } from "../config/service.js";
+import { resolveOutputContext } from "../config/service.js";
 
 const SCHEMA_VERSION = 1;
 const DEFAULT_GLOBAL_BUDGET = Object.freeze({
@@ -341,7 +341,7 @@ export async function writeSwarmPlanArtifacts({
     throw new Error("plan is required.");
   }
 
-  const outputRoot = await resolveOutputRoot({
+  const { outputRoot, outputFs } = await resolveOutputContext({
     cwd: path.resolve(String(plan.targetPath || ".")),
     outputDirOverride: outputDir,
     env,
@@ -350,9 +350,9 @@ export async function writeSwarmPlanArtifacts({
   const runDirectory = path.join(outputRoot, "swarms", plan.runId);
   const planJsonPath = path.join(runDirectory, "SWARM_PLAN.json");
   const planMarkdownPath = path.join(runDirectory, "SWARM_PLAN.md");
-  await fsp.mkdir(runDirectory, { recursive: true });
-  await fsp.writeFile(planJsonPath, `${JSON.stringify(plan, null, 2)}\n`, "utf-8");
-  await fsp.writeFile(planMarkdownPath, `${renderSwarmPlanMarkdown(plan).trim()}\n`, "utf-8");
+  await outputFs.mkdir(runDirectory, { recursive: true });
+  await outputFs.writeFile(planJsonPath, `${JSON.stringify(plan, null, 2)}\n`, "utf-8");
+  await outputFs.writeFile(planMarkdownPath, `${renderSwarmPlanMarkdown(plan).trim()}\n`, "utf-8");
 
   return {
     outputRoot,

package/src/swarm/pentest.js

@@ -3,7 +3,7 @@ import fsp from "node:fs/promises";
 import path from "node:path";
 
 import { getTargetById } from "../ai/domain-target-store.js";
-import { resolveOutputRoot } from "../config/service.js";
+import { resolveOutputContext } from "../config/service.js";
 
 const PENTEST_SCHEMA_VERSION = 1;
 
@@ -679,7 +679,7 @@ export async function runSwarmPentest({
   }
   const parsedTargetUrl = parseTargetUrl(targetUrl);
 
-  const outputRoot = await resolveOutputRoot({
+  const { outputRoot, outputFs } = await resolveOutputContext({
     cwd: normalizedTargetPath,
     outputDirOverride: outputDir,
     env,
@@ -747,8 +747,8 @@ export async function runSwarmPentest({
   const cleanupContractPath = path.join(pentestDirectory, "CLEANUP_CONTRACT.json");
   const reportJsonPath = path.join(pentestDirectory, "PENTEST_REPORT.json");
   const reportMarkdownPath = path.join(pentestDirectory, "PENTEST_REPORT.md");
-  await fsp.mkdir(pentestDirectory, { recursive: true });
-  await fsp.writeFile(
+  await outputFs.mkdir(pentestDirectory, { recursive: true });
+  await outputFs.writeFile(
     requestPlanPath,
     `${JSON.stringify(
       {
@@ -826,7 +826,7 @@ export async function runSwarmPentest({
   };
 
   await runCheckAtIndex(0);
-  await fsp.writeFile(
+  await outputFs.writeFile(
     auditLogPath,
     auditEntries.length > 0 ? `${auditEntries.map((entry) => JSON.stringify(entry)).join("\n")}\n` : "",
     "utf-8"
@@ -856,7 +856,7 @@ export async function runSwarmPentest({
       },
     ],
   };
-  await fsp.writeFile(identityIsolationPath, `${JSON.stringify(identityIsolation, null, 2)}\n`, "utf-8");
+  await outputFs.writeFile(identityIsolationPath, `${JSON.stringify(identityIsolation, null, 2)}\n`, "utf-8");
 
   const cleanupContract = {
     schemaVersion: 1,
@@ -868,7 +868,7 @@ export async function runSwarmPentest({
     cleanupRequested: true,
     cleanupTaskId: `cleanup-${runId}`,
   };
-  await fsp.writeFile(cleanupContractPath, `${JSON.stringify(cleanupContract, null, 2)}\n`, "utf-8");
+  await outputFs.writeFile(cleanupContractPath, `${JSON.stringify(cleanupContract, null, 2)}\n`, "utf-8");
 
   const findings = [];
   for (const entry of results) {
@@ -922,8 +922,8 @@ export async function runSwarmPentest({
     reportMarkdownPath,
   };
 
-  await fsp.writeFile(reportJsonPath, `${JSON.stringify(report, null, 2)}\n`, "utf-8");
-  await fsp.writeFile(reportMarkdownPath, `${renderPentestReportMarkdown(report).trim()}\n`, "utf-8");
+  await outputFs.writeFile(reportJsonPath, `${JSON.stringify(report, null, 2)}\n`, "utf-8");
+  await outputFs.writeFile(reportMarkdownPath, `${renderPentestReportMarkdown(report).trim()}\n`, "utf-8");
 
   return {
     ...report,

package/src/swarm/report.js

@@ -1,7 +1,7 @@
 import fsp from "node:fs/promises";
 import path from "node:path";
 
-import { resolveOutputRoot } from "../config/service.js";
+import { resolveOutputContext } from "../config/service.js";
 import { loadSwarmDashboardSnapshot, resolveSwarmRuntimeFiles } from "./dashboard.js";
 
 function normalizeString(value) {
@@ -109,7 +109,7 @@ export async function buildSwarmExecutionReport({
     homeDir,
   });
 
-  const outputRoot = await resolveOutputRoot({
+  const { outputRoot, outputFs } = await resolveOutputContext({
     cwd: path.resolve(String(targetPath || ".")),
     outputDirOverride: outputDir,
     env,
@@ -152,7 +152,7 @@ export async function buildSwarmExecutionReport({
     reportMarkdownPath,
   };
 
-  await fsp.writeFile(reportJsonPath, `${JSON.stringify(report, null, 2)}\n`, "utf-8");
-  await fsp.writeFile(reportMarkdownPath, `${buildReportMarkdown(report).trim()}\n`, "utf-8");
+  await outputFs.writeFile(reportJsonPath, `${JSON.stringify(report, null, 2)}\n`, "utf-8");
+  await outputFs.writeFile(reportMarkdownPath, `${buildReportMarkdown(report).trim()}\n`, "utf-8");
   return report;
 }

package/src/swarm/runtime.js

@@ -2,7 +2,7 @@ import { randomUUID } from "node:crypto";
 import fsp from "node:fs/promises";
 import path from "node:path";
 
-import { resolveOutputRoot } from "../config/service.js";
+import { resolveOutputContext } from "../config/service.js";
 import { evaluateBudget } from "../cost/budget.js";
 import { estimateTokens } from "../cost/tokenizer.js";
 
@@ -121,7 +121,7 @@ function createEvent({
   };
 }
 
-async function executePlaywrightAction({ page, action, runDirectory, usage, runId, step }) {
+async function executePlaywrightAction({ page, action, runDirectory, usage, runId, step, outputFs }) {
   const type = action.type;
   const metadata = {
     action: type,
@@ -195,14 +195,15 @@ async function executePlaywrightAction({ page, action, runDirectory, usage, runI
     });
   }
   if (type === "screenshot") {
-    const outputPath = action.path
+    const requestedOutputPath = action.path
       ? path.resolve(runDirectory, action.path)
       : path.join(runDirectory, "runtime", `step-${String(step).padStart(3, "0")}.png`);
-    await fsp.mkdir(path.dirname(outputPath), { recursive: true });
-    await page.screenshot({
-      path: outputPath,
+    const outputPath = await outputFs.assertFilePath(requestedOutputPath);
+    await outputFs.mkdir(path.dirname(outputPath), { recursive: true });
+    const screenshot = await page.screenshot({
       fullPage: true,
     });
+    await outputFs.writeFile(outputPath, screenshot);
     metadata.path = toPosixPath(path.relative(runDirectory, outputPath));
     usage.toolCalls += 1;
     usage.outputTokens += estimateTokens(`screenshot:${metadata.path}`);
@@ -268,7 +269,7 @@ async function writeRuntimeArtifacts({
   env,
   homeDir,
 } = {}) {
-  const outputRoot = await resolveOutputRoot({
+  const { outputRoot, outputFs } = await resolveOutputContext({
     cwd: path.resolve(String(summary.targetPath || ".")),
     outputDirOverride: outputDir,
     env,
@@ -279,8 +280,8 @@ async function writeRuntimeArtifacts({
   const runtimeJsonPath = path.join(runtimeDirectory, "SWARM_RUNTIME.json");
   const runtimeMarkdownPath = path.join(runtimeDirectory, "SWARM_RUNTIME.md");
   const runtimeEventsPath = path.join(runtimeDirectory, "events.ndjson");
-  await fsp.mkdir(runtimeDirectory, { recursive: true });
-  await fsp.writeFile(runtimeEventsPath, `${events.map((event) => JSON.stringify(event)).join("\n")}\n`, "utf-8");
+  await outputFs.mkdir(runtimeDirectory, { recursive: true });
+  await outputFs.writeFile(runtimeEventsPath, `${events.map((event) => JSON.stringify(event)).join("\n")}\n`, "utf-8");
 
   const fullSummary = {
     ...summary,
@@ -292,8 +293,8 @@ async function writeRuntimeArtifacts({
     runtimeEventsPath,
   };
 
-  await fsp.writeFile(runtimeJsonPath, `${JSON.stringify(fullSummary, null, 2)}\n`, "utf-8");
-  await fsp.writeFile(runtimeMarkdownPath, `${buildRuntimeMarkdown(fullSummary).trim()}\n`, "utf-8");
+  await outputFs.writeFile(runtimeJsonPath, `${JSON.stringify(fullSummary, null, 2)}\n`, "utf-8");
+  await outputFs.writeFile(runtimeMarkdownPath, `${buildRuntimeMarkdown(fullSummary).trim()}\n`, "utf-8");
 
   return fullSummary;
 }
@@ -323,7 +324,7 @@ export async function runSwarmRuntime({
   const normalizedTargetPath = path.resolve(String(targetPath || plan.targetPath || "."));
   const normalizedMaxSteps = normalizeMaxSteps(maxSteps);
   const runId = createRuntimeRunId();
-  const resolvedOutputRoot = await resolveOutputRoot({
+  const { outputRoot: resolvedOutputRoot, outputFs } = await resolveOutputContext({
     cwd: normalizedTargetPath,
     outputDirOverride: outputDir,
     env,
@@ -463,6 +464,7 @@ export async function runSwarmRuntime({
           const result = await runner(toolInput, {
             targetPath: normalizedTargetPath,
             outputRoot: resolvedOutputRoot,
+            outputFs,
             runId: toolInput.runId,
             execute: Boolean(execute),
             env,
@@ -583,6 +585,7 @@ export async function runSwarmRuntime({
             page,
             action,
             runDirectory: runtimeRunDirectory,
+            outputFs,
             usage,
             runId,
             step,

package/src/swarm/scenario-dsl.js

@@ -1,5 +1,6 @@
 import fsp from "node:fs/promises";
 import path from "node:path";
+import { resolveOutputContext } from "../config/service.js";
 
 const SUPPORTED_ACTIONS = new Set(["goto", "click", "fill", "wait", "screenshot"]);
 
@@ -256,15 +257,16 @@ export async function writeScenarioTemplate({
   startUrl = "https://example.com",
 } = {}) {
   const normalizedTargetPath = path.resolve(String(targetPath || "."));
-  const resolvedOutputFile = normalizeString(outputFile)
-    ? path.resolve(normalizedTargetPath, outputFile)
-    : path.join(normalizedTargetPath, ".sentinelayer", "scenarios", `${scenarioId}.sls`);
+  const { outputRoot: resolvedOutputFile, outputFs } = await resolveOutputContext({
+    cwd: normalizedTargetPath,
+    outputDirOverride: normalizeString(outputFile) || path.join(".sentinelayer", "scenarios", `${scenarioId}.sls`),
+  });
   const content = renderScenarioTemplate({
     scenarioId,
     startUrl,
   });
-  await fsp.mkdir(path.dirname(resolvedOutputFile), { recursive: true });
-  await fsp.writeFile(resolvedOutputFile, `${content.trim()}\n`, "utf-8");
+  await outputFs.mkdir(path.dirname(resolvedOutputFile), { recursive: true });
+  await outputFs.writeFile(resolvedOutputFile, `${content.trim()}\n`, "utf-8");
   return {
     filePath: resolvedOutputFile,
     content,