machine-bridge-mcp 1.2.7 → 1.2.9

package/docs/THREAT_MODEL.md

@@ -0,0 +1,142 @@
+# Threat model
+
+This document defines the security claims Machine Bridge is designed to make and the claims it explicitly does not make. It complements [SECURITY.md](../SECURITY.md) and the implementation detail in [ARCHITECTURE.md](ARCHITECTURE.md).
+
+## Scope
+
+Machine Bridge combines a remote OAuth relay, a high-authority local runtime, optional local stdio transport, persistent managed jobs, and a browser extension. The primary security objective is to ensure that only explicitly authorized, policy-permitted operations cross those boundaries, with bounded inputs, fail-closed state transitions, and minimal sensitive observability.
+
+The local runtime executes as the current OS user. Policy profiles restrict Machine Bridge behavior; they do not replace kernel, account, VM, container, browser-profile, or endpoint-security isolation.
+
+## Assets
+
+The main protected assets are:
+
+- workspace and local-user-accessible files;
+- process execution authority and inherited environment values;
+- daemon secret, account administration secret, account password verifiers, OAuth authorization codes, access tokens, and refresh tokens;
+- Worker and Durable Object routing state;
+- owner-only profile, lock, resource, service, and managed-job state;
+- registered local resource contents and paths;
+- browser pairing token, browser cookies, authenticated sessions, tabs, page content, and file-upload authority;
+- release candidate hashes, observed-verification acceptance records, package contents, and source-release integrity;
+- logs and diagnostics that could reveal paths, credentials, arguments, results, or user content.
+
+## Trust boundaries
+
+### Hosted client to Worker
+
+The hosted client and its prompts, tools, extensions, and retrieved content are not automatically trusted. The Worker must validate OAuth state, PKCE, redirect and resource binding, account role/version, token expiry/rotation, MCP session state, request shape, body bounds, and allowed tool exposure.
+
+### Worker to local daemon
+
+The Worker is a relay and authorization layer, not a source of local authority. The daemon accepts only an authenticated, version-compatible relay session. End-to-end readiness requires a local probe result through the active session. Every remote tool call carries bounded account authority that is rechecked locally.
+
+### MCP host to local stdio process
+
+A local MCP host can invoke every tool allowed by the selected daemon policy. The host, model output, repository instructions, and retrieved content may be malicious or prompt-injected. A permissive policy therefore grants meaningful local-user authority.
+
+### Local runtime to operating system
+
+The runtime relies on the OS account, filesystem permissions, macOS TCC/SIP, Windows ACLs, container/VM boundaries, and endpoint controls. Canonical workspace checks prevent path escape only when unrestricted paths are disabled. They do not protect against a malicious process already running with the same OS-user authority.
+
+### Local runtime to browser extension
+
+The broker is loopback-only and pairing-token protected. The extension origin, protocol version, build version, capabilities, and handshake state are validated. The extension still runs inside a real browser profile and can reach the tabs, sessions, and origins granted by browser permissions.
+
+### Local runtime to persistent state
+
+State paths, locks, plans, resources, and service definitions are security-sensitive. Reads are bounded and symlink-aware; writes use owner-only modes where supported and atomic replacement; locks bind tokens to process identity and start time; destructive removal validates ownership and expected layout.
+
+### Maintainer to release infrastructure
+
+Repository checks reduce accidental or malicious package drift, but source hosting, npm ownership, protected environments, maintainer accounts, and human review remain external trust dependencies. Repository automation cannot manufacture independent review or claim live candidate success without observing the owner-started candidate. It may record acceptance after that observed verification.
+
+## Attacker models
+
+Machine Bridge considers the following attackers and failure sources:
+
+1. **Malicious or compromised hosted MCP client** attempting unauthorized tools, token replay, OAuth redirect abuse, request smuggling, duplicate IDs, cancellation races, or excessive resource use.
+2. **Malicious local MCP host or model output** attempting to use allowed tools for destructive actions, credential discovery, shell injection, or persistence.
+3. **Malicious repository content** including instructions, package scripts, Git configuration, paths, symlinks, generated metadata, or files designed to influence an agent or execution boundary.
+4. **Malicious webpage or browser content** attempting prompt injection, deceptive selectors, sensitive-field disclosure, unsafe navigation, replay after ambiguous input dispatch, or extension-protocol abuse.
+5. **Local same-user process** attempting to race locks, replace files, impersonate stale processes, read local state, or interfere with loopback services.
+6. **Network attacker or misconfigured proxy** attempting interception, redirect manipulation, credential disclosure, stale deployment evidence, or ambiguous timeout outcomes.
+7. **Compromised dependency or build input** attempting package substitution, mutable workflow execution, install-script abuse, release drift, or sensitive artifact inclusion.
+8. **Operational failure** such as abrupt termination, PID reuse, clock rollback, partial writes, disk/permission errors, service-manager races, stale browser builds, or daemon replacement during active calls.
+
+## Security objectives
+
+The implementation aims to preserve these invariants:
+
+- deny unknown, malformed, stale, duplicated, unauthorized, or over-limit requests;
+- intersect remote account authority with the daemon capability ceiling in both Worker and local runtime;
+- keep transport authentication separate from tool authorization and OS authority;
+- use direct argv execution without shell interpretation unless the explicit shell tool is authorized;
+- canonicalize confined paths and reject symlink-based write escape;
+- bound request bodies, messages, files, output, logs, state, retained results, and concurrency;
+- ensure cancellation, timeout, disconnect, replacement, and shutdown have explicit process ownership and cleanup semantics;
+- prevent a candidate daemon or extension from displacing a healthy incumbent before compatibility/readiness validation;
+- avoid exposing secrets, arguments, results, resource contents, account credentials, or raw local paths in default logs and public metadata;
+- make multi-stage state and file mutations atomic or recoverable without silent partial success;
+- bind managed-job plans and release acceptance to cryptographic content hashes;
+- fail closed when state, ownership, permissions, process identity, or destructive cleanup cannot be verified;
+- keep supply-chain actions pinned, minimally permissioned, reviewed, and separately gated.
+
+## Non-goals
+
+Machine Bridge does **not** claim to provide:
+
+- kernel-enforced sandboxing, CPU/memory quotas, syscall filtering, or network isolation;
+- hard multi-tenant isolation between mutually untrusted users sharing one daemon and OS account;
+- protection from root, an administrator, or a fully compromised same-user account;
+- complete prevention of prompt injection or malicious instructions when an authorized tool can perform the requested action;
+- semantic detection of every secret, transformed credential, private document, or dangerous command;
+- proof that the browser extension is loaded in a safe or isolated profile;
+- rollback of a browser or external-system action after an ambiguous dispatch failure;
+- guaranteed cleanup after power loss, kernel failure, filesystem corruption, or an uncooperative external platform;
+- independent human code review while the project has only one active maintainer;
+- npm trusted publishing until the package owner configures external OIDC trust and a protected publication environment.
+
+## Residual risks
+
+### Canonical `full` profile
+
+`full` intentionally exposes the complete catalog, unrestricted local-user paths, shell execution, parent environment, and absolute path output. A malicious authorized client can use that authority destructively. The mitigation is a narrower profile or a separate low-privilege OS boundary, not additional warning text.
+
+### Application and browser automation
+
+UI state can change between inspection and action. Pages can present deceptive content, and an authenticated browser profile may contain high-value sessions. Trusted input and replay controls reduce specific failure modes but do not make arbitrary web content trustworthy.
+
+### Package scripts and registered commands
+
+Automatic command discovery does not inject script bodies into prompts, but invoking a package script still executes repository-controlled code. The active policy and human approval remain decisive.
+
+### Same-user interference
+
+Owner-only permissions and process-identity locks reduce accidental and cross-account interference. They cannot reliably defend against a determined process running as the same OS user with equivalent filesystem and process rights.
+
+### Availability and resource exhaustion
+
+Concurrency, message, output, and timeout limits bound many application-level resources. The daemon does not enforce OS CPU, memory, disk, or network quotas, so an authorized process can still consume host resources.
+
+### External governance and publication
+
+Code cannot create a second independent reviewer, npm OIDC trust relationship, protected environment, or OpenSSF Best Practices registration. Those controls remain explicit external work rather than simulated repository compliance.
+
+## Validation map
+
+The main regression suites cover:
+
+- OAuth, account, policy, MCP session, daemon readiness, and relay replacement;
+- path confinement, atomic writes, state locks, service lifecycle, managed-job recovery, and destructive cleanup;
+- direct process boundaries, shell separation, process-tree termination, timeout, cancellation, and disconnect;
+- browser pairing, version/capability handshake, owner/client broker routing, sensitive-field handling, trusted input, and CSP navigation;
+- privacy redaction, package contents, release impact, interactive candidate acceptance, dependency integrity, CodeQL, and Scorecard findings;
+- malformed, over-limit, concurrent, replayed, stale, and fault-injected inputs.
+
+See [TESTING.md](TESTING.md) for the complete test inventory and [AUDIT.md](AUDIT.md) for reviewed failures and residual limitations.
+
+## Reporting
+
+Report suspected vulnerabilities through the private process in [SECURITY.md](../SECURITY.md). Do not include real credentials, private user data, browser session material, or sensitive local paths in public issues or test fixtures.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "machine-bridge-mcp",
-  "version": "1.2.7",
+  "version": "1.2.9",
   "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",
@@ -47,7 +47,7 @@
     "worker:types": "node scripts/generate-worker-types.mjs",
     "typecheck": "npm run worker:types && tsc -p tsconfig.json --noEmit && npm run typecheck:local",
     "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 release-ci:test && npm run network-retry:test && npm run worker-deployment:test && npm run relay:test && npm run secure-file:test && npm run worker-secret-file:test && npm run sarif-security:test && npm run security-properties:test && npm run shell:test && npm run architecture:test && npm run markdown:test && npm run project-metadata:test && npm run numbers:test && npm run records:test && npm run state-inventory:test && npm run commit-message:test && npm run policy:test && npm run account:test && npm run worker-oauth-controller:test && npm run policy-docs:check && npm run tool-docs:check && npm run runtime-infrastructure:test && npm run runtime-boundaries:test && npm run runtime-handlers:test && npm run cli-entrypoint:test && npm run cli-service:test && npm run lifecycle:test && npm run logging-structure:test && npm run coverage:test && npm run worker-runtime-infrastructure:test && npm run lint:test && npm run lint && npm run typecheck && npm run syntax && npm run deadline:test && npm run process-lock:test && npm run service-lifecycle:test && npm run service-environment:test && npm run service-platform:test && npm run catalog:test && npm run agent-context:test && npm run capability-ranking:test && npm run browser-command:test && npm run browser-devtools-input:test && npm run browser-service-worker:test && npm run browser-page-automation: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 install: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 && npm run oauth-browser:test",
+    "check": "npm run check:full",
     "worker:dry-run": "wrangler deploy --dry-run",
     "worker:integration-test": "node tests/worker-integration-test.mjs",
     "release:check": "node scripts/github-release.mjs --check",
@@ -79,6 +79,7 @@
     "release-state:test": "node tests/release-state-test.mjs",
     "release-ci:test": "node tests/release-ci-test.mjs",
     "agent-context:test": "node tests/agent-context-test.mjs",
+    "agent-boundaries:test": "node tests/agent-boundaries-test.mjs",
     "browser-bridge:test": "node tests/browser-bridge-test.mjs",
     "app-automation:test": "node tests/app-automation-test.mjs",
     "process-lock:test": "node tests/process-lock-test.mjs",
@@ -117,12 +118,23 @@
     "typecheck:local": "tsc -p tsconfig.local.json --noEmit",
     "runtime-boundaries:test": "node tests/runtime-boundaries-test.mjs",
     "worker-oauth-controller:test": "node tests/worker-oauth-controller-test.mjs",
-    "cli-service:test": "node tests/cli-service-test.mjs"
+    "cli-service:test": "node tests/cli-service-test.mjs",
+    "release:acceptance:test": "node tests/release-acceptance-test.mjs",
+    "release:candidate": "npm run check && node scripts/local-release-acceptance.mjs --prepare",
+    "release:accept": "node scripts/local-release-acceptance.mjs --record",
+    "release:acceptance:verify": "node scripts/local-release-acceptance.mjs --verify",
+    "github:push": "node scripts/github-push.mjs",
+    "check:fast": "node scripts/run-checks.mjs fast",
+    "check:full": "node scripts/run-checks.mjs full",
+    "check-plan:test": "node tests/check-plan-test.mjs",
+    "check:platform": "node scripts/run-checks.mjs platform",
+    "release": "node scripts/github-release.mjs --publish",
+    "release:candidate:start": "node scripts/start-release-candidate.mjs"
   },
   "dependencies": {
     "https-proxy-agent": "9.1.0",
     "proxy-from-env": "2.1.0",
-    "wrangler": "4.111.0",
+    "wrangler": "4.112.0",
     "ws": "8.21.1"
   },
   "devDependencies": {
@@ -161,8 +173,8 @@
   "allowScripts": {
     "esbuild@0.28.1": true,
     "sharp@0.34.5": true,
-    "workerd@1.20260710.1": true,
-    "fsevents": false
+    "fsevents": false,
+    "workerd@1.20260714.1": true
   },
   "packageManager": "npm@12.0.1",
   "devEngines": {

package/scripts/check-plan.mjs

@@ -0,0 +1,91 @@
+export const FAST_CHECK_TASKS = Object.freeze([
+  "privacy:check",
+  "release-impact:check",
+  "release:acceptance:test",
+  "release-state:test",
+  "release-ci:test",
+  "network-retry:test",
+  "secure-file:test",
+  "worker-secret-file:test",
+  "sarif-security:test",
+  "shell:test",
+  "architecture:test",
+  "markdown:test",
+  "project-metadata:test",
+  "numbers:test",
+  "records:test",
+  "state-inventory:test",
+  "commit-message:test",
+  "policy:test",
+  "account:test",
+  "worker-oauth-controller:test",
+  "policy-docs:check",
+  "tool-docs:check",
+  "runtime-infrastructure:test",
+  "runtime-boundaries:test",
+  "runtime-handlers:test",
+  "cli-entrypoint:test",
+  "cli-service:test",
+  "lifecycle:test",
+  "logging-structure:test",
+  "worker-runtime-infrastructure:test",
+  "lint:test",
+  "lint",
+  "typecheck",
+  "syntax",
+  "deadline:test",
+  "catalog:test",
+  "capability-ranking:test",
+  "agent-boundaries:test",
+  "browser-command:test",
+  "check-plan:test",
+]);
+
+export const PLATFORM_ONLY_CHECK_TASKS = Object.freeze([
+  "privacy:test",
+  "release-impact:test",
+  "worker-deployment:test",
+  "relay:test",
+  "security-properties:test",
+  "process-lock:test",
+  "service-lifecycle:test",
+  "service-environment:test",
+  "service-platform:test",
+  "agent-context:test",
+  "browser-devtools-input:test",
+  "browser-service-worker:test",
+  "browser-page-automation:test",
+  "app-automation:test",
+  "self-test",
+  "atomic-fs:test",
+  "ssh-key:test",
+  "full-access:test",
+  "managed-jobs:test",
+]);
+
+export const FULL_ONLY_CHECK_TASKS = Object.freeze([
+  "coverage:test",
+  "browser-bridge:test",
+  "package:test",
+  "install:test",
+  "stdio:integration-test",
+  "worker:integration-test",
+  "oauth-browser:test",
+]);
+
+export const PLATFORM_CHECK_TASKS = Object.freeze([
+  ...FAST_CHECK_TASKS,
+  ...PLATFORM_ONLY_CHECK_TASKS,
+]);
+
+export const FULL_CHECK_TASKS = Object.freeze([
+  ...PLATFORM_CHECK_TASKS,
+  ...FULL_ONLY_CHECK_TASKS,
+]);
+
+export function checkTasks(mode) {
+  if (mode === "fast") return FAST_CHECK_TASKS;
+  if (mode === "platform") return PLATFORM_CHECK_TASKS;
+  if (mode === "full") return FULL_CHECK_TASKS;
+  throw new Error(`unknown check mode: ${mode}`);
+}

package/scripts/coverage-check.mjs

@@ -24,8 +24,12 @@ const tests = [
   "tests/state-inventory-test.mjs",
   "tests/worker-deployment-test.mjs",
   "tests/agent-context-test.mjs",
+  "tests/agent-boundaries-test.mjs",
   "tests/capability-ranking-test.mjs",
   "tests/browser-bridge-test.mjs",
+  "tests/relay-connection-test.mjs",
+  "tests/managed-jobs-test.mjs",
+  "tests/account-admin-test.mjs",
   "tests/monotonic-deadline-test.mjs",
 ];
 
@@ -54,6 +58,7 @@ try {
     "src/local/process-tracker.mjs": [65, 35],
     "src/local/log.mjs": [60, 40],
     "src/local/runtime.mjs": [75, 55],
+    "src/local/runtime-paths.mjs": [90, 50],
     "src/local/cli.mjs": [48, 21.9],
     "src/local/cli-service.mjs": [90, 65],
     "src/local/cli-options.mjs": [65, 35],
@@ -66,6 +71,9 @@ try {
     "src/local/worker-health.mjs": [85, 60],
     "src/local/worker-deployment.mjs": [80, 55],
     "src/local/agent-contract.mjs": [95, 40],
+    "src/local/agent-context-projection.mjs": [95, 60],
+    "src/local/agent-skill-discovery.mjs": [85, 60],
+    "src/local/agent-text-file.mjs": [90, 60],
     "src/local/capability-ranking.mjs": [95, 70],
     "src/local/browser-extension-protocol.mjs": [95, 35],
     "src/local/browser-operation-service.mjs": [80, 50],
@@ -73,9 +81,23 @@ try {
     "src/local/runtime-diagnostics.mjs": [75, 65],
     "src/local/runtime-capabilities.mjs": [75, 45],
     "src/local/monotonic-deadline.mjs": [100, 100],
+    "src/local/state.mjs": [85, 45],
+    "src/local/relay-connection.mjs": [90, 55],
+    "src/local/managed-jobs.mjs": [85, 50],
+    "src/local/managed-job-projection.mjs": [90, 60],
+    "src/local/managed-job-storage.mjs": [75, 50],
+    "src/local/managed-job-runner.mjs": [80, 50],
+    "src/local/browser-bridge.mjs": [80, 55],
+    "src/local/browser-request-registry.mjs": [95, 35],
+    "src/local/browser-broker-routes.mjs": [85, 55],
+    "src/local/browser-broker-server.mjs": [80, 50],
+    "src/worker/oauth-controller.ts": [85, 65],
+    "src/worker/oauth-authorization-page.ts": [90, 60],
     "src/worker/pending-calls.ts": [90, 35],
     "src/worker/policy.ts": [100, 25],
     "src/worker/errors.ts": [100, 40],
+    "src/worker/mcp-jsonrpc.ts": [95, 55],
+    "src/worker/websocket-protocol.ts": [100, 50],
   };
   const failures = [];
   for (const [file, [minimumFunctions, minimumBlocks]] of Object.entries(thresholds)) {

package/scripts/github-push.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { verifyCurrentReleaseAcceptance } from "./release-acceptance.mjs";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+try {
+  const status = output("git", ["status", "--porcelain"]);
+  if (status) throw new Error(`working tree is not clean:\n${status}`);
+  const branch = output("git", ["branch", "--show-current"]);
+  if (!branch) throw new Error("cannot push from a detached HEAD");
+  if (branch === "main") throw new Error("direct pushes to main are prohibited; push a reviewed branch and merge through a pull request");
+
+  const acceptance = verifyCurrentReleaseAcceptance(root);
+  if (acceptance.required) {
+    const path = `release-acceptance/v${acceptance.metadata.package_version}.json`;
+    run("git", ["ls-files", "--error-unmatch", path], { capture: true });
+    console.log(`Verified interactive local candidate acceptance for ${acceptance.metadata.filename}.`);
+  }
+
+  run("git", ["push", "--set-upstream", "origin", "HEAD"]);
+  console.log(`Pushed accepted branch ${branch} to origin.`);
+} catch (error) {
+  console.error(`GitHub push blocked: ${error?.message || error}`);
+  process.exit(1);
+}
+
+function output(command, args) {
+  return String(run(command, args, { capture: true }).stdout || "").trim();
+}
+
+function run(command, args, options = {}) {
+  const result = spawnSync(command, args, {
+    cwd: root,
+    encoding: "utf8",
+    env: process.env,
+    stdio: options.capture ? "pipe" : "inherit",
+    windowsHide: true,
+  });
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    const detail = options.capture ? String(result.stderr || result.stdout).trim() : "";
+    throw new Error(`${command} ${args.join(" ")} failed${detail ? `: ${detail}` : ""}`);
+  }
+  return result;
+}

package/scripts/github-release.mjs

@@ -12,6 +12,7 @@ import { spawnSync } from "node:child_process";
 import { runNetworkCommand } from "./network-retry.mjs";
 import { requireSuccessfulWorkflowRun } from "./release-ci.mjs";
 import { tagSyncError } from "./release-state.mjs";
+import { verifyCurrentReleaseAcceptance } from "./release-acceptance.mjs";
 import { fileURLToPath } from "node:url";
 
 const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
@@ -178,6 +179,7 @@ function releaseInfo(tag) {
 
 function assertCoreSync({ requireReleaseAsset }) {
   const pkg = packageMetadata();
+  assertLocalAcceptance();
   const tag = `v${pkg.version}`;
   const head = output("git", ["rev-parse", "HEAD"]);
   const originMain = output("git", ["rev-parse", "origin/main"]);
@@ -299,18 +301,12 @@ function publishCurrent() {
   run("npm", ["run", "check"]);
   run("npm", ["run", "version:check"]);
   ensureClean();
+  assertLocalAcceptance();
 
   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"]);
+    fail("HEAD does not match origin/main; local acceptance must be committed, pushed through npm run github:push, reviewed, and merged before release publication");
   }
   assertSuccessfulCi(head);
 
@@ -342,6 +338,17 @@ function publishCurrent() {
   assertCoreSync({ requireReleaseAsset: true });
 }
 
+function assertLocalAcceptance() {
+  try {
+    const result = verifyCurrentReleaseAcceptance(root);
+    if (result.required) {
+      console.log(`Interactive local candidate acceptance matches ${result.metadata.filename} (${result.metadata.shasum}).`);
+    }
+  } catch (error) {
+    fail(String(error?.message || error));
+  }
+}
+
 function backfillMissingReleases() {
   ensureClean();
   fetchRemote();

package/scripts/local-release-acceptance.mjs

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+
+import {
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { spawnSync } from "node:child_process";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  ACCEPTANCE_CONFIRMATION,
+  ACCEPTANCE_SCHEMA_VERSION,
+  acceptancePath,
+  packProject,
+  requiresLocalAcceptance,
+  verifyAcceptanceRecord,
+  verifyCurrentReleaseAcceptance,
+  verifyTarball,
+} from "./release-acceptance.mjs";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const candidateDirectory = join(root, ".release-candidate");
+const candidateManifestPath = join(candidateDirectory, "manifest.json");
+const mode = process.argv[2] || "--verify";
+
+try {
+  if (mode === "--prepare") prepareCandidate();
+  else if (mode === "--record") recordAcceptance();
+  else if (mode === "--verify") verifyAcceptance();
+  else fail("usage: node scripts/local-release-acceptance.mjs [--prepare|--record|--verify]");
+} catch (error) {
+  fail(error?.message || error);
+}
+
+function prepareCandidate() {
+  const pkg = readPackage();
+  if (!requiresLocalAcceptance(pkg.version)) {
+    throw new Error(`local acceptance policy begins at ${pkg.name} 1.2.8; current version is ${pkg.version}`);
+  }
+  rmSync(candidateDirectory, { recursive: true, force: true });
+  mkdirSync(candidateDirectory, { recursive: true });
+  const metadata = packProject(root, candidateDirectory);
+  const manifest = {
+    schema_version: ACCEPTANCE_SCHEMA_VERSION,
+    result: "pending",
+    ...metadata,
+    prepared_at: new Date().toISOString(),
+  };
+  writeFileSync(candidateManifestPath, `${JSON.stringify(manifest, null, 2)}\n`, { mode: 0o600 });
+  const phrase = confirmationPhrase(pkg.name, pkg.version);
+  console.log(`Release candidate created: ${join(candidateDirectory, metadata.filename)}`);
+  console.log("The repository owner must start this exact candidate in a local terminal with:");
+  console.log("npm run release:candidate:start -- --allow-worker-deploy");
+  console.log("Leave the candidate running while the coding agent verifies connection readiness and representative functionality through Machine Bridge.");
+  console.log("After that observed live verification succeeds, the coding agent records acceptance with:");
+  console.log(`npm run release:accept -- --confirm \"${phrase}\"`);
+  console.log("Automated tests alone do not authorize acceptance or the first GitHub push.");
+}
+
+function recordAcceptance() {
+  const pkg = readPackage();
+  const supplied = argumentValue("--confirm");
+  const expected = confirmationPhrase(pkg.name, pkg.version);
+  if (supplied !== expected) {
+    throw new Error(`interactive candidate verification confirmation must exactly match: ${expected}`);
+  }
+  const pending = readJson(candidateManifestPath, "release candidate manifest");
+  if (pending.result !== "pending" || pending.package_name !== pkg.name || pending.package_version !== pkg.version) {
+    throw new Error("release candidate manifest does not match the current package");
+  }
+  verifyTarball(join(candidateDirectory, pending.filename), pending);
+
+  const verificationDirectory = join(candidateDirectory, "verification");
+  rmSync(verificationDirectory, { recursive: true, force: true });
+  mkdirSync(verificationDirectory, { recursive: true });
+  const current = packProject(root, verificationDirectory);
+  for (const key of ["package_name", "package_version", "filename", "shasum", "integrity"]) {
+    if (pending[key] !== current[key]) {
+      throw new Error(`source changed after candidate preparation: ${key} no longer matches`);
+    }
+  }
+
+  const record = {
+    schema_version: ACCEPTANCE_SCHEMA_VERSION,
+    result: "passed",
+    confirmation: ACCEPTANCE_CONFIRMATION,
+    package_name: current.package_name,
+    package_version: current.package_version,
+    filename: current.filename,
+    shasum: current.shasum,
+    integrity: current.integrity,
+    accepted_at: new Date().toISOString(),
+    package_content_sha256: computePortablePackageDigest(),
+  };
+  verifyAcceptanceRecord(record, current);
+  const path = acceptancePath(root, pkg.version);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(record, null, 2)}\n`, "utf8");
+  console.log(`Interactive local candidate acceptance recorded: ${path}`);
+  console.log("Commit this record with the candidate. Any packaged-file change invalidates it.");
+}
+
+function verifyAcceptance() {
+  const result = verifyCurrentReleaseAcceptance(root);
+  if (!result.required) {
+    console.log(`Local release acceptance is not required for ${result.version}.`);
+    return;
+  }
+  console.log(`Local release acceptance matches ${result.metadata.filename} (${result.metadata.shasum}).`);
+}
+
+function computePortablePackageDigest() {
+  const npmCli = process.env.npm_execpath;
+  if (!npmCli) throw new Error("portable package digest requires npm_execpath");
+  const temporary = mkdtempSync(join(tmpdir(), "mbm-release-index-"));
+  const indexPath = join(temporary, "index");
+  const env = { ...process.env, GIT_INDEX_FILE: indexPath };
+  try {
+    runChecked("git", ["read-tree", "HEAD"], { env });
+    runChecked("git", ["add", "--all", "--", "."], { env });
+    const packed = runChecked(process.execPath, [
+      npmCli,
+      "pack",
+      "--ignore-scripts",
+      "--silent",
+      "--dry-run",
+      "--json",
+    ], { env });
+    const verifier = runChecked(process.execPath, [
+      join(root, ".github", "scripts", "verify-release-acceptance.mjs"),
+      "--print-digest",
+    ], { env, input: packed.stdout });
+    const digest = verifier.stdout.trim();
+    if (!/^[0-9a-f]{64}$/.test(digest)) throw new Error("portable package digest output is invalid");
+    return digest;
+  } finally {
+    rmSync(temporary, { recursive: true, force: true });
+  }
+}
+
+function runChecked(file, args, { env = process.env, input } = {}) {
+  const result = spawnSync(file, args, {
+    cwd: root,
+    encoding: "utf8",
+    env,
+    input,
+    windowsHide: true,
+  });
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    throw new Error(`${file} ${args[0] || ""} failed: ${String(result.stderr || result.stdout).trim()}`);
+  }
+  return result;
+}
+
+function readPackage() {
+  return readJson(join(root, "package.json"), "package.json");
+}
+
+function readJson(path, label) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch (error) {
+    throw new Error(`${label} is unavailable or invalid: ${error.message}`);
+  }
+}
+
+function argumentValue(name) {
+  const exact = process.argv.find((value) => value.startsWith(`${name}=`));
+  if (exact) return exact.slice(name.length + 1);
+  const index = process.argv.indexOf(name);
+  return index >= 0 ? process.argv[index + 1] : "";
+}
+
+function confirmationPhrase(name, version) {
+  return `I VERIFIED ${name} ${version} CANDIDATE ON THE OWNER MACHINE AND IT WORKS`;
+}
+
+function fail(message) {
+  console.error(`local release acceptance failed: ${message}`);
+  process.exit(1);
+}