@deeeed/metamask-harness 0.24.0 → 0.25.0

package/dist/run-recording.js

@@ -31,23 +31,25 @@ async function startRecipeRecording(adapter, projectRoot, artifactsDir, options)
   }
   const recordArgs = ["record", "--framed", "--pid", String(pid)];
   const relativePath = "videos/full-run.mp4";
-  const outputPath = path.join(artifactsDir, relativePath);
-  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
-  fs.rmSync(outputPath, { force: true });
-  const child = spawn(captureHelperPath(), [...recordArgs, "--output", outputPath], {
+  const stage = preparePrivateRecordingStage(artifactsDir, relativePath);
+  const child = spawn(captureHelperPath(), [...recordArgs, "--output", stage.stagedOutputPath], {
     cwd: projectRoot,
     env: process.env,
     stdio: ["pipe", "pipe", "pipe"]
   });
   const recording = {
     child,
-    outputPath,
+    outputPath: stage.outputPath,
+    stagedOutputPath: stage.stagedOutputPath,
+    stagingDir: stage.stagingDir,
     relativePath,
     pid,
     stdout: "",
     stderr: "",
     exited: false,
     exitCode: null,
+    frameReady: false,
+    finalized: false,
     stderrBuffer: "",
     pendingSnapshots: /* @__PURE__ */ new Map()
   };
@@ -69,15 +71,25 @@ async function startRecipeRecording(adapter, projectRoot, artifactsDir, options)
     activeRecordingsByPid.delete(recording.pid);
     rejectPendingSnapshots(recording, new Error(`capture-helper recording exited before snapshot completed (code=${exitCode ?? "unknown"})`));
   });
-  await sleep(750);
+  await waitForRecordingReady(recording, 15e3);
   if (recording.exited) {
-    console.error(
-      `WARN: capture-helper record exited before the recipe started (code=${recording.exitCode ?? "unknown"}): ${recording.stderr || recording.stdout}`
+    cleanupRecordingStage(recording);
+    throw new Error(
+      `capture-helper exited before recording its first frame (code=${recording.exitCode ?? "unknown"}): ${recording.stderr || recording.stdout}`
+    );
+  }
+  if (!recording.frameReady) {
+    try {
+      await stopRecordingProcess(recording);
+    } finally {
+      cleanupRecordingStage(recording);
+    }
+    throw new Error(
+      `capture-helper did not record a frame within 15000ms: ${recording.stderr || recording.stdout || "no recorder output"}`
     );
-    return void 0;
   }
   activeRecordingsByPid.set(pid, recording);
-  console.error(`INFO: recording recipe video with capture-helper pid=${pid} output=${outputPath}`);
+  console.error(`INFO: recording recipe video with capture-helper pid=${pid} output=${recording.outputPath}`);
   return recording;
 }
 async function captureActiveRecipeRecordingSnapshot(pid, outputPath, timeoutMs = 3e4) {
@@ -101,8 +113,36 @@ async function captureActiveRecipeRecordingSnapshot(pid, outputPath, timeoutMs =
   });
 }
 async function stopRecipeRecording(recording, result) {
-  if (!recording) return;
-  if (!recording.exited) {
+  if (!recording || recording.finalized) return;
+  recording.finalized = true;
+  try {
+    await stopRecordingProcess(recording);
+  } catch (error) {
+    cleanupRecordingStage(recording);
+    if (result) removeRecordingArtifactFromManifest(result, recording.relativePath);
+    throw error;
+  }
+  const validation = validateRecordingArtifact(recording);
+  if (validation.ok === false) {
+    cleanupRecordingStage(recording);
+    if (result) removeRecordingArtifactFromManifest(result, recording.relativePath);
+    throw new Error(
+      `capture-helper recording did not produce a usable video artifact: ${validation.reason}`
+    );
+  }
+  try {
+    publishPrivateRecording(recording);
+  } catch (error) {
+    cleanupRecordingStage(recording);
+    if (result) removeRecordingArtifactFromManifest(result, recording.relativePath);
+    throw new Error(
+      `capture-helper recording could not safely publish ${recording.outputPath}: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+  if (result) addRecordingArtifactToManifest(result, recording);
+}
+async function stopRecordingProcess(recording) {
+  if (!recording.exited && !recording.child.stdin.destroyed) {
     recording.child.stdin.end("stop\n");
     await waitForRecordingExit(recording, 15e3);
   }
@@ -114,33 +154,33 @@ async function stopRecipeRecording(recording, result) {
     recording.child.kill("SIGTERM");
     await waitForRecordingExit(recording, 3e3);
   }
-  const validation = validateRecordingArtifact(recording);
-  if (validation.ok === false) {
-    try {
-      fs.rmSync(recording.outputPath, { force: true });
-    } catch (error) {
-      console.error(
-        `WARN: could not remove unusable capture-helper video ${recording.outputPath}: ${error instanceof Error ? error.message : String(error)}`
-      );
-    }
-    console.error(
-      `WARN: capture-helper recording did not produce a usable video artifact: ${validation.reason}`
-    );
-    if (result) removeRecordingArtifactFromManifest(result, recording.relativePath);
-    return;
+  if (!recording.exited) {
+    recording.child.kill("SIGKILL");
+    await waitForRecordingExit(recording, 2e3);
+  }
+  if (!recording.exited) {
+    throw new Error(`capture-helper recording process did not exit: pid=${recording.child.pid ?? "unknown"}`);
   }
-  if (result) addRecordingArtifactToManifest(result, recording);
 }
 async function waitForRecordingExit(recording, timeoutMs) {
   if (recording.exited) return;
   await new Promise((resolve) => {
-    const timer = setTimeout(resolve, timeoutMs);
-    recording.child.once("close", () => {
+    const finish = () => {
       clearTimeout(timer);
+      recording.child.removeListener("close", finish);
       resolve();
-    });
+    };
+    const timer = setTimeout(finish, timeoutMs);
+    recording.child.once("close", finish);
+    if (recording.exited) finish();
   });
 }
+async function waitForRecordingReady(recording, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (!recording.frameReady && !recording.exited && Date.now() < deadline) {
+    await sleep(50);
+  }
+}
 function handleRecordingStderr(recording, chunk) {
   recording.stderrBuffer += chunk;
   let newlineIndex = recording.stderrBuffer.indexOf("\n");
@@ -160,6 +200,9 @@ function handleRecordingEventLine(recording, line) {
   } catch {
     return;
   }
+  if (event.type === "info" && typeof event.msg === "string" && /^record frames=[1-9]\d*$/.test(event.msg)) {
+    recording.frameReady = true;
+  }
   const output = typeof event.output === "string" ? event.output : void 0;
   if (!output) return;
   const pending = recording.pendingSnapshots.get(output);
@@ -184,36 +227,39 @@ function rejectPendingSnapshots(recording, error) {
   recording.pendingSnapshots.clear();
 }
 function validateRecordingArtifact(recording) {
-  if (!fs.existsSync(recording.outputPath)) {
-    return { ok: false, reason: `missing output ${recording.outputPath}` };
+  if (!fs.existsSync(recording.stagedOutputPath)) {
+    return { ok: false, reason: `missing output ${recording.stagedOutputPath}` };
   }
-  const size = fs.statSync(recording.outputPath).size;
-  if (size === 0) {
-    return { ok: false, reason: `empty output ${recording.outputPath}` };
+  const info = fs.lstatSync(recording.stagedOutputPath);
+  if (info.isSymbolicLink() || !info.isFile()) {
+    return { ok: false, reason: `output is not a safe regular file ${recording.stagedOutputPath}` };
+  }
+  if (info.size === 0) {
+    return { ok: false, reason: `empty output ${recording.stagedOutputPath}` };
   }
   const recorderOutput = `${recording.stdout}
 ${recording.stderr}`;
   if (!recorderOutput.includes("record_complete")) {
     return {
       ok: false,
-      reason: `capture-helper did not report record_complete for ${recording.outputPath}: ${recorderOutput.trim() || "no recorder output"}`
+      reason: `capture-helper did not report record_complete for ${recording.stagedOutputPath}: ${recorderOutput.trim() || "no recorder output"}`
     };
   }
   const ffprobe = spawnSync(
     "ffprobe",
-    ["-hide_banner", "-v", "error", "-show_entries", "format=duration", "-of", "default=noprint_wrappers=1:nokey=1", recording.outputPath],
+    ["-hide_banner", "-v", "error", "-show_entries", "format=duration", "-of", "default=noprint_wrappers=1:nokey=1", recording.stagedOutputPath],
     { encoding: "utf8" }
   );
   if (ffprobe.error && ffprobe.error.code === "ENOENT") {
     return { ok: true };
   }
   if (ffprobe.error) {
-    return { ok: false, reason: `ffprobe failed for ${recording.outputPath}: ${ffprobe.error.message}` };
+    return { ok: false, reason: `ffprobe failed for ${recording.stagedOutputPath}: ${ffprobe.error.message}` };
   }
   if (ffprobe.status !== 0) {
     return {
       ok: false,
-      reason: `invalid MP4 ${recording.outputPath}: ${ffprobe.stderr.trim() || ffprobe.stdout.trim() || `ffprobe exited ${ffprobe.status}`}`
+      reason: `invalid MP4 ${recording.stagedOutputPath}: ${ffprobe.stderr.trim() || ffprobe.stdout.trim() || `ffprobe exited ${ffprobe.status}`}`
     };
   }
   const durationSeconds = Number(ffprobe.stdout.trim());
@@ -222,6 +268,77 @@ ${recording.stderr}`;
   }
   return { ok: true };
 }
+function preparePrivateRecordingStage(artifactsDir, relativePath) {
+  const artifactsRoot = path.resolve(artifactsDir);
+  const outputPath = path.resolve(artifactsRoot, relativePath);
+  if (!outputPath.startsWith(`${artifactsRoot}${path.sep}`)) {
+    throw new Error(`Refusing recording artifact outside artifacts dir: ${relativePath}`);
+  }
+  fs.mkdirSync(artifactsRoot, { recursive: true });
+  ensureRecordingParent(artifactsRoot, path.dirname(outputPath));
+  refuseUnsafeRecordingDestination(outputPath);
+  const stagingDir = fs.mkdtempSync(path.join(artifactsRoot, ".extension-recording-"));
+  fs.chmodSync(stagingDir, 448);
+  return {
+    outputPath,
+    stagedOutputPath: path.join(stagingDir, "full-run.mp4"),
+    stagingDir
+  };
+}
+function ensureRecordingParent(artifactsRoot, parent) {
+  const relative = path.relative(artifactsRoot, parent);
+  let current = artifactsRoot;
+  for (const segment of relative.split(path.sep).filter(Boolean)) {
+    current = path.join(current, segment);
+    const info = lstatIfPresent(current);
+    if (!info) {
+      fs.mkdirSync(current, { mode: 448 });
+      continue;
+    }
+    if (info.isSymbolicLink() || !info.isDirectory()) {
+      throw new Error(`Refusing recording artifact parent that is not a real directory: ${current}`);
+    }
+  }
+}
+function refuseUnsafeRecordingDestination(outputPath) {
+  const info = lstatIfPresent(outputPath);
+  if (!info) return;
+  if (info.isSymbolicLink()) {
+    throw new Error(`Refusing recording artifact destination symlink: ${outputPath}`);
+  }
+  if (!info.isFile()) {
+    throw new Error(`Refusing recording artifact destination that is not a regular file: ${outputPath}`);
+  }
+}
+function lstatIfPresent(filePath) {
+  try {
+    return fs.lstatSync(filePath);
+  } catch (error) {
+    if (error.code === "ENOENT") return void 0;
+    throw error;
+  }
+}
+function publishPrivateRecording(recording) {
+  const descriptor = fs.openSync(
+    recording.stagedOutputPath,
+    fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0)
+  );
+  try {
+    const info = fs.fstatSync(descriptor);
+    if (!info.isFile()) {
+      throw new Error(`Captured recording is not a safe regular file: ${recording.stagedOutputPath}`);
+    }
+    fs.fchmodSync(descriptor, 384);
+    refuseUnsafeRecordingDestination(recording.outputPath);
+    fs.renameSync(recording.stagedOutputPath, recording.outputPath);
+  } finally {
+    fs.closeSync(descriptor);
+  }
+  cleanupRecordingStage(recording);
+}
+function cleanupRecordingStage(recording) {
+  fs.rmSync(recording.stagingDir, { recursive: true, force: true });
+}
 function addRecordingArtifactToManifest(result, recording) {
   const manifestPath = result.artifactManifestPath;
   if (!manifestPath || !fs.existsSync(manifestPath)) {

package/library/actions/extension/analytics/set_consent.mjs

@@ -0,0 +1,165 @@
+import { runAdapter, withExtensionPage } from '../platform/cdp.mjs';
+import { consentParams } from '../../shared/analytics/consent.mjs';
+
+runAdapter((input) => withExtensionPage(input, async (page) => {
+  const { participate, marketing, timeoutMs } = consentParams(input.node);
+  const bridgeSymbol = 'metamask-harness-consent-bridge';
+
+  async function readConsentState() {
+    return page.evaluate(`(async () => {
+      const getState = globalThis.stateHooks?.getCleanAppState;
+      if (typeof getState !== 'function') throw new Error('stateHooks.getCleanAppState is unavailable.');
+      const metamask = (await getState())?.metamask ?? {};
+      return {
+        optedIn: Boolean(metamask.optedIn),
+        dataCollectionForMarketing: Boolean(metamask.dataCollectionForMarketing),
+        analyticsId: metamask.analyticsId ? 'set' : null
+      };
+    })()`, { awaitPromise: true });
+  }
+
+  async function waitForConsentState(expected) {
+    const deadline = Date.now() + timeoutMs;
+    let state;
+    do {
+      state = await readConsentState();
+      if (Object.entries(expected).every(([key, value]) => state[key] === value)) {
+        return state;
+      }
+      await new Promise((resolve) => setTimeout(resolve, 100));
+    } while (Date.now() < deadline);
+    throw new Error(`Consent state did not settle to ${JSON.stringify(expected)}; got ${JSON.stringify(state)}.`);
+  }
+
+  const hasDebugBridge = await page.evaluate(
+    `typeof globalThis.stateHooks?.submitRequestToBackground === 'function'`,
+  );
+  let preloadIdentifier;
+  if (!hasDebugBridge) {
+    const preload = await page.session.call('Page.addScriptToEvaluateOnNewDocument', {
+      source: `Object.defineProperty(
+        globalThis,
+        Symbol.for(${JSON.stringify(bridgeSymbol)}),
+        { value: globalThis.chrome, configurable: true }
+      );`,
+    });
+    preloadIdentifier = preload?.identifier;
+    try {
+      let notifyLoaded;
+      const loaded = new Promise((resolve) => {
+        notifyLoaded = resolve;
+      });
+      const unsubscribe = page.session.on('Page.loadEventFired', () => notifyLoaded?.());
+      let reloadTimeout;
+      try {
+        await page.session.call('Page.reload', { ignoreCache: false });
+        await Promise.race([
+          loaded,
+          new Promise((_, reject) => {
+            reloadTimeout = setTimeout(
+              () => reject(new Error(`Extension consent reload timed out after ${timeoutMs}ms.`)),
+              timeoutMs,
+            );
+          }),
+        ]);
+      } finally {
+        clearTimeout(reloadTimeout);
+        unsubscribe();
+      }
+      await page.waitForExpression(
+        `typeof globalThis[Symbol.for(${JSON.stringify(bridgeSymbol)})]?.runtime?.connect === 'function'`,
+        { timeoutMs },
+      );
+    } finally {
+      if (preloadIdentifier) {
+        await page.session.call('Page.removeScriptToEvaluateOnNewDocument', {
+          identifier: preloadIdentifier,
+        });
+      }
+    }
+  }
+
+  const controllerResult = await page.evaluate(`(async () => {
+    const submit = globalThis.stateHooks?.submitRequestToBackground;
+    const bridgeKey = Symbol.for(${JSON.stringify(bridgeSymbol)});
+    const capturedChrome = globalThis[bridgeKey];
+    let port;
+    let nextId = Date.now();
+
+    const rawSubmit = (method, params) => new Promise((resolve, reject) => {
+      if (!port) {
+        const connectionName = location.pathname.includes('sidepanel')
+          ? 'sidepanel'
+          : location.pathname.includes('popup')
+            ? 'popup'
+            : 'fullscreen';
+        port = capturedChrome.runtime.connect({ name: connectionName });
+      }
+      const id = nextId++;
+      const timer = setTimeout(
+        () => reject(new Error(method + ' timed out after ${timeoutMs}ms')),
+        ${timeoutMs},
+      );
+      const listener = (message) => {
+        const data = message?.name === 'controller' ? message.data : null;
+        if (data?.id !== id) return;
+        clearTimeout(timer);
+        port.onMessage.removeListener(listener);
+        if (data.error) reject(new Error(JSON.stringify(data.error)));
+        else resolve(data.result);
+      };
+      port.onMessage.addListener(listener);
+      port.postMessage({
+        name: 'controller',
+        data: { jsonrpc: '2.0', id, method, params }
+      });
+    });
+
+    const callController = typeof submit === 'function' ? submit : rawSubmit;
+    if (typeof callController !== 'function') {
+      throw new Error('Extension consent setup could not reach the background controller.');
+    }
+
+    const setMarketing = async (value) => {
+      await callController('setDataCollectionForMarketing', [value]);
+    };
+
+    try {
+      if (!${JSON.stringify(participate)}) await setMarketing(false);
+      const analyticsId = await callController(
+        'setParticipateInMetaMetrics',
+        [${JSON.stringify(participate)}],
+      );
+      if (${JSON.stringify(participate)}) {
+        await setMarketing(${JSON.stringify(marketing)});
+      }
+      return { analyticsId: analyticsId ? 'set' : null };
+    } finally {
+      port?.disconnect();
+      if (capturedChrome) delete globalThis[bridgeKey];
+    }
+  })()`, { awaitPromise: true });
+
+  const state = await waitForConsentState({
+    optedIn: participate,
+    dataCollectionForMarketing: marketing,
+  });
+
+  if (state.optedIn !== participate) {
+    throw new Error(`Expected optedIn=${participate}, got ${state.optedIn}.`);
+  }
+  if (state.dataCollectionForMarketing !== marketing) {
+    throw new Error(`Expected dataCollectionForMarketing=${marketing}, got ${state.dataCollectionForMarketing}.`);
+  }
+  if (participate && controllerResult.analyticsId !== 'set') {
+    throw new Error('MetaMetrics consent was enabled but the controller did not return an analyticsId.');
+  }
+  return {
+    action: input.action,
+    consent: {
+      ...state,
+      analyticsId: controllerResult.analyticsId,
+    },
+    proofPath: 'extension-background-controller',
+  };
+}));

package/library/actions/extension/platform/cdp.mjs

@@ -1,4 +1,17 @@
-import { constants, access, cp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import {
+  constants,
+  access,
+  chmod,
+  cp,
+  lstat,
+  mkdir,
+  mkdtemp,
+  open,
+  readFile,
+  rename,
+  rm,
+  writeFile,
+} from 'node:fs/promises';
 import { closeSync, openSync } from 'node:fs';
 import { spawn } from 'node:child_process';
 import { createRequire } from 'node:module';
@@ -74,6 +87,75 @@ function resolveRelativeArtifactPath(artifactsDir, relPath) {
   return { relative: normalized, absolute };
 }
 
+async function preparePrivateArtifactStage(artifactsDir, relPath) {
+  const destination = resolveRelativeArtifactPath(artifactsDir, relPath);
+  const artifactsRoot = path.resolve(artifactsDir);
+  await mkdir(artifactsRoot, { recursive: true });
+  await ensureArtifactParent(artifactsRoot, path.dirname(destination.absolute));
+  await refuseUnsafeDestination(destination.absolute);
+  const stagingDir = await mkdtemp(path.join(artifactsRoot, '.extension-evidence-'));
+  await chmod(stagingDir, 0o700);
+  return {
+    ...destination,
+    stagingDir,
+    staged: path.join(stagingDir, 'artifact'),
+  };
+}
+
+async function ensureArtifactParent(artifactsRoot, parent) {
+  const relative = path.relative(artifactsRoot, parent);
+  let current = artifactsRoot;
+  for (const segment of relative.split(path.sep).filter(Boolean)) {
+    current = path.join(current, segment);
+    try {
+      const info = await lstat(current);
+      if (info.isSymbolicLink() || !info.isDirectory()) {
+        throw new Error(`Refusing Extension evidence parent that is not a real directory: ${current}`);
+      }
+    } catch (error) {
+      if (error?.code !== 'ENOENT') throw error;
+      await mkdir(current, { mode: 0o700 });
+    }
+  }
+}
+
+async function refuseUnsafeDestination(destination) {
+  try {
+    const info = await lstat(destination);
+    if (info.isSymbolicLink()) {
+      throw new Error(`Refusing Extension evidence destination symlink: ${destination}`);
+    }
+    if (!info.isFile()) {
+      throw new Error(`Refusing Extension evidence destination that is not a regular file: ${destination}`);
+    }
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error;
+  }
+}
+
+async function publishPrivateArtifact(stage) {
+  const handle = await open(
+    stage.staged,
+    constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0),
+  );
+  try {
+    const info = await handle.stat();
+    if (!info.isFile()) {
+      throw new Error(`Captured Extension evidence is not a safe regular file: ${stage.staged}`);
+    }
+    await handle.chmod(0o600);
+    await refuseUnsafeDestination(stage.absolute);
+    await rename(stage.staged, stage.absolute);
+  } finally {
+    await handle.close();
+  }
+  await rm(stage.stagingDir, { recursive: true, force: true });
+}
+
+async function cleanupPrivateArtifactStage(stage) {
+  await rm(stage.stagingDir, { recursive: true, force: true });
+}
+
 function captureHelperPath() {
   return process.env.CAPTURE_HELPER_PATH || 'capture-helper';
 }
@@ -121,8 +203,7 @@ async function captureHelperBrowserPid(context, port) {
 }
 
 async function captureCdpViewportSnapshot(page, context, relPath, metadata, captureHelperError = null) {
-  const { relative, absolute } = resolveRelativeArtifactPath(context.artifactsDir, relPath);
-  await mkdir(path.dirname(absolute), { recursive: true });
+  const stage = await preparePrivateArtifactStage(context.artifactsDir, relPath);
   try {
     const timeoutMs = Number(metadata?.cdpTimeoutMs ?? 5000);
     const result = await Promise.race([
@@ -136,9 +217,13 @@ async function captureCdpViewportSnapshot(page, context, relPath, metadata, capt
     if (typeof result?.data !== 'string' || result.data.length === 0) {
       throw new Error('Chrome Page.captureScreenshot returned no image data.');
     }
-    await writeFile(absolute, Buffer.from(result.data, 'base64'));
+    await writeFile(stage.staged, Buffer.from(result.data, 'base64'), {
+      flag: 'wx',
+      mode: 0o600,
+    });
+    await publishPrivateArtifact(stage);
     return {
-      path: relative,
+      path: stage.relative,
       type: 'screenshot',
       nodeId: context.nodeId,
       label: metadata?.label ?? `${context.nodeId} screenshot`,
@@ -151,13 +236,13 @@ async function captureCdpViewportSnapshot(page, context, relPath, metadata, capt
       },
     };
   } catch (error) {
+    await cleanupPrivateArtifactStage(stage);
     const cdpError = error instanceof Error ? error.message : String(error);
     return captureDomRasterSnapshot(page, context, relPath, metadata, captureHelperError, cdpError);
   }
 }
 
 async function captureDomRasterSnapshot(page, context, relPath, metadata, captureHelperError, cdpError) {
-  const { relative, absolute } = resolveRelativeArtifactPath(context.artifactsDir, relPath);
   const dataUrl = await page.evaluate(`(async () => {
     const width = Math.max(1, window.innerWidth);
     const height = Math.max(1, window.innerHeight);
@@ -200,9 +285,20 @@ async function captureDomRasterSnapshot(page, context, relPath, metadata, captur
   if (typeof dataUrl !== 'string' || !dataUrl.startsWith('data:image/png;base64,')) {
     throw new Error(`Extension screenshot fallbacks failed: capture-helper=${captureHelperError ?? 'not attempted'}; cdp=${cdpError}; DOM raster returned no PNG.`);
   }
-  await writeFile(absolute, Buffer.from(dataUrl.slice('data:image/png;base64,'.length), 'base64'));
+  const stage = await preparePrivateArtifactStage(context.artifactsDir, relPath);
+  try {
+    await writeFile(
+      stage.staged,
+      Buffer.from(dataUrl.slice('data:image/png;base64,'.length), 'base64'),
+      { flag: 'wx', mode: 0o600 },
+    );
+    await publishPrivateArtifact(stage);
+  } catch (error) {
+    await cleanupPrivateArtifactStage(stage);
+    throw error;
+  }
   return {
-    path: relative,
+    path: stage.relative,
     type: 'screenshot',
     nodeId: context.nodeId,
     label: metadata?.label ?? `${context.nodeId} screenshot`,
@@ -222,16 +318,16 @@ export async function captureHelperSnapshot(page, context, relPath, metadata) {
   if (process.platform !== 'darwin') {
     return captureCdpViewportSnapshot(page, context, relPath, metadata);
   }
-  const { relative, absolute } = resolveRelativeArtifactPath(context.artifactsDir, relPath);
-  await mkdir(path.dirname(absolute), { recursive: true });
+  const stage = await preparePrivateArtifactStage(context.artifactsDir, relPath);
 
   try {
     const pid = await captureHelperBrowserPid(context, page.port);
     const timeoutMs = Number(metadata?.timeoutMs ?? 30000);
-    const sessionSnapshot = await captureActiveRecipeRecordingSnapshot(pid, absolute, timeoutMs);
+    const sessionSnapshot = await captureActiveRecipeRecordingSnapshot(pid, stage.staged, timeoutMs);
     if (sessionSnapshot) {
+      await publishPrivateArtifact(stage);
       return {
-        path: relative,
+        path: stage.relative,
         type: 'screenshot',
         nodeId: context.nodeId,
         label: metadata?.label ?? `${context.nodeId} screenshot`,
@@ -246,7 +342,7 @@ export async function captureHelperSnapshot(page, context, relPath, metadata) {
       };
     }
 
-    const result = await runProcess(captureHelperPath(), ['snapshot', '--pid', String(pid), '--output', absolute], {
+    const result = await runProcess(captureHelperPath(), ['snapshot', '--pid', String(pid), '--output', stage.staged], {
       cwd: context.projectRoot,
       env: process.env,
       timeoutMs,
@@ -255,8 +351,9 @@ export async function captureHelperSnapshot(page, context, relPath, metadata) {
       throw new Error(`capture-helper snapshot failed for pid ${pid}: ${result.stderr || result.stdout}`);
     }
     const details = parseJsonObject(result.stdout);
+    await publishPrivateArtifact(stage);
     return {
-      path: relative,
+      path: stage.relative,
       type: 'screenshot',
       nodeId: context.nodeId,
       label: metadata?.label ?? `${context.nodeId} screenshot`,
@@ -270,6 +367,7 @@ export async function captureHelperSnapshot(page, context, relPath, metadata) {
       },
     };
   } catch (error) {
+    await cleanupPrivateArtifactStage(stage);
     const message = error instanceof Error ? error.message : String(error);
     return captureCdpViewportSnapshot(page, context, relPath, metadata, message);
   }