@deeeed/metamask-harness 0.51.6 → 0.51.7

package/CHANGELOG.md

@@ -1,6 +1,14 @@
 # Changelog
 
-## Unreleased
+## 0.51.7 - 2026-09-14
+
+### Added
+
+- `pr-body render <task-dir>` writes `artifacts/pr-body.md`: the worker's `artifacts/pr-description.md` with the "Validation Recipe", "Validation Logs" (and "Recipe Workflow" when `artifacts/workflow.mmd` exists) sections rendered from the task artifacts with fences that cannot break, replacing any pasted by hand. The farm publication step and the Cook evidence packaging call the same command.
+
+### Changed
+
+- Extension launch focus hold polls every 80 ms instead of 20 ms, and the reopen launcher honours `MM_HARNESS_FOCUS_SETTLE_MS` like the primary launcher.
 
 ## 0.51.6 - 2026-09-14
 

package/README.md

@@ -193,6 +193,20 @@ Teams maintain their library checkouts. Update them before starting a task;
 the harness records local revisions and recipe digests but does not fetch or
 check for upstream updates. Keep the selected library unchanged during a run.
 
+## Publish a change
+
+```bash
+# Write artifacts/pr-description.md in the repository PR template shape (prose
+# only), then render the publishable body.
+mm-harness pr-body render temp/tasks/dev/TAT-1 --command 'mm-harness run artifacts/recipe.json'
+```
+
+`pr-body render` writes `artifacts/pr-body.md`: the description with the "Validation
+Recipe" and "Validation Logs" sections rendered from `artifacts/recipe.json` and
+`artifacts/recipe-run/report.md` (and "Recipe Workflow" from `artifacts/workflow.mmd`
+when it exists), replacing any pasted by hand. The worker never pastes artifacts
+into markdown, so fences cannot break.
+
 ## Review a change
 
 ```bash

package/adapters/extension/ensure-browser.sh

@@ -519,7 +519,9 @@ const releaseFocusHold = () => {
   if (process.env.MM_HARNESS_FOCUS_BROWSER === '1') {
     await page.bringToFront().catch(() => {});
   } else {
-    await new Promise(r => setTimeout(r, 1000));
+    const settleMs = Number(process.env.MM_HARNESS_FOCUS_SETTLE_MS);
+    const waitMs = Number.isFinite(settleMs) && settleMs >= 0 ? settleMs : 1000;
+    if (waitMs > 0) await new Promise(r => setTimeout(r, waitMs));
     preserveMacFrontmost(previousFrontmost, chromiumApp);
   }
   releaseFocusHold();

package/adapters/extension/launch-browser.cjs

@@ -408,11 +408,11 @@ function cdpListenerPids(port) {
 function terminatePids(pids) {
   const unique = [...new Set(pids)].filter((pid) => pid !== process.pid);
   for (const pid of unique) signalPid(pid, 'SIGTERM');
-  for (let i = 0; i < 10 && unique.some(pidAlive); i += 1) {
+  for (let i = 0; i < 10 && unique.some(processRespondsToSignal); i += 1) {
     spawnSync('sleep', ['0.2']);
   }
   for (const pid of unique) {
-    if (pidAlive(pid)) signalPid(pid, 'SIGKILL');
+    if (processRespondsToSignal(pid)) signalPid(pid, 'SIGKILL');
   }
 }
 
@@ -426,7 +426,7 @@ function signalPid(pid, signal) {
   }
 }
 
-function pidAlive(pid) {
+function processRespondsToSignal(pid) {
   try {
     process.kill(pid, 0);
     return true;

package/adapters/extension/lib/macos-focus.cjs

@@ -3,7 +3,9 @@
 const { execFileSync, spawn } = require('node:child_process');
 const fs = require('node:fs');
 
-const HOLD_INTERVAL_MS = 20;
+// Window activation is not sub-20ms; 80ms keeps the hold responsive while
+// spawning far fewer lsappinfo/open subprocesses per second.
+const HOLD_INTERVAL_MS = 80;
 // Upper bound for one Launch Services query or `open -a`. A short bound made a
 // loaded Mac time out the first query, which silently disabled the whole hold.
 const LS_TIMEOUT_MS = 2000;
@@ -28,6 +30,7 @@ function captureMacFrontmost() {
       timeout: LS_TIMEOUT_MS,
     }));
   } catch {
+    // Best effort: lsappinfo missing, timed out, or the app exited; no focus to preserve.
     return null;
   }
 }
@@ -62,6 +65,7 @@ function currentFrontmostPid() {
     const pid = Number.parseInt((value.match(/"pid"=(\d+)/u) || [])[1], 10);
     return Number.isInteger(pid) && pid > 0 ? pid : null;
   } catch {
+    // Best effort: lsappinfo unavailable or timed out; callers treat null as unknown.
     return null;
   }
 }
@@ -76,6 +80,7 @@ function restoreMacFrontmost(target) {
     });
     return true;
   } catch {
+    // Best effort: `open -a` failed or timed out; the operator keeps whatever is in front.
     return false;
   }
 }
@@ -97,6 +102,7 @@ function restoreMacFrontmostProcess(pid) {
       timeout: LS_TIMEOUT_MS,
     })));
   } catch {
+    // Best effort: lsappinfo unavailable, timed out, or the pid has no Launch Services entry; nothing to restore.
     return false;
   }
 }
@@ -152,6 +158,7 @@ function sameBundle(left, right) {
     try {
       return fs.realpathSync(value);
     } catch {
+      // A path that cannot be resolved is compared as given.
       return value;
     }
   };
@@ -173,6 +180,7 @@ function bundlePathForPid(pid) {
       timeout: LS_TIMEOUT_MS,
     }))?.bundlePath ?? null;
   } catch {
+    // Best effort: lsappinfo unavailable, timed out, or the pid has no Launch Services entry; the hold is skipped.
     return null;
   }
 }
@@ -192,6 +200,7 @@ function parentAlive(pid) {
     process.kill(pid, 0);
     return true;
   } catch {
+    // ESRCH or EPERM: the parent is gone or not ours; either way the hold must end.
     return false;
   }
 }

package/adapters/extension/lib/validation-process-ownership.cjs

@@ -55,6 +55,7 @@ function pidAlive(pid) {
     if (error.code === 'ESRCH') return false;
     throw error;
   }
+  // Requires macOS or procps ps; a ps that rejects these flags prints nothing, which is treated as dead.
   const state = spawnSync('ps', ['-o', 'stat=', '-p', String(pid)], {
     encoding: 'utf8',
     stdio: ['ignore', 'pipe', 'ignore'],

package/dist/cli-commands.js

@@ -11,6 +11,7 @@ const SPEC = {
     { name: "help", desc: "Load version-matched recipe guidance (help review composes the review guide)", args: ["review"], flags: ["--json", "--adapter", "--target", "--domain"] },
     { name: "review", desc: "Materialize a review checklist composed from the base review and a team library", args: ["checklist"], flags: ["--domain", "--since", "--base", "--out", "--adapter", "--target", "--json"] },
     { name: "domain", desc: "Which team library owns the change (declared value, else owned-paths.json)", flags: ["--domain", "--base", "--adapter", "--target", "--json"] },
+    { name: "pr-body", desc: "Render the publishable PR body: pr-description.md plus the recipe and run sections built from artifacts", args: ["render", "<task-dir>"], flags: ["--command", "--out", "--json"] },
     { name: "config", desc: "Per-engineer locations: libraries.<name>, references.<adapter>", args: ["list", "path", "get", "set", "unset"], flags: ["--json"] },
     { name: "tutorial", desc: "Open the visual recipe tutorial", flags: ["--json", "--no-open"] },
     { name: "setup-base", desc: "Bootstrap numbered product checkouts", flags: ["--dir", "--counts", "--only", "--dry-run", "--force", "--json", "--show-config", "--reset-config", "--skip-harness-update"] },

package/dist/cli.js

@@ -28,6 +28,7 @@ import { handleLast } from "./commands/last.js";
 import { handleReview } from "./commands/review.js";
 import { handleDomain } from "./commands/domain.js";
 import { handleConfig } from "./commands/config.js";
+import { handlePrBody } from "./commands/pr-body.js";
 import { parseArgs, targetPath } from "./commands/parse-args.js";
 const COMMANDS = {
   actions: handleActions,
@@ -138,6 +139,7 @@ async function main(argv) {
   if (command === "review") return handleReview(argv.slice(1));
   if (command === "domain") return handleDomain(argv.slice(1));
   if (command === "config") return handleConfig(argv.slice(1));
+  if (command === "pr-body") return handlePrBody(argv.slice(1));
   const handler = COMMANDS[command];
   if (!handler) throw new Error(`Unknown command: ${command}`);
   return handler(parseArgs(argv.slice(1), command));

package/dist/command-contract.js

@@ -77,6 +77,14 @@ const PUBLIC_COMMAND_CONTRACTS = {
       "--base": value()
     })
   },
+  "pr-body": {
+    options: options(HELP, JSON, {
+      "--command": value(),
+      "--out": value()
+    }),
+    positionals: [{ label: "action", choices: ["render"] }, { label: "task-dir" }],
+    minimumPositionals: 2
+  },
   config: {
     options: options(HELP, JSON),
     positionals: [

package/dist/commands/pr-body.js

@@ -0,0 +1,31 @@
+import fs from "node:fs";
+import path from "node:path";
+import { BODY_FILE, renderPrBody } from "../pr-body/render.js";
+import { optionFlag, optionString, parseArgs, usageError } from "./parse-args.js";
+const USAGE = "Usage: mm-harness pr-body render <task-dir> [--command <text>] [--out <file>] [--json]";
+async function handlePrBody(argv) {
+  const parsed = parseArgs(argv, "pr-body");
+  const [action, taskArg] = parsed.positional;
+  if (action !== "render" || !taskArg) throw usageError(USAGE);
+  const taskDir = path.resolve(taskArg);
+  if (!fs.existsSync(path.join(taskDir, "artifacts"))) {
+    throw usageError(`${taskDir} has no artifacts/ directory; pass the task directory mm-harness task init wrote.`);
+  }
+  const command = optionString(parsed.options, "command");
+  const result = renderPrBody({ taskDir, ...command ? { command } : {} });
+  const out = path.resolve(optionString(parsed.options, "out") ?? path.join(taskDir, "artifacts", BODY_FILE));
+  fs.mkdirSync(path.dirname(out), { recursive: true });
+  fs.writeFileSync(out, result.body);
+  if (optionFlag(parsed.options, "json")) {
+    process.stdout.write(`${JSON.stringify({ command: "pr-body", subcommand: "render", status: "ok", taskDir, out, ...result, body: void 0 }, null, 2)}
+`);
+  } else {
+    process.stdout.write(`pr body: ${out}
+  ${result.sections.join("\n  ")}
+`);
+  }
+  return 0;
+}
+export {
+  handlePrBody
+};

package/dist/mm-harness-cli.js

@@ -91,6 +91,28 @@ Example:
   mm-harness domain
   mm-harness domain --json`
   },
+  {
+    name: "pr-body",
+    summary: "Render the publishable PR body: the authored description plus the recipe and run log sections built from artifacts.",
+    example: "mm-harness pr-body render temp/tasks/dev/TAT-1",
+    helpText: `mm-harness pr-body render <task-dir> [flags]
+
+  Reads <task-dir>/artifacts/pr-description.md (the PR body the worker wrote in
+  the repository PR template shape) and inserts the machine sections rendered
+  from artifacts: "Validation Recipe" from artifacts/recipe.json, "Validation
+  Logs" from artifacts/recipe-run/report.md, and "Recipe Workflow" from
+  artifacts/workflow.mmd when it exists. Any such section the worker pasted by
+  hand is replaced. The sections go before the first checklist section, else at
+  the end. Fences are always longer than any backtick run in the content and
+  close on their own line. Writes <task-dir>/artifacts/pr-body.md.
+
+  --command <text>  Recipe invocation to show above the run log
+  --out <file>      Write elsewhere than artifacts/pr-body.md
+  --json            Machine-readable result
+
+Example:
+  mm-harness pr-body render temp/tasks/dev/TAT-1 --json`
+  },
   {
     name: "config",
     summary: "Per-engineer machine locations for team libraries and reference checkouts.",
@@ -856,7 +878,7 @@ const HELP_GROUPS = [
   {
     title: "PROVE",
     blurb: "run recipes and inspect readiness",
-    commands: ["run", "last", "doctor", "check", "checklist", "review", "recipe-quality"]
+    commands: ["run", "last", "doctor", "check", "checklist", "review", "pr-body", "recipe-quality"]
   },
   {
     title: "RUNTIME OVERLAY",

package/dist/pr-body/render.js

@@ -0,0 +1,136 @@
+import fs from "node:fs";
+import path from "node:path";
+const PROSE_FILE = "pr-description.md";
+const BODY_FILE = "pr-body.md";
+const RECIPE_HEADING = "## **Validation Recipe**";
+const LOGS_HEADING = "## **Validation Logs**";
+const WORKFLOW_HEADING = "## **Recipe Workflow**";
+function headingKey(heading) {
+  return heading.replace(/^#+\s*/, "").replace(/[*_`]/g, "").replace(/\s+/g, " ").trim().toLowerCase();
+}
+const MACHINE_KEYS = new Set([RECIPE_HEADING, LOGS_HEADING, WORKFLOW_HEADING].map(headingKey));
+function levelTwoHeadingLines(lines) {
+  const found = [];
+  lines.forEach((line, index) => {
+    if (/^ {0,3}##(?!#)\s+\S/.test(line)) found.push(index);
+  });
+  return found;
+}
+function fenceFor(content) {
+  let longest = 0;
+  for (const run of content.match(/`+/g) ?? []) longest = Math.max(longest, run.length);
+  return "`".repeat(Math.max(3, longest + 1));
+}
+function fenced(content, info = "") {
+  const fence = fenceFor(content);
+  return `${fence}${info}
+${content.replace(/\n+$/, "")}
+${fence}`;
+}
+function escapeHtml(text) {
+  return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function countRecipeNodes(recipe) {
+  if (!recipe || typeof recipe !== "object") return 0;
+  const record = recipe;
+  if (Array.isArray(record.nodes)) return record.nodes.length;
+  if (Array.isArray(record.steps)) return record.steps.length;
+  const workflow = record.workflow;
+  if (!workflow || typeof workflow !== "object") return 0;
+  return Object.values(workflow).reduce(
+    (total, value) => total + (Array.isArray(value) ? value.length : 0),
+    0
+  );
+}
+function recipeSection(file) {
+  const recipe = JSON.parse(fs.readFileSync(file, "utf8"));
+  const nodes = countRecipeNodes(recipe);
+  const record = recipe && typeof recipe === "object" ? recipe : {};
+  const title = typeof record.title === "string" ? record.title : typeof record.description === "string" ? record.description : "";
+  const summary = escapeHtml(`recipe.json (${nodes} steps${title ? ` \u2014 ${title.slice(0, 120)}` : ""})`);
+  return {
+    nodes,
+    body: [`<details><summary>${summary}</summary>`, "", fenced(JSON.stringify(recipe, null, 2), "json"), "</details>"].join("\n")
+  };
+}
+function logsSection(file, command) {
+  const report = fs.readFileSync(file, "utf8");
+  const status = /^Status:\s*(\S+)/m.exec(report)?.[1];
+  const nodes = /^Nodes:\s*(.+?)\s*$/m.exec(report)?.[1];
+  const summary = escapeHtml(status || nodes ? `Full output (${[nodes, status].filter(Boolean).join(", ")})` : "Full output");
+  const lines = [];
+  if (command) lines.push("Command:", "", fenced(command, "bash"), "");
+  lines.push(`<details><summary>${summary}</summary>`, "", fenced(report), "</details>");
+  return lines.join("\n");
+}
+function trimEnd(lines) {
+  let end = lines.length;
+  while (end > 0 && !lines[end - 1].trim()) end -= 1;
+  return lines.slice(0, end);
+}
+function renderPrBody(input) {
+  const artifacts = path.join(input.taskDir, "artifacts");
+  const prosePath = path.join(artifacts, PROSE_FILE);
+  if (!fs.existsSync(prosePath)) {
+    throw new Error(`Missing ${path.relative(input.taskDir, prosePath)}: write the PR description there first.`);
+  }
+  const recipePath = path.join(artifacts, "recipe.json");
+  const reportPath = path.join(artifacts, "recipe-run", "report.md");
+  const workflowPath = path.join(artifacts, "workflow.mmd");
+  const machine = [];
+  let recipe = null;
+  if (fs.existsSync(recipePath)) {
+    const rendered = recipeSection(recipePath);
+    recipe = { nodes: rendered.nodes, path: path.relative(input.taskDir, recipePath) };
+    machine.push([RECIPE_HEADING, rendered.body]);
+  } else {
+    machine.push([RECIPE_HEADING, "Not applicable: this task has no `artifacts/recipe.json`."]);
+  }
+  const hasReport = fs.existsSync(reportPath);
+  machine.push([
+    LOGS_HEADING,
+    hasReport ? logsSection(reportPath, input.command) : "Not applicable: no recipe run report under `artifacts/recipe-run/`."
+  ]);
+  const hasWorkflow = fs.existsSync(workflowPath);
+  if (hasWorkflow) {
+    machine.push([
+      WORKFLOW_HEADING,
+      ["<details><summary>workflow.mmd</summary>", "", fenced(fs.readFileSync(workflowPath, "utf8"), "mermaid"), "</details>"].join("\n")
+    ]);
+  }
+  const lines = fs.readFileSync(prosePath, "utf8").replace(/\r\n?/g, "\n").split("\n");
+  const headings = levelTwoHeadingLines(lines);
+  const keep = new Array(lines.length).fill(true);
+  let insertAt = lines.length;
+  headings.forEach((start, at) => {
+    const end = headings[at + 1] ?? lines.length;
+    const key = headingKey(lines[start]);
+    if (MACHINE_KEYS.has(key)) keep.fill(false, start, end);
+    else if (insertAt === lines.length && /checklist/.test(key)) insertAt = start;
+  });
+  const before = lines.slice(0, insertAt).filter((_, index) => keep[index]);
+  const after = lines.slice(insertAt).filter((_, index) => keep[insertAt + index]);
+  const generated = machine.flatMap(([heading, body2]) => [heading, "", body2, ""]);
+  const body = [...trimEnd(before), "", ...generated, ...after].join("\n").replace(/\n{3,}/g, "\n\n").replace(/\n*$/, "\n");
+  return {
+    body,
+    sections: machine.map(([heading]) => heading),
+    recipe,
+    run: hasReport ? { path: path.relative(input.taskDir, reportPath) } : null,
+    workflow: hasWorkflow ? { path: path.relative(input.taskDir, workflowPath) } : null
+  };
+}
+export {
+  BODY_FILE,
+  LOGS_HEADING,
+  PROSE_FILE,
+  RECIPE_HEADING,
+  WORKFLOW_HEADING,
+  countRecipeNodes,
+  escapeHtml,
+  fenceFor,
+  fenced,
+  headingKey,
+  levelTwoHeadingLines,
+  renderPrBody
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deeeed/metamask-harness",
-  "version": "0.51.6",
+  "version": "0.51.7",
   "type": "module",
   "bin": {
     "mm-harness": "bin/mm-harness"