@deeeed/metamask-harness 0.43.0 → 0.44.0

package/dist/commands/run.js

@@ -21,6 +21,7 @@ import {
   executeWithHealBounds,
   preflightRecipe,
   prepareHeal,
+  persistRunEffects,
   recoverRunInfra,
   runRecipe,
   validateRunRecipeStatic
@@ -30,11 +31,15 @@ import { applyDeviceTargeting } from "./device-target.js";
 import { getAdapterSurface } from "../adapters/surface.js";
 import { coreDependencyBlock } from "./core-readiness.js";
 import { readMobileReleaseArtifactState } from "../adapters/mobile/release-artifact-state.js";
-import { writeRunReport } from "./run-report.js";
+import {
+  indexProductProvenanceArtifact,
+  writeRunReport
+} from "./run-report.js";
 import { acquireCheckoutLock } from "../checkout-lock.js";
 import { JsonStreamWriter } from "../json-stream.js";
 import { formatRunDiagnosticsForHuman, readRunDiagnosticsDocument } from "../run-diagnostics.js";
 import { recipeTrustFailure } from "../recipe-security.js";
+import { ProvenanceDriftError } from "../execution-provenance.js";
 import { recordCommandEvidence, redactStructuredValue } from "../command-journal.js";
 import {
   actionLibraryContextArgs,
@@ -75,6 +80,31 @@ async function handleRun(parsed) {
     stream.complete(exitCode === EXIT.ok ? "pass" : "fail", exitCode);
     return exitCode;
   } catch (error) {
+    if (error instanceof ProvenanceDriftError) {
+      const failure = {
+        code: error.code,
+        message: error.message,
+        userAction: error.userAction,
+        provenancePath: error.provenancePath,
+        drift: error.drift
+      };
+      if (stream.enabled) {
+        stream.error(failure);
+        stream.complete("fail", error.exitCode);
+      } else if (optionFlag(parsed.options, "json")) {
+        console.log(JSON.stringify({
+          schemaVersion: 1,
+          command: "run",
+          status: "fail",
+          error: failure,
+          exitCode: error.exitCode
+        }, null, 2));
+      } else {
+        console.error(`\u2717 mm-harness run: ${error.message}`);
+        console.error(`  Next: ${error.userAction}`);
+      }
+      return error.exitCode;
+    }
     const trustFailure = recipeTrustFailure(error);
     if (trustFailure) {
       if (stream.enabled) {
@@ -275,6 +305,14 @@ async function handleRunInner({ positional, options }, stream) {
       return prepared;
     }
     const { state, heal } = prepared;
+    preflightedExecution = await preflightRecipe(
+      adapter,
+      validated.recipeFile,
+      artifactsDir,
+      target,
+      optionString(options, "actionManifest"),
+      runtimeOptions
+    );
     networkObservation = await startRunNetworkObservation(
       adapter,
       target,
@@ -311,7 +349,8 @@ async function handleRunInner({ positional, options }, stream) {
             target,
             optionString(options, "actionManifest"),
             runtimeOptions,
-            execution
+            execution,
+            state
           );
         },
         adapter,
@@ -335,6 +374,12 @@ async function handleRunInner({ positional, options }, stream) {
     performanceObservation = void 0;
     for (const mutation of state.mutations) stream.mutation(mutation);
     for (const recovery of state.recovered) stream.recovery(recovery);
+    persistRunEffects(result.summaryPath, result.artifactManifestPath, state);
+    indexProductProvenanceArtifact(
+      result.artifactManifestPath,
+      target,
+      adapter
+    );
     if (violation !== null) {
       const userAction = violation.userAction ?? `inspect ${shellQuote(result.summaryPath)} and ${shellQuote(result.tracePath)}; fix the application or recipe failure before retrying`;
       stream.error({

package/dist/execution-provenance.js

@@ -0,0 +1,342 @@
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import fs, { constants as fsConstants } from "node:fs";
+import path from "node:path";
+import { mobileSourceFingerprint } from "./adapters/mobile/source-freshness.js";
+import { importRecipeProtocol, runnerDir } from "./paths.js";
+const gitContexts = /* @__PURE__ */ new Map();
+let protocolPromise;
+class ProvenanceDriftError extends Error {
+  code = "PROVENANCE_DRIFT";
+  exitCode = 5;
+  userAction;
+  provenancePath;
+  drift;
+  constructor(provenancePath, drift, cause) {
+    const fields = [...new Set(drift.map((entry) => entry.field))].join(", ");
+    super(
+      `Execution inputs changed after preparation (${fields}); evidence is invalid.`,
+      cause === void 0 ? void 0 : { cause }
+    );
+    this.name = "ProvenanceDriftError";
+    this.provenancePath = provenancePath;
+    this.drift = drift;
+    this.userAction = `restore the prepared recipe, library, and product source, then rerun; inspect ${provenancePath}`;
+  }
+}
+async function captureExecutionProvenance(input, phase) {
+  const protocol = await (protocolPromise ??= importRecipeProtocol());
+  const recipeDigest = input.recipePath ? recipeFileDigest(protocol, input.recipePath) : protocol.digestRecipeDocument(input.recipeDocument);
+  const libraries = (input.librarySources ?? []).map((source, index) => ({
+    name: source.name ?? `library-${index + 1}`,
+    ...sourceSnapshot(source.root)
+  }));
+  const runnerRoot = input.runnerRoot ?? runnerDir;
+  return {
+    phase,
+    capturedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    recipeDigest,
+    product: sourceSnapshot(
+      input.projectRoot,
+      input.adapter,
+      input.excludedProductRoots
+    ),
+    runner: sourceSnapshot(runnerRoot, void 0, [], [
+      "src",
+      "adapters",
+      "library",
+      "bin",
+      "dist",
+      "package.json"
+    ]),
+    libraries,
+    helpers: (input.helperPaths ?? []).map((helperPath) => ({
+      path: displayPath(input.projectRoot, helperPath),
+      sourceFingerprint: fileFingerprint(helperPath)
+    }))
+  };
+}
+function executionProvenanceDrift(start, current) {
+  const drift = [];
+  if (current.phase === "start") return drift;
+  const phase = current.phase;
+  compare(drift, phase, "recipeDigest", start.recipeDigest, current.recipeDigest);
+  compareSource(drift, phase, "product", start.product, current.product);
+  compareSource(drift, phase, "runner", start.runner, current.runner);
+  if (start.libraries.length !== current.libraries.length) {
+    compare(
+      drift,
+      phase,
+      "libraries.length",
+      String(start.libraries.length),
+      String(current.libraries.length)
+    );
+  }
+  const count = Math.min(start.libraries.length, current.libraries.length);
+  for (let index = 0; index < count; index += 1) {
+    const expected = start.libraries[index];
+    const actual = current.libraries[index];
+    const prefix = `libraries[${index}]`;
+    compare(drift, phase, `${prefix}.name`, expected.name, actual.name);
+    compareSource(drift, phase, prefix, expected, actual);
+  }
+  if (start.helpers.length !== current.helpers.length) {
+    compare(
+      drift,
+      phase,
+      "helpers.length",
+      String(start.helpers.length),
+      String(current.helpers.length)
+    );
+  }
+  const helperCount = Math.min(start.helpers.length, current.helpers.length);
+  for (let index = 0; index < helperCount; index += 1) {
+    compare(drift, phase, `helpers[${index}].path`, start.helpers[index].path, current.helpers[index].path);
+    compare(
+      drift,
+      phase,
+      `helpers[${index}].sourceFingerprint`,
+      start.helpers[index].sourceFingerprint,
+      current.helpers[index].sourceFingerprint
+    );
+  }
+  return drift;
+}
+function writeExecutionProvenance(artifactsDir, snapshots, drift, artifactManifestPath) {
+  const provenancePath = path.join(path.resolve(artifactsDir), "execution-provenance.json");
+  const record = {
+    schemaVersion: 1,
+    valid: drift.length === 0,
+    snapshots,
+    drift
+  };
+  fs.mkdirSync(path.dirname(provenancePath), { recursive: true });
+  fs.writeFileSync(provenancePath, `${JSON.stringify(record, null, 2)}
+`);
+  if (artifactManifestPath) indexProvenanceArtifact(artifactManifestPath, record);
+  return provenancePath;
+}
+function recipeFileDigest(protocol, recipePath) {
+  const source = readRegularFileNoFollow(recipePath);
+  try {
+    return protocol.digestRecipeDocument(JSON.parse(source.toString("utf8")));
+  } catch {
+    return `invalid:sha256:${createHash("sha256").update(source).digest("hex")}`;
+  }
+}
+function sourceSnapshot(root, adapter, excludedRoots = [], includedRoots = []) {
+  const git = gitContext(root);
+  if (!git) {
+    return {
+      head: null,
+      status: "not-a-git-checkout",
+      sourceFingerprint: directoryFingerprint(root, excludedRoots, includedRoots)
+    };
+  }
+  const pathspecs = sourcePathspecs(git, excludedRoots, includedRoots);
+  const status = gitText(git.topLevel, [
+    "status",
+    "--porcelain=v1",
+    "--untracked-files=normal",
+    "--",
+    ...pathspecs
+  ]);
+  return {
+    head: gitText(git.topLevel, ["rev-parse", "HEAD"]).trim() || null,
+    status,
+    sourceFingerprint: adapter === "mobile" && path.resolve(root) === git.topLevel ? mobileSourceFingerprint(root) : nestedGitSourceFingerprint(root, git, pathspecs, excludedRoots, includedRoots)
+  };
+}
+function nestedGitSourceFingerprint(root, git, pathspecs, excludedRoots, includedRoots) {
+  const gitFingerprint = gitSourceFingerprint(git.topLevel, pathspecs);
+  if (git.pathspec === "." && includedRoots.length === 0) return gitFingerprint;
+  return createHash("sha256").update(gitFingerprint).update("\0nested-source\0").update(directoryFingerprint(root, excludedRoots, includedRoots)).digest("hex");
+}
+function gitContext(root) {
+  const cacheKey = path.resolve(root);
+  if (gitContexts.has(cacheKey)) return gitContexts.get(cacheKey) ?? null;
+  try {
+    const resolved = cacheKey;
+    const topLevel = fs.realpathSync(
+      gitText(resolved, ["rev-parse", "--show-toplevel"]).trim()
+    );
+    const relative = path.relative(topLevel, fs.realpathSync(resolved));
+    const context = relative === ".." || relative.startsWith(`..${path.sep}`) ? null : { topLevel, pathspec: relative || "." };
+    gitContexts.set(cacheKey, context);
+    return context;
+  } catch {
+    gitContexts.set(cacheKey, null);
+    return null;
+  }
+}
+function gitSourceFingerprint(topLevel, pathspecs) {
+  const hash = createHash("sha256");
+  hash.update(gitBuffer(topLevel, ["rev-parse", "HEAD"]));
+  hash.update("\0diff\0");
+  hash.update(
+    gitBuffer(topLevel, [
+      "diff",
+      "--no-ext-diff",
+      "--binary",
+      "HEAD",
+      "--",
+      ...pathspecs
+    ])
+  );
+  const untracked = gitText(topLevel, [
+    "ls-files",
+    "--others",
+    "--exclude-standard",
+    "-z",
+    "--",
+    ...pathspecs
+  ]).split("\0").filter(Boolean).sort();
+  for (const relative of untracked) {
+    hash.update(`\0untracked\0${relative}\0`);
+    const absolute = path.join(topLevel, relative);
+    hash.update(readPathIdentity(absolute));
+  }
+  return hash.digest("hex");
+}
+function sourcePathspecs(git, excludedRoots, includedRoots) {
+  const exclusions = excludedRoots.flatMap((root) => {
+    const relative = path.relative(git.topLevel, path.resolve(root));
+    return relative !== ".." && !relative.startsWith(`..${path.sep}`) ? [`:(exclude)${relative}`] : [];
+  });
+  const inclusions = includedRoots.length > 0 ? includedRoots.map((root) => path.join(git.pathspec === "." ? "" : git.pathspec, root)) : [git.pathspec];
+  return [...inclusions, ...exclusions];
+}
+function directoryFingerprint(root, excludedRoots, includedRoots) {
+  const hash = createHash("sha256");
+  const resolvedRoot = path.resolve(root);
+  const roots = includedRoots.length > 0 ? includedRoots : [""];
+  for (const included of roots) {
+    hashDirectory(
+      hash,
+      resolvedRoot,
+      included,
+      new Set(excludedRoots.map((entry) => path.resolve(entry)))
+    );
+  }
+  return hash.digest("hex");
+}
+function hashDirectory(hash, root, relative, excludedRoots) {
+  const absolute = path.join(root, relative);
+  if ([...excludedRoots].some(
+    (excluded) => absolute === excluded || absolute.startsWith(`${excluded}${path.sep}`)
+  )) return;
+  let stat;
+  try {
+    stat = fs.lstatSync(absolute);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      hash.update(`absent\0${relative}\0`);
+      return;
+    }
+    throw error;
+  }
+  if (stat.isDirectory()) {
+    hash.update(`directory\0${relative}\0`);
+    for (const name of fs.readdirSync(absolute).sort()) {
+      if (relative === "" && (name === ".git" || name === "node_modules" || name === "temp")) continue;
+      hashDirectory(hash, root, path.join(relative, name), excludedRoots);
+    }
+    return;
+  }
+  if (stat.isSymbolicLink()) {
+    throw new Error(`Execution provenance source must not be a symbolic link: ${absolute}`);
+  }
+  hash.update(`file\0${relative}\0`);
+  hash.update(readRegularFileNoFollow(absolute));
+  hash.update("\0");
+}
+function fileFingerprint(filePath) {
+  return createHash("sha256").update(readRegularFileNoFollow(filePath)).digest("hex");
+}
+function readPathIdentity(filePath) {
+  const stat = fs.lstatSync(filePath);
+  if (stat.isSymbolicLink()) {
+    throw new Error(`Execution provenance source must not be a symbolic link: ${filePath}`);
+  }
+  return readRegularFileNoFollow(filePath);
+}
+function readRegularFileNoFollow(filePath) {
+  let fd;
+  try {
+    fd = fs.openSync(filePath, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+  } catch (error) {
+    if (error.code === "ELOOP") {
+      throw new Error(`Execution provenance source must not be a symbolic link: ${filePath}`);
+    }
+    throw error;
+  }
+  try {
+    if (!fs.fstatSync(fd).isFile()) {
+      throw new Error(`Execution provenance source is not a regular file: ${filePath}`);
+    }
+    return fs.readFileSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+function displayPath(projectRoot, filePath) {
+  const relative = path.relative(path.resolve(projectRoot), path.resolve(filePath));
+  return relative !== ".." && !relative.startsWith(`..${path.sep}`) ? relative || "." : path.resolve(filePath);
+}
+function gitText(cwd, args) {
+  return gitBuffer(cwd, args).toString("utf8");
+}
+function gitBuffer(cwd, args) {
+  return execFileSync("git", args, {
+    cwd,
+    encoding: "buffer",
+    maxBuffer: 128 * 1024 * 1024,
+    stdio: ["ignore", "pipe", "ignore"]
+  });
+}
+function compareSource(drift, phase, prefix, start, current) {
+  compare(drift, phase, `${prefix}.head`, start.head, current.head);
+  compare(drift, phase, `${prefix}.status`, start.status, current.status);
+  compare(
+    drift,
+    phase,
+    `${prefix}.sourceFingerprint`,
+    start.sourceFingerprint,
+    current.sourceFingerprint
+  );
+}
+function compare(drift, phase, field, start, current) {
+  if (start !== current) drift.push({ phase, field, start, current });
+}
+function indexProvenanceArtifact(artifactManifestPath, record) {
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(artifactManifestPath, "utf8"));
+  } catch {
+    return;
+  }
+  if (!manifest || typeof manifest !== "object" || Array.isArray(manifest)) return;
+  const document = manifest;
+  const artifacts = Array.isArray(document.artifacts) ? document.artifacts : [];
+  document.artifacts = [
+    ...artifacts.filter((artifact) => !artifact || typeof artifact !== "object" || Array.isArray(artifact) || artifact.path !== "execution-provenance.json"),
+    {
+      path: "execution-provenance.json",
+      type: "json",
+      label: "Execution provenance",
+      category: "system",
+      metadata: {
+        valid: record.valid,
+        errorCode: record.valid ? null : "PROVENANCE_DRIFT"
+      }
+    }
+  ];
+  fs.writeFileSync(artifactManifestPath, `${JSON.stringify(document, null, 2)}
+`);
+}
+export {
+  ProvenanceDriftError,
+  captureExecutionProvenance,
+  executionProvenanceDrift,
+  writeExecutionProvenance
+};

package/dist/run-diagnostics.js

@@ -8,6 +8,7 @@ import { ensureExtensionConsoleCapture } from "./adapters/extension/console-capt
 const MAX_CAPTURE_BYTES = 512 * 1024;
 const MAX_FINDINGS = 20;
 const MAX_PREVIEW_CHARS = 320;
+const RAW_APP_LOG_ARTIFACT = "diagnostics-app-log.txt";
 function readRunDiagnosticsDocument(diagnosticsPath) {
   if (typeof diagnosticsPath !== "string" || diagnosticsPath.length === 0) return null;
   try {
@@ -53,11 +54,15 @@ function finishRunDiagnostics(baseline, result) {
   if (!baseline) return result;
   try {
     const bufferedIssues = baseline.mobileIssueBuffer ? collectMobileIssueBuffer(baseline.mobileIssueBuffer.projectRoot) : void 0;
-    const diagnostics = collectRunDiagnostics(baseline, bufferedIssues);
+    const { diagnostics, rawAppLog } = collectRunDiagnosticsCapture(baseline, bufferedIssues);
     const artifactsDir = path.dirname(result.summaryPath);
     const diagnosticsPath = path.join(artifactsDir, "diagnostics.json");
     fs.writeFileSync(diagnosticsPath, `${JSON.stringify(diagnostics, null, 2)}
 `);
+    fs.writeFileSync(
+      path.join(artifactsDir, RAW_APP_LOG_ARTIFACT),
+      redactDiagnosticText(rawAppLog.toString("utf8"))
+    );
     indexDiagnosticArtifact(result.artifactManifestPath);
     indexDiagnosticSummary(result.summaryPath, diagnostics);
     return {
@@ -83,6 +88,9 @@ function finishRunDiagnostics(baseline, result) {
   }
 }
 function collectRunDiagnostics(baseline, bufferedIssues) {
+  return collectRunDiagnosticsCapture(baseline, bufferedIssues).diagnostics;
+}
+function collectRunDiagnosticsCapture(baseline, bufferedIssues) {
   const stat = safeStat(baseline.source.path);
   const source = {
     label: baseline.source.label,
@@ -91,9 +99,11 @@ function collectRunDiagnostics(baseline, bufferedIssues) {
     endOffset: stat?.size ?? baseline.offset,
     bytesRead: 0,
     truncated: false,
-    inAppBuffer: bufferedIssues === void 0 ? "n/a" : bufferedIssues === null ? "unavailable" : "collected"
+    inAppBuffer: bufferedIssues === void 0 ? "n/a" : bufferedIssues === null ? "unavailable" : "collected",
+    rawArtifact: RAW_APP_LOG_ARTIFACT,
+    redacted: true
   };
-  let text = "";
+  let rawAppLog = Buffer.alloc(0);
   if (stat) {
     const sameFile = baseline.inode === void 0 || baseline.inode === stat.ino;
     const startOffset = sameFile && stat.size >= baseline.offset ? baseline.offset : 0;
@@ -103,8 +113,9 @@ function collectRunDiagnostics(baseline, bufferedIssues) {
     source.endOffset = stat.size;
     source.bytesRead = bytesToRead;
     source.truncated = available > MAX_CAPTURE_BYTES;
-    if (bytesToRead > 0) text = readSlice(baseline.source.path, startOffset, bytesToRead);
+    if (bytesToRead > 0) rawAppLog = readSlice(baseline.source.path, startOffset, bytesToRead);
   }
+  const text = rawAppLog.toString("utf8");
   const allFindings = dedupeFindings(
     [
       ...text.split(/\r?\n/u).map(classifyLine).filter((finding) => finding !== null),
@@ -113,9 +124,10 @@ function collectRunDiagnostics(baseline, bufferedIssues) {
   );
   const findings = allFindings.slice(0, MAX_FINDINGS);
   const counts = countFindings(allFindings);
+  const omittedFindingCount = Math.max(0, allFindings.length - findings.length);
   const status = counts.total > 0 ? "review" : stat || bufferedIssues !== void 0 && bufferedIssues !== null ? "clean" : "unavailable";
-  const note = counts.total > 0 ? `Observed ${counts.total} distinct application warning/error event(s) during the recipe run; relation to the task is not determined.` : status === "clean" ? "No application warnings or errors were emitted during the recipe run." : "Application diagnostics were unavailable for this run.";
-  return {
+  const note = counts.total > 0 ? `Observed ${counts.total} distinct application warning/error event(s) during the recipe run; showing ${findings.length} preview(s) and omitting ${omittedFindingCount}. Relation to the task is not determined.` : status === "clean" ? "No application warnings or errors were emitted during the recipe run." : "Application diagnostics were unavailable for this run.";
+  return { diagnostics: {
     schemaVersion: 1,
     scope: "recipe-run-application",
     status,
@@ -123,8 +135,10 @@ function collectRunDiagnostics(baseline, bufferedIssues) {
     note,
     source,
     counts,
+    displayedFindingCount: findings.length,
+    omittedFindingCount,
     findings
-  };
+  }, rawAppLog };
 }
 function classifyLine(line) {
   const trimmed = line.trim();
@@ -180,7 +194,10 @@ function runMobileIssueCommand(projectRoot, command) {
   }
 }
 function redactPreview(value) {
-  return value.replace(/\b(Bearer)\s+\S+/giu, "$1 [REDACTED]").replace(/\b(api[-_]?key|password|passphrase|mnemonic|seed(?:Phrase)?|privateKey|secret|token|authorization|vault)\b\s*[:=]\s*(?:"[^"]*"|'[^']*'|\S+)/giu, "$1=[REDACTED]").replace(/\b(?:0x)?[a-f0-9]{64,}\b/giu, "[REDACTED_HEX]").replace(/(https?:\/\/[^\s?]+)\?\S+/giu, "$1?[REDACTED_QUERY]").slice(0, MAX_PREVIEW_CHARS);
+  return redactDiagnosticText(value).slice(0, MAX_PREVIEW_CHARS);
+}
+function redactDiagnosticText(value) {
+  return value.replace(/\b(Bearer)\s+\S+/giu, "$1 [REDACTED]").replace(/(["'])(api[-_]?key|password|passphrase|mnemonic|seed(?:Phrase)?|privateKey|secret|token|authorization|vault)\1\s*:\s*(?:"[^"]*"|'[^']*'|[^,\s}\]]+)/giu, '$1$2$1:"[REDACTED]"').replace(/\b(api[-_]?key|password|passphrase|mnemonic|seed(?:Phrase)?|privateKey|secret|token|authorization|vault)\b\s*[:=]\s*(?:"[^"]*"|'[^']*'|\S+)/giu, "$1=[REDACTED]").replace(/\b(?:0x)?[a-f0-9]{64,}\b/giu, "[REDACTED_HEX]").replace(/(https?:\/\/[^\s?]+)\?\S+/giu, "$1?[REDACTED_QUERY]");
 }
 function dedupeFindings(findings) {
   const byFingerprint = /* @__PURE__ */ new Map();
@@ -201,7 +218,7 @@ function readSlice(filePath, offset, length) {
   try {
     const buffer = Buffer.alloc(length);
     const bytesRead = fs.readSync(fd, buffer, 0, length, offset);
-    return buffer.subarray(0, bytesRead).toString("utf8");
+    return buffer.subarray(0, bytesRead);
   } finally {
     fs.closeSync(fd);
   }
@@ -218,12 +235,18 @@ function indexDiagnosticArtifact(manifestPath) {
   if (!manifest) return;
   const artifacts = Array.isArray(manifest.artifacts) ? manifest.artifacts : [];
   manifest.artifacts = [
-    ...artifacts.filter((artifact) => !isRecord(artifact) || artifact.path !== "diagnostics.json"),
+    ...artifacts.filter((artifact) => !isRecord(artifact) || !["diagnostics.json", RAW_APP_LOG_ARTIFACT].includes(String(artifact.path))),
     {
       path: "diagnostics.json",
       type: "json",
       label: "Run-scoped application diagnostics",
       category: "diagnostic"
+    },
+    {
+      path: RAW_APP_LOG_ARTIFACT,
+      type: "log",
+      label: "Redacted run-scoped application log slice",
+      category: "diagnostic"
     }
   ];
   fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}
@@ -236,7 +259,9 @@ function indexDiagnosticSummary(summaryPath, diagnostics) {
     status: diagnostics.status,
     nonBlocking: true,
     counts: diagnostics.counts,
-    diagnosticsPath: "diagnostics.json"
+    diagnosticsPath: "diagnostics.json",
+    appLogPath: RAW_APP_LOG_ARTIFACT,
+    appLogRedacted: true
   };
   fs.writeFileSync(summaryPath, `${JSON.stringify(summary, null, 2)}
 `);

package/dist/runner.js

@@ -2,6 +2,7 @@ import { execFileSync, execSync } from "node:child_process";
 import { OFFICIAL_RECIPE_ACTIONS } from "@farmslot/protocol";
 import { createMetaMaskAdapters, createMetaMaskUiTransport } from "./adapters.js";
 import { bridgeCommand } from "../library/actions/mobile/platform/bridge.mjs";
+import { resolveMobileToolPath } from "../library/actions/mobile/platform/tool-paths.mjs";
 import {
   mobileSourceFingerprint,
   recordMobileSourceBaseline
@@ -334,21 +335,29 @@ function mobileSourceAwareLifecycleAdapters(adapter, lifecycle, readinessProbe =
   fingerprint: mobileSourceFingerprint,
   record: recordMobileSourceBaseline
 }, processIdentity = {
-  readIosPid: readIosAppPid
+  readIosPid: readIosAppPid,
+  readAndroidPid: readAndroidAppPid
 }) {
   if (adapter !== "mobile") return lifecycle;
   return lifecycle.map((entry) => ({
     ...entry,
     async execute(node, context) {
-      if (context.env?.METAMASK_RECIPE_MOBILE_OPAQUE_RUNTIME === "1") {
+      const command = node.command ?? node.event ?? node.state;
+      const opaqueRuntime = context.env?.METAMASK_RECIPE_MOBILE_OPAQUE_RUNTIME === "1";
+      const requiresProcessContinuity = command !== "restart" && node.require_process_continuity === true;
+      if (opaqueRuntime && !requiresProcessContinuity) {
         return entry.execute(node, context);
       }
-      const command = node.command ?? node.event ?? node.state;
-      const reloadsSource = command === "launch" || command === "foreground" || command === "restart";
-      const checksIosContinuity = command === "foreground" && !isAndroidLifecycle(node, context.env ?? {});
-      const processBefore = checksIosContinuity ? processIdentity.readIosPid(node, context) : void 0;
-      const fingerprint = reloadsSource ? sourceFreshness.fingerprint(context.projectRoot) : void 0;
-      const androidRestart = command === "restart" && isAndroidLifecycle(node, context.env ?? {});
+      const reloadsSource = !opaqueRuntime && (command === "launch" || command === "foreground" || command === "restart");
+      const recordsSource = !opaqueRuntime && command === "restart";
+      const androidLifecycle = isAndroidLifecycle(node, context.env ?? {});
+      const checksIosContinuity = command === "foreground" && !androidLifecycle;
+      const checksRequiredContinuity = requiresProcessContinuity;
+      const recordsProcessIdentity = checksIosContinuity || checksRequiredContinuity;
+      const readProcessId = androidLifecycle ? processIdentity.readAndroidPid ?? readAndroidAppPid : processIdentity.readIosPid;
+      const processBefore = recordsProcessIdentity ? readProcessId(node, context) : void 0;
+      const fingerprint = recordsSource ? sourceFreshness.fingerprint(context.projectRoot) : void 0;
+      const androidRestart = command === "restart" && androidLifecycle;
       const initialNode = androidRestart ? { ...node, settle_ms: 0 } : node;
       const initialResult = await entry.execute(initialNode, context);
       let result = initialResult;
@@ -362,22 +371,26 @@ function mobileSourceAwareLifecycleAdapters(adapter, lifecycle, readinessProbe =
       if (reloadsSource) {
         await readinessProbe(node, context);
       }
-      if (checksIosContinuity) {
-        const processAfter = processIdentity.readIosPid(node, context);
-        const actualTransition = processBefore !== null && processBefore === processAfter ? "foreground_resume" : processAfter !== null ? "cold_relaunch" : "unknown";
+      if (recordsProcessIdentity) {
+        const processAfter = readProcessId(node, context);
+        const processPreserved = processBefore !== null && processBefore === processAfter;
+        const actualTransition = processPreserved ? command === "background" ? "background_same_process" : "foreground_resume" : processAfter !== null ? "cold_relaunch" : "unknown";
+        const processContinuity = processPreserved ? "preserved" : processAfter === null ? "unknown" : "changed";
         const resultRecord = asRecord(result);
         result = {
           ...resultRecord,
           output: {
             ...asRecord(resultRecord.output),
             actualTransition,
+            processContinuity,
             processBefore,
             processAfter
           }
         };
-        if (node.require_process_continuity === true && actualTransition !== "foreground_resume") {
+        if (checksRequiredContinuity && !processPreserved) {
+          const platform = androidLifecycle ? "Android" : "iOS";
           throw new Error(
-            `iOS foreground did not preserve the app process (actualTransition=${actualTransition}, before=${String(processBefore)}, after=${String(processAfter)}); this lifecycle sample is a cold relaunch, not a reconnect.`
+            `${platform} ${String(command)} did not prove app-process continuity (actualTransition=${actualTransition}, before=${String(processBefore)}, after=${String(processAfter)}); this lifecycle sample cannot be classified as a same-process reconnect.`
           );
         }
       }
@@ -390,6 +403,24 @@ function mobileSourceAwareLifecycleAdapters(adapter, lifecycle, readinessProbe =
     }
   }));
 }
+function readAndroidAppPid(node, context) {
+  const env = context.env ?? {};
+  const device = node.adb_serial ?? node.android_device ?? node.device ?? env.ADB_SERIAL ?? env.ANDROID_SERIAL ?? process.env.ADB_SERIAL ?? process.env.ANDROID_SERIAL;
+  const packageId = node.package_id ?? node.packageName ?? node.app_id ?? env.ANDROID_PACKAGE_ID ?? process.env.ANDROID_PACKAGE_ID ?? "io.metamask";
+  if (typeof device !== "string" || typeof packageId !== "string") return null;
+  try {
+    const adb = resolveMobileToolPath("adb", { required: true });
+    const output = execFileSync(
+      adb,
+      ["-s", device, "shell", "pidof", packageId],
+      { encoding: "utf8", timeout: 5e3, stdio: ["ignore", "pipe", "ignore"] }
+    );
+    const pid = Number.parseInt(output.trim().split(/\s+/u)[0] ?? "", 10);
+    return Number.isInteger(pid) && pid > 0 ? pid : null;
+  } catch {
+    return null;
+  }
+}
 function readIosAppPid(node, context) {
   const env = context.env ?? {};
   const device = node.simulator ?? node.ios_simulator ?? env.SIM_UDID ?? env.IOS_SIMULATOR ?? process.env.SIM_UDID ?? process.env.IOS_SIMULATOR;