machine-bridge-mcp 0.11.1 → 0.12.1

package/docs/PRIVACY.md

@@ -10,7 +10,7 @@ Run:
 npm run privacy:check
 ```
 
-The check scans tracked and unignored new UTF-8 files and their relative names for private-key material, common live-token forms, user-home paths, non-example `user@host` identifiers, and locally configured private identifiers. Publication-surface symbolic links are rejected rather than followed. Binary, invalid UTF-8, and files above the bounded scanner limit fail closed and require explicit manual review instead of being silently skipped. It reports only the file, line, and rule; it does not print the matched value.
+The check scans tracked and unignored new UTF-8 files and relative names for generic/encrypted/algorithm-specific private-key headers, AWS/GitHub/GitLab/npm/Slack/Google/live-payment/API token forms, JWT-shaped bearer values, embedded-credential URLs, absolute user-home paths, non-example email/`user@host` identifiers, credential-shaped filenames, and locally configured private identifiers. A tracked `.npmrc` is parsed: non-secret repository settings such as `engine-strict=true` are allowed, while authentication/identity keys, environment interpolation, and embedded credentials fail closed. Publication-surface symbolic links are rejected rather than followed. Binary, invalid UTF-8, and files above the bounded scanner limit require explicit manual review instead of being silently skipped. Findings report only file, line, and rule; the matched value is never printed.
 
 Maintain machine-specific names in an ignored owner-only file:
 
@@ -43,9 +43,11 @@ Before committing or publishing:
 - use reserved example domains and neutral aliases;
 - run `npm run privacy:check`, `npm run check`, and `npm pack --dry-run`;
 - treat paths, host aliases, usernames, codenames, real browser URLs/page captures, application names tied to a user, and form data as private metadata even when they are not authentication secrets;
-- keep browser pairing-state files and captured source/screenshots out of fixtures, documentation, support logs, and release assets.
+- keep browser pairing-state files and captured source/screenshots out of fixtures, documentation, support logs, and release assets;
+- review any tracked `.npmrc` as configuration code and never commit authentication, registry identity, environment interpolation, cert/key paths, or credential-bearing URLs;
+- inspect package modes and filenames as well as file contents—an empty `.env`, private-key filename, database, or log is still an inappropriate publication artifact.
 
-The scanner is heuristic. It cannot identify every personal or organizational name, transformed value, image, archive, binary fixture, or data already present in Git history.
+The scanner is heuristic. It cannot identify every personal or organizational name, split/transformed/encrypted value, image, archive, binary fixture, custom credential format, or data already present in Git history. Passing it is a gate, not proof that a publication contains no private data.
 
 ## Incident response
 

package/docs/RELEASING.md

@@ -22,7 +22,7 @@ The release invariant is:
 
 2. Add the matching dated `CHANGELOG.md` section.
 3. Run `npm run release-impact:check`, `npm run privacy:check`, `npm run check`, both dependency audits, `npm audit signatures`, and generate a CycloneDX `npm sbom`.
-4. Inspect the complete diff and `npm pack --dry-run`, then commit and push all release changes to `main`.
+4. Inspect the complete diff and `npm pack --dry-run`, including packaged file modes and every helper referenced by package scripts, then commit and push all release changes to `main`.
 
 A privacy/security documentation correction is not “docs only” for release purposes. It requires a replacement npm version and, when appropriate, deprecation or unpublication of the affected version.
 

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;
@@ -47,6 +49,18 @@ The suite includes:
 - live stdio MCP initialization with session instructions, capability resolution, discovery, calls, rich content, sessions, cancellation, managed-job acceptance, and a detached job/finally phase that survives stdio shutdown;
 - live local Worker OAuth registration, consent, PKCE, token replay rejection, throttling, CORS, protocol negotiation, daemon-backed session bootstrap, dynamic tool advertisement, rich content, daemon replacement, cancellation, malformed daemon JSON/non-object rejection, duplicate hello rejection, and unknown-message closure.
 
+## Opt-in live desktop and browser validation
+
+The normal suite uses deterministic mocks for macOS Accessibility and an authenticated in-process extension peer for browser routing. Before a release that changes local UI automation, run the macOS live smoke test on a machine where the invoking Node/terminal process has Accessibility permission:
+
+```sh
+npm run app-automation:live-test
+```
+
+It opens Calculator, activates it through the fixed JXA helper, verifies structured JSON output, inspects main-window Accessibility controls with menu recursion disabled, clicks the `One` control, and quits the application. It is intentionally excluded from CI because macOS TCC permission and a graphical login session are host state.
+
+For browser changes, perform an isolated-profile smoke test with the packaged unpacked extension: pair it to a temporary source runtime, navigate a local no-store page, inspect controls, fill multiple fields, click a button, verify the live DOM, and capture a screenshot. A Playwright persistent Chromium context is an acceptable harness because it loads the real MV3 service worker while keeping the user's daily browser profile untouched.
+
 ## Additional release checks
 
 ```sh
@@ -65,6 +79,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 +95,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.1",
   "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,10 @@
     "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",
+    "app-automation:live-test": "node tests/app-automation-test.mjs --live-macos"
   },
   "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]");
+}