machine-bridge-mcp 0.11.1 → 0.12.0

package/docs/TESTING.md

@@ -15,10 +15,12 @@ The suite includes:
 - release-impact enforcement requiring a new package version and CHANGELOG section for release-relevant changes;
 - release-state diagnostics distinguishing missing local/remote version tags from tags that point to the wrong commit, including the required publication order;
 - generated Cloudflare Worker types and strict TypeScript checking, including unused-local and unused-parameter rejection;
-- syntax validation for every shipped JavaScript entry point;
+- recursive syntax validation for every JavaScript file under the shipped/runtime/test roots plus the shell wrapper;
 - shared tool-catalog schema, annotation, and profile-inventory checks;
 - default working-agreement injection without user files, bounded automatic project metadata, script-body non-disclosure, user-global opt-out, repository opt-out rejection, global `model_instructions_file` injection in stdio/remote initialization, hierarchical precedence, live project/skill rescanning and fingerprints, automatic task ranking/loading, command override/removal, direct argv handling, timeout ceilings, and execution-profile denial;
-- foreground takeover of active and orphaned background daemons, legacy lock identification from canonicalized process arguments, foreground-process protection, actual-PID exit waiting, non-forcing timeout guidance, daemon lock mode/version metadata, launchd service-target semantics, and silent idempotent duplicate service starts;
+- concurrent complete-before-visible lock claims, atomic replacement under active readers, malformed-lock grace, snapshot/token-safe reclamation, absolute-age expiry, PID-reuse detection, and bounded startup-lock waiting;
+- foreground takeover of active and orphaned background daemons, legacy lock identification from canonicalized process arguments, foreground-process protection, actual-PID exit waiting, non-forcing timeout guidance, daemon lock mode/version/process-start metadata, launchd service-target semantics, and silent idempotent duplicate service starts;
+- fail-closed service lifecycle ordering for provider-stop, all-workspace daemon-stop, and definition removal, including platform/daemon/removal failure injection and normalized macOS/systemd/Windows results;
 - machine-level browser-broker ownership/client proxying, authenticated extension origin/subprotocol, non-cacheable local pairing, pairing-token non-disclosure, resource-backed upload routing, and broker result redaction;
 - canonical path and symbolic-link escape tests;
 - relative-path privacy and error-path redaction tests;
@@ -29,16 +31,16 @@ The suite includes:
 - nested Git repository detection and helper suppression;
 - author-email privacy in `git_log`;
 - isolated command HOME/temp/cache behavior;
-- one-shot timeout, descendant termination, cancellation, and process-session interaction;
+- one-shot timeout, descendant process-group/tree termination including descendants that ignore graceful shutdown, cancellation, and process-session interaction;
 - layered fixed runtime diagnostics for filesystem, direct process, shell, managed-job storage, and resource availability;
 - local resource CLI registration, permission checks, dynamic reload, state-path redaction, and content non-disclosure;
 - real Ed25519 and RSA generation, idempotent reuse, public/private correspondence, mode enforcement, incomplete/mismatched/symlink rejection, and private-content non-disclosure;
 - real-machine canonical-full sandbox acceptance for outside-workspace I/O, direct/shell execution, full environment inheritance, SSH prerequisites, temporary authorized-key writing, and detached cleanup without external state changes;
 - deterministic injected atomic-replace failures and repeated Windows full-sandbox runs to catch transient file-sharing races;
 - canonical named-profile repair and full-only tool exposure parity between local and Worker policy filters;
-- managed-job staging/local approval/cancel-before-start, detachment, job-scoped temporary files, resource hash verification/redaction, discard capture, finally execution, cancellation escalation, plan scrubbing, and dead-runner recovery;
-- daemon/startup locking and state corruption recovery;
-- guarded state-root removal, schema migration, policy-origin persistence, and legacy implicit-default migration;
+- managed-job staging/local approval/cancel-before-start, detachment, job-scoped temporary files, resource hash verification/redaction, discard capture, finally execution, descendant-tree escalation, token/snapshot-safe transition locks, runner process identity, plan scrubbing, PID-reuse-safe dead-runner recovery, and legacy PID-file compatibility;
+- daemon/startup locking, successfully-read corrupt-JSON recovery, and explicit propagation/preservation of oversized, symbolic-link, permission, and I/O failures;
+- guarded state-root removal, unsafe state-root/workspace overlap rejection before creation, all-profile lock/daemon scanning, schema migration, policy-origin persistence, and legacy implicit-default migration;
 - no filename-based sensitive-file denial under unrestricted policy;
 - log redaction, control-character handling, message/field bounds, suppression of both successful and failed per-tool events outside debug, service warning-level configuration, and idempotent bounded migration of legacy log formats;
 - deterministic relay connection lifecycle coverage for transport construction/error/deadline, pre-handshake `welcome` validation, authenticated `hello_ack` readiness, identity/version mismatch, retryable Worker handshake errors, fatal protocol errors, autonomous outage-reminder backoff, handshake and heartbeat timeout, brief-outage suppression, sustained-outage escalation, recovery summaries, and supersession;
@@ -65,6 +67,7 @@ GitHub Actions executes the main suite on Linux, macOS, and Windows using the pi
 ## Test design rules
 
 - Tests should exercise the public boundary rather than only helper functions when practical.
+- Lock, service lifecycle, state deletion, detached process, and credential changes require behavior-level concurrent or fault-injection coverage; source-string assertions are supplementary only.
 - Every permission-expanding feature needs a denial test. Browser/application features also require a token/value/content non-disclosure assertion.
 - Every bounded resource needs an over-limit test.
 - Every multi-stage mutation needs a no-partial-commit test.
@@ -80,10 +83,10 @@ Run `npm run privacy:check` before committing and before packaging. Developers s
 
 ## Package manifest
 
-`npm run package:test` executes a real silent `npm pack --dry-run --json`, requires clean parseable JSON, rejects sensitive local artifacts and credential-like file classes, and verifies that privacy/engineering guidance, the runtime/relay/secure-file/browser/app modules, packaged browser extension, contribution discipline, and privacy/release-impact checkers are present in the published package. `npm run install:test` packs the real tarball, installs it into an isolated global prefix with the documented npm 12 options, rejects blocked-script warnings, confirms optional `fsevents` is absent, and runs the installed CLI.
+`npm run package:test` executes a real silent `npm pack --dry-run --json`, requires clean parseable JSON, rejects sensitive local artifacts and credential-like file classes, validates every packaged mode as `0644` or `0755`, and verifies that privacy/engineering guidance, runtime/relay/secure-file/lock/service/browser/app modules, all package-script helpers, the packaged browser extension, contribution discipline, and privacy/release-impact checkers are present. `npm run install:test` packs the real tarball, installs it into an isolated global prefix with the documented npm 12 options, rejects blocked-script warnings, confirms optional `fsevents` is absent, and runs the installed CLI.
 
 The stdio integration test also sends an oversized line, verifies bounded rejection, and confirms that the next valid request is still processed.
 
 ## Architecture and documentation regression checks
 
-`npm run architecture:test` rejects local-module dependency cycles, missing relative imports, obsolete `LocalDaemon`/`daemon.mjs` naming, broken relative Markdown links, invisible ASCII control bytes in repository text, removal of the owner-required default-`full` engineering invariant, and accidental publication of `.project-local/` notes.
+`npm run architecture:test` rejects local-module dependency cycles, missing static or dynamic relative imports, package scripts that reference missing files, drift from the recursive syntax scanner, incomplete executable package directories, inconsistent installation guidance, obsolete `LocalDaemon`/`daemon.mjs` naming, broken relative Markdown links, invisible ASCII control bytes in repository text, removal of the owner-required default-`full` engineering invariant, and accidental publication of `.project-local/` notes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "machine-bridge-mcp",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "description": "Cross-client MCP bridge for local agent context, structured browser and application automation, files, Git, processes, resources, and durable jobs over stdio or OAuth relay.",
   "type": "module",
   "license": "MIT",
@@ -20,10 +20,7 @@
     "src/local",
     "src/shared",
     "src/worker/index.ts",
-    "scripts/sync-worker-version.mjs",
-    "scripts/privacy-check.mjs",
-    "scripts/release-impact-check.mjs",
-    "scripts/network-retry.mjs",
+    "scripts",
     "wrangler.jsonc",
     "tsconfig.json",
     "README.md",
@@ -44,8 +41,8 @@
     "prepublishOnly": "npm run check && npm run version:check && npm run release:check",
     "worker:types": "wrangler types src/worker/worker-configuration.d.ts",
     "typecheck": "npm run worker:types && tsc -p tsconfig.json --noEmit",
-    "syntax": "sh -n mbm && node --check bin/machine-mcp.mjs && node --check src/local/cli.mjs && node --check src/local/runtime.mjs && node --check src/local/agent-context.mjs && node --check src/local/default-instructions.mjs && node --check src/local/daemon-process.mjs && node --check src/local/browser-bridge.mjs && node --check src/local/app-automation.mjs && node --check src/local/relay-connection.mjs && node --check src/local/secure-file.mjs && node --check src/local/patch.mjs && node --check src/local/process-sessions.mjs && node --check src/local/tools.mjs && node --check src/local/stdio.mjs && node --check src/local/state.mjs && node --check src/local/shell.mjs && node --check src/local/service.mjs && node --check src/local/log.mjs && node --check src/local/atomic-fs.mjs && node --check src/local/ssh-key.mjs && node --check src/local/resource-operations.mjs && node --check src/local/full-access-test.mjs && node --check src/local/managed-jobs.mjs && node --check src/local/job-runner.mjs && node --check scripts/sync-worker-version.mjs && node --check scripts/privacy-check.mjs && node --check scripts/release-impact-check.mjs && node --check scripts/network-retry.mjs && node --check scripts/release-state.mjs && node --check scripts/github-release.mjs && node --check tests/worker-integration-test.mjs && node --check tests/stdio-integration-test.mjs && node --check tests/catalog-test.mjs && node --check tests/agent-context-test.mjs && node --check tests/browser-bridge-test.mjs && node --check tests/app-automation-test.mjs && node --check tests/local-self-test.mjs && node --check tests/runtime-self-test.mjs && node --check tests/managed-jobs-test.mjs && node --check tests/ssh-key-test.mjs && node --check tests/full-access-test.mjs && node --check tests/atomic-fs-test.mjs && node --check tests/package-test.mjs && node --check tests/release-impact-test.mjs && node --check tests/release-state-test.mjs && node --check tests/privacy-test.mjs && node --check tests/network-retry-test.mjs && node --check tests/relay-connection-test.mjs && node --check tests/install-smoke-test.mjs && node --check tests/secure-file-test.mjs && node --check tests/architecture-test.mjs && node --check browser-extension/service-worker.js && node --check browser-extension/pairing.js && node --check browser-extension/page-automation.js",
-    "check": "npm run privacy:check && npm run privacy:test && npm run release-impact:check && npm run release-impact:test && npm run release-state:test && npm run network-retry:test && npm run relay:test && npm run secure-file:test && npm run architecture:test && npm run typecheck && npm run syntax && npm run catalog:test && npm run agent-context:test && npm run browser-bridge:test && npm run app-automation:test && npm run self-test && npm run atomic-fs:test && npm run package:test && npm run ssh-key:test && npm run full-access:test && npm run managed-jobs:test && npm run stdio:integration-test && npm run worker:integration-test",
+    "syntax": "node scripts/syntax-check.mjs",
+    "check": "npm run privacy:check && npm run privacy:test && npm run release-impact:check && npm run release-impact:test && npm run release-state:test && npm run network-retry:test && npm run relay:test && npm run secure-file:test && npm run architecture:test && npm run typecheck && npm run syntax && npm run process-lock:test && npm run service-lifecycle:test && npm run catalog:test && npm run agent-context:test && npm run browser-bridge:test && npm run app-automation:test && npm run self-test && npm run atomic-fs:test && npm run package:test && npm run ssh-key:test && npm run full-access:test && npm run managed-jobs:test && npm run stdio:integration-test && npm run worker:integration-test",
     "worker:dry-run": "wrangler deploy --dry-run",
     "worker:integration-test": "node tests/worker-integration-test.mjs",
     "release:check": "node scripts/github-release.mjs --check",
@@ -70,7 +67,9 @@
     "release-state:test": "node tests/release-state-test.mjs",
     "agent-context:test": "node tests/agent-context-test.mjs",
     "browser-bridge:test": "node tests/browser-bridge-test.mjs",
-    "app-automation:test": "node tests/app-automation-test.mjs"
+    "app-automation:test": "node tests/app-automation-test.mjs",
+    "process-lock:test": "node tests/process-lock-test.mjs",
+    "service-lifecycle:test": "node tests/service-lifecycle-test.mjs"
   },
   "dependencies": {
     "wrangler": "4.110.0",

package/scripts/github-release.mjs

@@ -0,0 +1,368 @@
+#!/usr/bin/env node
+
+import {
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import { runNetworkCommand } from "./network-retry.mjs";
+import { tagSyncError } from "./release-state.mjs";
+import { fileURLToPath } from "node:url";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+process.chdir(root);
+
+function fail(message) {
+  console.error(`release error: ${message}`);
+  process.exit(1);
+}
+
+function run(command, args, options = {}) {
+  const result = spawnSync(command, args, {
+    cwd: root,
+    encoding: "utf8",
+    stdio: options.capture ? "pipe" : "inherit",
+    env: process.env,
+  });
+
+  if (result.error) {
+    fail(`${command} could not be started: ${result.error.message}`);
+  }
+  if (result.status !== 0 && !options.allowFailure) {
+    const detail = options.capture
+      ? `${result.stdout ?? ""}${result.stderr ?? ""}`.trim()
+      : "";
+    fail(`${command} ${args.join(" ")} failed${detail ? `: ${detail}` : ""}`);
+  }
+  return result;
+}
+
+
+function runNetwork(command, args, options = {}) {
+  const result = runNetworkCommand(command, args, { cwd: root, env: process.env });
+  if (!options.capture) {
+    if (result.stdout) process.stdout.write(result.stdout);
+    if (result.stderr) process.stderr.write(result.stderr);
+  }
+  if (result.error && !options.allowFailure) {
+    fail(`${command} could not be started: ${result.error.message}`);
+  }
+  if (result.status !== 0 && !options.allowFailure) failCommandResult(command, args, result);
+  return result;
+}
+
+function outputNetwork(command, args, options = {}) {
+  const result = runNetwork(command, args, { ...options, capture: true });
+  return (result.stdout ?? "").trim();
+}
+
+function failCommandResult(command, args, result) {
+  const detail = `${result.stdout ?? ""}${result.stderr ?? ""}`.trim();
+  fail(`${command} ${args.join(" ")} failed${detail ? `: ${detail}` : ""}`);
+}
+
+function output(command, args, options = {}) {
+  const result = run(command, args, { ...options, capture: true });
+  return (result.stdout ?? "").trim();
+}
+
+function packageMetadata() {
+  const data = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+  if (typeof data.name !== "string" || typeof data.version !== "string") {
+    fail("package.json must contain string name and version fields");
+  }
+  if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(data.version)) {
+    fail(`unsupported package version: ${data.version}`);
+  }
+  return data;
+}
+
+function changelogBody(version) {
+  const changelog = readFileSync(join(root, "CHANGELOG.md"), "utf8");
+  const heading = new RegExp(`^## ${version.replaceAll(".", "\\.")}(?:\\s+-[^\\n]*)?$`, "m");
+  const match = heading.exec(changelog);
+  if (!match) return null;
+  const start = match.index + match[0].length;
+  const next = changelog.slice(start).search(/^## /m);
+  const body = changelog.slice(start, next < 0 ? undefined : start + next).trim();
+  return body || null;
+}
+
+function ensureClean() {
+  const status = output("git", ["status", "--porcelain"]);
+  if (status) fail(`working tree is not clean:\n${status}`);
+}
+
+function fetchRemote() {
+  runNetwork("git", ["fetch", "origin", "main", "--tags", "--prune"]);
+}
+
+function localTagCommit(tag) {
+  const result = run("git", ["rev-list", "-n", "1", tag], {
+    capture: true,
+    allowFailure: true,
+  });
+  return result.status === 0 ? result.stdout.trim() : null;
+}
+
+function remoteTagCommit(tag) {
+  const text = outputNetwork("git", [
+    "ls-remote",
+    "--tags",
+    "origin",
+    `refs/tags/${tag}`,
+    `refs/tags/${tag}^{}`,
+  ]);
+  if (!text) return null;
+  const rows = text.split("\n").map((line) => line.trim().split(/\s+/));
+  const peeled = rows.find(([, ref]) => ref === `refs/tags/${tag}^{}`);
+  const direct = rows.find(([, ref]) => ref === `refs/tags/${tag}`);
+  return (peeled ?? direct)?.[0] ?? null;
+}
+
+function releaseInfo(tag) {
+  const result = runNetwork(
+    "gh",
+    [
+      "release",
+      "view",
+      tag,
+      "--json",
+      "tagName,name,targetCommitish,isDraft,isPrerelease,assets,url",
+    ],
+    { capture: true, allowFailure: true },
+  );
+  if (result.status !== 0) return null;
+  return JSON.parse(result.stdout);
+}
+
+function assertCoreSync({ requireReleaseAsset }) {
+  const pkg = packageMetadata();
+  const tag = `v${pkg.version}`;
+  const head = output("git", ["rev-parse", "HEAD"]);
+  const originMain = output("git", ["rev-parse", "origin/main"]);
+  if (head !== originMain) {
+    fail(`HEAD ${head} does not match origin/main ${originMain}`);
+  }
+
+  const localCommit = localTagCommit(tag);
+  const localTagError = tagSyncError({ scope: "local", tag, head, commit: localCommit });
+  if (localTagError) fail(localTagError);
+
+  const remoteCommit = remoteTagCommit(tag);
+  const remoteTagError = tagSyncError({ scope: "remote", tag, head, commit: remoteCommit });
+  if (remoteTagError) fail(remoteTagError);
+
+  const release = releaseInfo(tag);
+  if (!release || release.isDraft || release.isPrerelease) {
+    fail(`published GitHub Release ${tag} is missing or not final`);
+  }
+
+  if (requireReleaseAsset) {
+    const expectedAsset = `${pkg.name}-${pkg.version}.tgz`;
+    const names = new Set((release.assets ?? []).map((asset) => asset.name));
+    if (!names.has(expectedAsset)) {
+      fail(`GitHub Release ${tag} is missing ${expectedAsset}`);
+    }
+  }
+
+  console.log(`GitHub source, tag, release, and package asset are in sync: ${tag}`);
+}
+
+function writeNotesFile(directory, version) {
+  const body = changelogBody(version);
+  if (!body) return null;
+  const path = join(directory, `release-${version}.md`);
+  writeFileSync(path, body.endsWith("\n") ? body : `${body}\n`, "utf8");
+  return path;
+}
+
+function packReleaseAsset(directory, pkg) {
+  const result = run(
+    "npm",
+    ["pack", "--silent", "--json", "--pack-destination", directory],
+    { capture: true },
+  );
+  let records;
+  try {
+    records = JSON.parse(result.stdout);
+  } catch {
+    fail("npm pack did not return valid JSON");
+  }
+  const record = normalizePackRecord(records, pkg.name);
+  const filename = record?.filename;
+  if (typeof filename !== "string") fail("npm pack did not report a filename");
+  const path = join(directory, filename);
+  const expected = `${pkg.name.replaceAll("/", "-").replace(/^@/, "")}-${pkg.version}.tgz`;
+  if (filename !== expected) {
+    fail(`unexpected npm package filename ${filename}; expected ${expected}`);
+  }
+  return path;
+}
+
+function normalizePackRecord(value, packageName) {
+  if (Array.isArray(value)) return value[0] ?? null;
+  if (!value || typeof value !== "object") return null;
+  if (value[packageName] && typeof value[packageName] === "object") return value[packageName];
+  return Object.values(value).find((item) => item && typeof item === "object") ?? null;
+}
+
+function ensureRelease(tag, version, assetPath, latest) {
+  const temp = dirname(assetPath);
+  const notes = writeNotesFile(temp, version);
+  const existing = releaseInfo(tag);
+  const title = `machine-bridge-mcp ${tag}`;
+
+  if (!existing) {
+    const args = [
+      "release",
+      "create",
+      tag,
+      assetPath,
+      "--verify-tag",
+      "--title",
+      title,
+      latest ? "--latest" : "--latest=false",
+    ];
+    if (notes) args.push("--notes-file", notes);
+    else args.push("--generate-notes");
+    const created = runNetwork("gh", args, { allowFailure: true });
+    if (created.status !== 0 && !releaseInfo(tag)) failCommandResult("gh", args, created);
+  } else {
+    runNetwork("gh", [
+      "release",
+      "edit",
+      tag,
+      "--title",
+      title,
+      latest ? "--latest" : "--latest=false",
+      ...(notes ? ["--notes-file", notes] : []),
+    ]);
+    runNetwork("gh", ["release", "upload", tag, assetPath, "--clobber"]);
+  }
+}
+
+function publishCurrent() {
+  ensureClean();
+  fetchRemote();
+
+  const branch = output("git", ["branch", "--show-current"]);
+  if (branch !== "main") fail(`release must run from main, not ${branch || "detached HEAD"}`);
+
+  const pkg = packageMetadata();
+  const tag = `v${pkg.version}`;
+  if (!changelogBody(pkg.version)) {
+    fail(`CHANGELOG.md has no section for ${pkg.version}`);
+  }
+
+  run("npm", ["run", "check"]);
+  run("npm", ["run", "version:check"]);
+  ensureClean();
+
+  const head = output("git", ["rev-parse", "HEAD"]);
+  const originMain = output("git", ["rev-parse", "origin/main"]);
+  if (head !== originMain) {
+    const ancestor = run("git", ["merge-base", "--is-ancestor", "origin/main", "HEAD"], {
+      capture: true,
+      allowFailure: true,
+    });
+    if (ancestor.status !== 0) {
+      fail("origin/main is not an ancestor of HEAD; refusing a non-fast-forward release");
+    }
+    runNetwork("git", ["push", "origin", "HEAD:main"]);
+  }
+
+  const existingLocal = localTagCommit(tag);
+  if (existingLocal && existingLocal !== head) {
+    fail(`local ${tag} points to ${existingLocal}, not ${head}`);
+  }
+  if (!existingLocal) {
+    run("git", ["tag", "-a", tag, "-m", `Release ${pkg.version}`]);
+  }
+
+  const existingRemote = remoteTagCommit(tag);
+  if (existingRemote && existingRemote !== head) {
+    fail(`remote ${tag} points to ${existingRemote}, not ${head}`);
+  }
+  if (!existingRemote) {
+    runNetwork("git", ["push", "origin", tag]);
+  }
+
+  const temp = mkdtempSync(join(tmpdir(), "machine-bridge-mcp-release-"));
+  try {
+    const assetPath = packReleaseAsset(temp, pkg);
+    ensureRelease(tag, pkg.version, assetPath, true);
+  } finally {
+    rmSync(temp, { recursive: true, force: true });
+  }
+
+  fetchRemote();
+  assertCoreSync({ requireReleaseAsset: true });
+}
+
+function backfillMissingReleases() {
+  ensureClean();
+  fetchRemote();
+
+  const tags = output("git", ["tag", "--sort=version:refname"])
+    .split("\n")
+    .filter((tag) => /^v\d+\.\d+\.\d+$/.test(tag));
+  const releases = JSON.parse(outputNetwork("gh", [
+    "release",
+    "list",
+    "--limit",
+    "1000",
+    "--json",
+    "tagName",
+  ]));
+  const existing = new Set(releases.map((release) => release.tagName));
+  const missing = tags.filter((tag) => !existing.has(tag));
+
+  if (missing.length === 0) {
+    console.log("No GitHub Releases are missing.");
+    return;
+  }
+
+  const temp = mkdtempSync(join(tmpdir(), "machine-bridge-mcp-backfill-"));
+  try {
+    for (const tag of missing) {
+      if (!remoteTagCommit(tag)) fail(`remote tag ${tag} is missing`);
+      const version = tag.slice(1);
+      const notes = writeNotesFile(temp, version);
+      const args = [
+        "release",
+        "create",
+        tag,
+        "--verify-tag",
+        "--title",
+        `machine-bridge-mcp ${tag}`,
+        "--latest=false",
+      ];
+      if (notes) args.push("--notes-file", notes);
+      else args.push("--generate-notes");
+      const created = runNetwork("gh", args, { allowFailure: true });
+      if (created.status !== 0 && !releaseInfo(tag)) failCommandResult("gh", args, created);
+    }
+  } finally {
+    rmSync(temp, { recursive: true, force: true });
+  }
+
+  console.log(`Backfilled ${missing.length} GitHub Release(s): ${missing.join(", ")}`);
+}
+
+const mode = process.argv[2] ?? "--check";
+if (mode === "--check") {
+  ensureClean();
+  fetchRemote();
+  assertCoreSync({ requireReleaseAsset: true });
+} else if (mode === "--publish") {
+  publishCurrent();
+} else if (mode === "--backfill") {
+  backfillMissingReleases();
+} else {
+  fail("usage: node scripts/github-release.mjs [--check|--publish|--backfill]");
+}

package/scripts/privacy-check.mjs

@@ -12,16 +12,23 @@ const findings = [];
 for (const relativePath of candidates) {
   if (relativePath === ".privacy-denylist") continue;
   scanDenylistPath(relativePath, denylist, findings);
+  scanSensitivePath(relativePath, findings);
   const fullPath = path.join(root, relativePath);
   let info;
-  try { info = lstatSync(fullPath); } catch { continue; }
+  try { info = lstatSync(fullPath); } catch {
+    findings.push({ path: relativePath, line: 1, rule: "publication file metadata could not be read" });
+    continue;
+  }
   if (info.isSymbolicLink()) {
     findings.push({ path: relativePath, line: 1, rule: "symbolic link in publication surface" });
     continue;
   }
   if (!info.isFile()) continue;
   let buffer;
-  try { buffer = readFileSync(fullPath); } catch { continue; }
+  try { buffer = readFileSync(fullPath); } catch {
+    findings.push({ path: relativePath, line: 1, rule: "publication file content could not be read" });
+    continue;
+  }
   if (buffer.length > 5 * 1024 * 1024) {
     findings.push({ path: relativePath, line: 1, rule: "file exceeds privacy scanner size limit and requires manual review" });
     continue;
@@ -36,6 +43,7 @@ for (const relativePath of candidates) {
     continue;
   }
   if (relativePath !== selfPath) scanBuiltIn(relativePath, text, findings);
+  if (path.basename(relativePath).toLowerCase() === ".npmrc") scanNpmrc(relativePath, text, findings);
   scanDenylist(relativePath, text, denylist, findings);
 }
 
@@ -65,7 +73,9 @@ function collectCandidateFiles(directory) {
       const relative = stack.pop();
       const absolute = path.join(directory, relative);
       let entries;
-      try { entries = readdirSync(absolute, { withFileTypes: true }); } catch { continue; }
+      try { entries = readdirSync(absolute, { withFileTypes: true }); } catch {
+        throw new Error("privacy fallback traversal could not read a repository directory");
+      }
       for (const entry of entries) {
         if (excluded.has(entry.name) || entry.name === ".privacy-denylist") continue;
         const child = relative ? path.join(relative, entry.name) : entry.name;
@@ -92,10 +102,17 @@ function escapeRegExp(value) {
 
 function scanBuiltIn(relativePath, text, out) {
   const rules = [
-    ["private key material", /-----BEGIN\s+(?:OPENSSH|RSA|EC|DSA)\s+PRIVATE\s+KEY-----/g],
+    ["private key material", /-----BEGIN\s+(?:(?:OPENSSH|RSA|EC|DSA)\s+|ENCRYPTED\s+)?PRIVATE\s+KEY-----/g],
     ["AWS access key", /\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/g],
     ["GitHub access token", /\bgh[pousr]_[A-Za-z0-9_]{30,}\b/g],
+    ["GitLab access token", /\bglpat-[A-Za-z0-9_-]{20,}\b/g],
+    ["npm access token", /\bnpm_[A-Za-z0-9]{30,}\b/g],
+    ["Slack access token", /\bxox[aboprs]-[A-Za-z0-9-]{10,}\b/g],
+    ["Google API key", /\bAIza[A-Za-z0-9_-]{30,}\b/g],
+    ["live payment API key", /\b(?:sk|rk|pk)_live_[A-Za-z0-9]{16,}\b/g],
     ["API secret token", /\bsk-(?:proj-)?[A-Za-z0-9_-]{20,}\b/g],
+    ["JWT-like bearer token", /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/g],
+    ["URL with embedded credentials", /https?:\/\/[^\s/@:"'<>]+:[^\s/@"'<>]+@[^\s/"'<>]+/gi],
     ["absolute macOS/Linux home path", /(?:^|[\s"'=(:,])\/(?:Users|home)\/([^/\s"'<>]+)\//gm],
     ["absolute Windows home path", /(?:^|[\s"'=(:,])\b[A-Za-z]:\\Users\\([^\\\s"'<>]+)\\/gm],
   ];
@@ -105,6 +122,11 @@ function scanBuiltIn(relativePath, text, out) {
       out.push({ path: relativePath, line: lineNumber(text, match.index || 0), rule });
     }
   }
+  const emailLike = /\b[A-Z0-9._%+-]+@([A-Z0-9.-]+\.[A-Z]{2,})\b/gi;
+  for (const match of text.matchAll(emailLike)) {
+    if (isReservedExampleHost(match[1]) || String(match[1]).toLowerCase().endsWith(".noreply.github.com")) continue;
+    out.push({ path: relativePath, line: lineNumber(text, match.index || 0), rule: "non-example email address" });
+  }
   const sshLike = /\b[A-Za-z_][A-Za-z0-9._-]*@([A-Za-z0-9.-]+)\b/g;
   for (const match of text.matchAll(sshLike)) {
     if (isReservedExampleHost(match[1]) || !hasNearbySshContext(text, match.index || 0)) continue;
@@ -112,6 +134,40 @@ function scanBuiltIn(relativePath, text, out) {
   }
 }
 
+
+function scanSensitivePath(relativePath, out) {
+  const normalized = String(relativePath).split(path.sep).join("/");
+  const base = path.posix.basename(normalized).toLowerCase();
+  const sensitive = base === ".dev.vars"
+    || /^\.env(?:\.|$)/.test(base)
+    || /\.(?:pem|p12|pfx|sqlite|sqlite3|db|log)$/i.test(base)
+    || /^(?:id_rsa|id_dsa|id_ecdsa|id_ed25519)(?:\.|$)/i.test(base)
+    || /^(?:credentials?|secrets?|cookies?|sessions?|tokens?)(?:\.|$)/i.test(base);
+  if (sensitive) out.push({ path: relativePath, line: 1, rule: "credential- or private-data-shaped publication filename" });
+}
+
+function scanNpmrc(relativePath, text, out) {
+  const forbiddenKey = /(?:^|:)(?:_auth|_authtoken|_password|username|email|certfile|keyfile|cafile)$/i;
+  const lines = text.split(/\r?\n/);
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index].trim();
+    if (!line || line.startsWith("#") || line.startsWith(";")) continue;
+    const separator = line.indexOf("=");
+    if (separator < 1) {
+      out.push({ path: relativePath, line: index + 1, rule: "unparseable tracked .npmrc line requires manual review" });
+      continue;
+    }
+    const key = line.slice(0, separator).trim().toLowerCase();
+    const value = line.slice(separator + 1).trim();
+    if (forbiddenKey.test(key) || /(?:^|[:/])(?:_auth|_authtoken|_password|username|email|certfile|keyfile|cafile)$/i.test(key)) {
+      out.push({ path: relativePath, line: index + 1, rule: "tracked .npmrc contains authentication or identity configuration" });
+    }
+    if (/\$\{[^}]+\}/.test(value) || /https?:\/\/[^/@\s]+:[^/@\s]+@/i.test(value)) {
+      out.push({ path: relativePath, line: index + 1, rule: "tracked .npmrc contains environment interpolation or embedded credentials" });
+    }
+  }
+}
+
 function scanDenylistPath(relativePath, entries, out) {
   const lower = relativePath.toLocaleLowerCase("en-US");
   for (const entry of entries) {
@@ -133,7 +189,9 @@ function scanDenylist(relativePath, text, entries, out) {
 function loadDenylist(file) {
   if (!existsSync(file)) return [];
   let text;
-  try { text = readFileSync(file, "utf8"); } catch { return []; }
+  try { text = readFileSync(file, "utf8"); } catch {
+    throw new Error("local privacy denylist exists but could not be read");
+  }
   return [...new Set(text.split(/\r?\n/)
     .map((line) => line.trim())
     .filter((line) => line && !line.startsWith("#") && line.length >= 3)
@@ -163,6 +221,9 @@ function isReservedExampleHost(host) {
     || value === "127.0.0.1"
     || value === "::1"
     || value === "example"
+    || value === "example.com"
+    || value === "example.net"
+    || value === "example.org"
     || value.endsWith(".example")
     || value.endsWith(".example.com")
     || value.endsWith(".example.net")

package/scripts/release-state.mjs

@@ -0,0 +1,10 @@
+export function tagSyncError({ scope = "local", tag, head, commit }) {
+  const label = scope === "remote" ? "remote tag" : "local tag";
+  if (!commit) {
+    return `${label} ${tag} is missing; run npm run release:publish before npm publish`;
+  }
+  if (commit !== head) {
+    return `${label} ${tag} points to ${commit}, not HEAD ${head}`;
+  }
+  return "";
+}