machine-bridge-mcp 1.2.6 → 1.2.8

package/docs/RELEASING.md

@@ -2,58 +2,92 @@
 
 The release invariant is:
 
-- `main` points to the release commit, and the exact commit has a completed successful push-triggered `.github/workflows/ci.yml` run.
-- `v<package version>` points to that same commit locally and on GitHub.
-- A final GitHub Release exists for the tag.
-- The GitHub Release contains the npm tarball generated from that commit.
-- `package.json`, `package-lock.json`, the Worker-reported version, and `browser-extension/manifest.json` (`version`/`version_name`) agree.
-- Every release-relevant change since the prior version tag has a higher package version and matching CHANGELOG section.
-- The same reviewed change is present on GitHub and in a new npm version.
+- the repository owner tested the exact npm tarball represented by `release-acceptance/v<version>.json` on the maintainer machine and explicitly recorded a passing result;
+- the current package produces the same SHA-1 and SHA-512 integrity values as that accepted tarball;
+- `main` points to the release commit, and that exact commit has completed successful push-triggered CI, CodeQL, Governance, and OpenSSF Scorecard runs;
+- `v<package version>` points to that same commit locally and on GitHub;
+- a final GitHub Release exists for the tag and contains the accepted npm tarball;
+- `package.json`, `package-lock.json`, the Worker-reported version, and `browser-extension/manifest.json` (`version`/`version_name`) agree;
+- every npm-package change since the prior version tag has a higher package version and matching CHANGELOG section;
+- the same accepted package content is present on GitHub and in a new npm version.
 
-`npm publish` runs `release:check` through `prepublishOnly`, so npm publication is blocked until all GitHub state is synchronized.
+A green automated suite is necessary but is not evidence that the maintainer's ordinary installation path works. The repository therefore separates automated validation from owner acceptance and binds both to the final package bytes.
 
-## Default automation responsibility
+## Change classification
 
-For every reviewed release-relevant change, repository automation completes the source release without requiring the owner to repeat the instruction: it merges the pull request, waits for successful push-triggered CI on the exact `main` commit, creates and pushes the annotated version tag, creates or updates the final GitHub Release, uploads the generated npm tarball, and verifies that all references identify the same commit. These GitHub operations use only local `git`, `gh`, and `gh api` through Machine Bridge.
+A change is **npm-package relevant** when it alters `package.json`, `package-lock.json`, or a path included by the package `files` manifest. Source, runtime scripts, browser extension files, shared contracts, shipped documentation, and package metadata therefore require a new version and local acceptance.
 
-This standing responsibility does not authorize npm publication, Cloudflare Worker deployment, credential changes, global package installation, or local daemon/service replacement. Those operations change a registry or live machine and require explicit authorization.
+A repository-only change under paths such as `.github/` may be merged without a synthetic npm version when the package bytes are unchanged. It still requires review and all applicable GitHub checks. `scripts/release-impact-check.mjs` implements this distinction from the package manifest rather than from a duplicated path list.
 
-## Prepare a version
+## Prepare the candidate locally
 
-1. Set the new version without creating an automatic npm tag. The npm version hook synchronizes the Worker and packaged browser-extension versions:
+1. Set the new version without creating a tag. The npm version hook synchronizes the Worker and browser-extension versions:
 
    ```sh
    npm version <version> --no-git-tag-version
    ```
 
-2. Add the matching dated `CHANGELOG.md` section.
-3. Run `npm run release-impact:check`, `npm run privacy:check`, review `npm run privacy:history`, run `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`, including packaged file modes and every helper referenced by package scripts, then commit and push all release changes to `main`. Wait for the push-triggered Linux/macOS/Windows and package-audit checks to complete successfully.
+2. Add the matching dated `CHANGELOG.md` section and update affected documentation and audit notes.
+3. Run the required dependency, privacy, Worker, and package checks while iterating.
+4. Inspect the complete diff.
+5. Generate the final candidate:
 
-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.
+   ```sh
+   npm run release:candidate
+   ```
+
+`release:candidate` runs the complete repository suite and then writes the exact npm tarball plus a bounded pending manifest under ignored `.release-candidate/`. Do not modify a packaged file after generating the candidate without regenerating and retesting it.
+
+## Repository-owner local acceptance
+
+The repository owner—not the coding agent—must test the exact `.release-candidate/*.tgz` artifact on the maintainer machine through the normal installation and startup path relevant to the change. For a general release, this includes installation from that tarball, zero-argument startup, ordinary connection/readiness, and at least one representative user operation. Changes to browser, application automation, service startup, proxying, credentials, or platform-specific behavior require the corresponding live or platform-specific test described in `docs/TESTING.md` and `docs/OPERATIONS.md`.
+
+After the owner confirms the candidate works, record the decision using the exact phrase printed by `release:candidate`, for example:
+
+```sh
+npm run release:accept -- --confirm "I TESTED machine-bridge-mcp 1.2.8 LOCALLY AND IT WORKS"
+```
+
+This creates `release-acceptance/v<version>.json` containing only package identity, hashes, timestamp, result, and a fixed owner-confirmation marker. It does not store a personal name, machine path, command output, credential, or user content. The acceptance record is intentionally excluded from the npm package, so adding it does not change the tested tarball.
 
-## Publish GitHub source and release
+The command repacks the current tree and refuses to record acceptance if any packaged byte changed after candidate preparation. The assertion is a process gate backed by branch ownership and review, not a cryptographic identity signature; it must never be generated by automation merely because automated tests passed.
 
-From a clean `main` worktree:
+## Push and review
+
+Commit the candidate changes and acceptance record, then push the branch only through:
+
+```sh
+npm run github:push
+```
+
+The command requires a clean non-`main` branch, verifies that the acceptance record is tracked, rebuilds the npm package, compares both hashes, and only then executes a non-force push of the current branch. Direct pushes to `main` remain prohibited. Any packaged-file change after acceptance invalidates the hash and blocks the next push until the owner retests a regenerated candidate.
+
+Open a pull request, satisfy the required checks, and squash-merge. Pull-request CI repeats the acceptance verification. A content-preserving squash changes the Git commit but not the package bytes, so the accepted hash remains valid.
+
+## Publish the GitHub source release
+
+From a clean, fast-forwarded `main` worktree whose `HEAD` exactly equals `origin/main`:
 
 ```sh
 npm run release:publish
 ```
 
-The command validates the project, including repository privacy checks, fast-forwards `origin/main` when needed, then requires the latest push-triggered CI run for that exact commit to be completed successfully before it creates or verifies the annotated version tag. It then pushes the tag, builds the npm tarball, creates or updates the GitHub Release, uploads the tarball, and verifies the resulting state. Read-only GitHub operations, Git pushes, and idempotent release updates use bounded retries only for classified transient network failures; ambiguous Release creation responses are resolved by querying server state before continuing.
+`release:publish` never pushes `main`. It verifies the owner acceptance, runs the complete project and version checks, requires successful exact-commit push runs for CI, CodeQL, Governance, and Scorecard, creates or verifies the annotated version tag, pushes only the version tag when absent, builds the npm tarball, creates or updates the final GitHub Release, uploads the tarball, and verifies the resulting state.
 
-To verify without changing anything:
+To verify an already completed source release without changing anything:
 
 ```sh
 npm run release:check
 ```
 
-To create GitHub Release records for existing remote version tags that lack releases:
+To create GitHub Release records for historical remote tags that lack releases:
 
 ```sh
 npm run release:backfill
 ```
 
+Backfill is historical metadata repair. It does not retroactively claim that releases predating the 1.2.8 acceptance policy had a recorded local acceptance.
+
 ## Publish npm
 
 Only after `release:check` succeeds:
@@ -62,18 +96,16 @@ Only after `release:check` succeeds:
 npm publish --access public
 ```
 
-The npm lifecycle repeats the full project checks and the GitHub synchronization check before upload. Do not leave a code or documentation fix only on GitHub; the corresponding npm version must be published, and the operator should be explicitly reminded until registry publication is confirmed.
-
-## Authentication requirements
+`prepublishOnly` repeats the complete checks and GitHub synchronization check. npm publication remains a deliberate release-operator action and is not authorized by an ordinary source change.
 
-- Git push access to `origin`.
-- An authenticated GitHub CLI session with repository release permission.
-- An npm account that owns the package or has maintainer permission.
+## Authentication and external controls
 
-GitHub Actions is a required publication boundary. The authenticated GitHub CLI must be able to read Actions runs, and a missing, pending, cancelled, skipped, or failed exact-commit push run blocks both `release:publish` and `release:check`. This prevents a machine-specific local pass from publishing a version that fails another supported platform.
+Required local access:
 
-## Registry publication hardening
+- Git push access to `origin` for the accepted branch and version tag;
+- an authenticated GitHub CLI session with pull-request and release permission;
+- an npm account that owns the package or has maintainer permission for the separate registry publication step.
 
-The preferred target is npm trusted publishing from a narrowly scoped GitHub Actions release workflow using OIDC and a protected GitHub environment. This removes the need for a long-lived npm publication token and allows npm to generate provenance automatically. Enabling it requires an explicit package-owner configuration in npm and a reviewed change to the release workflow; repository code alone cannot complete that trust relationship.
+GitHub Actions remains a required cross-platform boundary. Missing, pending, cancelled, skipped, failed, pull-request-only, stale, or wrong-commit runs do not satisfy release publication. Local owner acceptance and successful GitHub checks are complementary evidence; neither substitutes for the other.
 
-Until trusted publishing is configured, publication remains a deliberate local operator step after `release:check`. Do not add an npm token to repository or environment files, workflow YAML, logs, or local project notes. Restrict any fallback token to the shortest practical lifetime and minimum package scope.
+The preferred registry target remains npm trusted publishing from a narrowly scoped GitHub Actions workflow using OIDC and a protected GitHub environment. Enabling it requires package-owner configuration in npm and a reviewed workflow change. Until then, never place an npm token in repository files, workflow YAML, logs, local acceptance records, or project notes.

package/docs/TESTING.md

@@ -12,6 +12,8 @@ The repository requires Node.js 26 and npm 12. `.node-version`, `.nvmrc`, `packa
 
 The suite includes:
 
+- package-impact classification derived from the npm package manifest, allowing repository-only GitHub workflow maintenance without weakening version requirements for shipped content;
+- repository-owner local acceptance hashing, including exact tarball SHA-1/SHA-512 matching, acceptance-record exclusion from the package, and invalidation after any packaged-byte change;
 - 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, plus a release-CI gate that rejects missing, pending, failed, pull-request-only, stale, or wrong-commit runs;
 - generated Cloudflare Worker types under ignored `.wrangler/` state and strict TypeScript checking, including unused-local and unused-parameter rejection; packaging rejects generated declarations;
@@ -24,7 +26,7 @@ The suite includes:
 - foreground takeover of active and orphaned background daemons with current service-lock metadata, foreground-process protection, bounded final lock-handoff retry, actual-PID exit waiting, POSIX non-escalating timeout behavior, Windows verified-daemon stop semantics, daemon lock mode/version/process-start metadata, launchd service-target semantics, and silent idempotent duplicate service starts; daemon fixture subprocesses intentionally do not inherit V8 coverage because their purpose is ownership timing rather than code measurement;
 - 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; Windows coverage reproduces an inline `/TR` command above 262 characters, proves the short launcher action remains bounded, verifies least-privilege logon registration, restart/log routing, language-independent `Ready`/`Running` observation, and state-observed stop/removal despite localized nonzero command output;
 - private service-environment capture/load coverage for exact allowlisting, value bounds and control-character rejection, non-proxy secret exclusion, runtime-value precedence, Windows case-insensitive replacement, explicit empty-value clearing, and preservation across a later environment-free startup;
-- machine-level browser-broker ownership/client proxying, authenticated extension origin/subprotocol, non-cacheable local pairing, pairing-token non-disclosure, resource-backed upload routing, broker result redaction, pre-registered runtime-handshake listeners, bounded socket/HTTP waits, frozen-wall-clock browser deadline coverage, installed-application discovery caching, and name-based task matching;
+- machine-level browser-broker ownership/client proxying, authenticated extension origin/subprotocol, non-cacheable local pairing, pairing-token non-disclosure, resource-backed upload routing, broker result redaction, pre-registered runtime-handshake listeners, bounded socket/HTTP waits, direct loopback health despite hostile environment-proxy settings, stop-during-start generation invalidation, frozen-wall-clock browser deadline coverage, installed-application discovery caching, and name-based task matching;
 - Worker health direct/proxy routing through a real local HTTP CONNECT proxy, `NO_PROXY` bypass, exact `workers.dev` origin/name validation, redirect rejection, body/deadline bounds, error classification, bounded propagation retry, and invalid proxy fail-fast behavior without endpoint or credential disclosure;
 - Worker deployment ambiguity/idempotency: a successful Wrangler result followed by health timeout persists the fingerprint, a second start performs no upload, an actual process restart and disk-state reload still performs no upload, definitive stale-version evidence redeploys under the same name, accidental name changes are rejected, forced replacements clear current endpoint state, and prior names remain in uninstall inventory;
 - relay environment-proxy direct/bypass/agent selection, unsupported proxy rejection, fail-fast invalid configuration, and route observability without endpoint or credential disclosure;
@@ -38,13 +40,13 @@ The suite includes:
 - author-email privacy in `git_log`;
 - isolated command HOME/temp/cache behavior;
 - one-shot timeout, descendant process-group/tree termination including descendants that ignore graceful shutdown after the direct child has already exited, cancellation, and process-session interaction;
-- layered fixed runtime diagnostics for filesystem, direct process, shell, managed-job storage, and resource availability;
+- layered fixed runtime diagnostics for filesystem, direct process, shell, managed-job storage, and resource availability; machine-readable execution guardrails that must keep CPU, memory, and network isolation marked unenforced unless an actual OS boundary is added;
 - 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, sustained transient Windows sharing contention beyond the old retry budget, bounded exponential delay selection, and repeated Windows full-sandbox runs;
 - 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, descendant-tree escalation, token/snapshot-safe transition locks, runner process identity, plan scrubbing, PID-reuse-safe dead-runner recovery, and rejection of numeric-only runner records;
+- 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, spawn-without-PID rejection, asynchronous runner-error observability, plan scrubbing, PID-reuse-safe dead-runner recovery, and rejection of numeric-only runner records;
 - 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, strict current-schema validation, corrupt-JSON isolation, and policy-origin persistence;
 - no filename-based sensitive-file denial under unrestricted policy;
@@ -97,9 +99,10 @@ npm sbom --sbom-format cyclonedx
 npm pack --dry-run
 npm run version:check
 npm run release-impact:check
+npm run release:acceptance:verify
 ```
 
-GitHub Actions executes the main suite on Linux, macOS, and Windows using the pinned Node 26/npm 12 baseline. Because Node 26 currently bundles npm 11, CI downloads the exact npm 12.0.1 tarball from the canonical registry, rejects redirects, verifies its recorded SHA-512 SRI, and exposes that verified CLI through `GITHUB_PATH` before any project-local npm command can trigger strict `devEngines`. Checkout fetches version tags so the release-impact gate can compare the branch with the latest release. A separate package-audit job scans reachable Git history, audits both the complete dependency graph and the production-only graph, verifies registry signatures and attestations, validates a CycloneDX SBOM written under the runner temporary directory, exercises the documented isolated global installation, then performs a dry-run package build. Separate pinned workflows validate governance titles, review dependency changes, run CodeQL over JavaScript/TypeScript and GitHub Actions, and run OpenSSF Scorecard. The SARIF gate fails closed when rule metadata is absent, CodeQL permits only one exact, expiring non-shell process-boundary result, and Scorecard permits only exact reviewed governance/time-dependent findings; new dependency-pinning, fuzzing, or other supply-chain results fail before upload. Scorecard's signed analysis job contains only pinned `uses` steps, while a dependent gate job downloads the SARIF, enforces the accepted inventory, and uploads it to code scanning. Security property tests use a `.js` `fast-check` suite with deterministic seeds because the pinned Scorecard scanner recognizes JavaScript property testing only in `*.js`/`*.jsx`. The installed zero-argument startup smoke test also verifies that Windows creates and remembers `%USERPROFILE%\MachineBridge` while other platforms retain the package-free current directory. The macOS matrix job also runs the installation smoke test because Wrangler's optional `fsevents` resolution is platform-specific. Third-party Actions are pinned to immutable 40-character commit SHAs; architecture tests reject movable tags, and Dependabot monitors both action and dependency updates. Source release creation additionally requires successful push-triggered CI, CodeQL, Governance, and Scorecard runs for the exact `main` commit.
+GitHub Actions executes the main suite on Linux, macOS, and Windows using the pinned Node 26/npm 12 baseline. Because Node 26 currently bundles npm 11, CI downloads the exact npm 12.0.1 tarball from the canonical registry, rejects redirects, verifies its recorded SHA-512 SRI, and exposes that verified CLI through `GITHUB_PATH` before any project-local npm command can trigger strict `devEngines`. Checkout fetches version tags so the release-impact gate can compare the branch with the latest release. A separate package-audit job scans reachable Git history, audits both the complete dependency graph and the production-only graph, verifies registry signatures and attestations, validates a CycloneDX SBOM written under the runner temporary directory, exercises the documented isolated global installation, then performs a dry-run package build. Separate pinned workflows validate governance titles, review dependency changes, run CodeQL over JavaScript/TypeScript and GitHub Actions, and run OpenSSF Scorecard. The SARIF gate fails closed when rule metadata is absent, CodeQL permits only one exact, expiring non-shell process-boundary result, and Scorecard permits only exact reviewed governance/time-dependent findings; new dependency-pinning, fuzzing, or other supply-chain results fail before upload. Scorecard's signed analysis job contains only pinned `uses` steps, while a dependent gate job downloads the SARIF, enforces the accepted inventory, and uploads it to code scanning. Security property tests use a `.js` `fast-check` suite with deterministic seeds because the pinned Scorecard scanner recognizes JavaScript property testing only in `*.js`/`*.jsx`. The installed zero-argument startup smoke test also verifies that Windows creates and remembers `%USERPROFILE%\MachineBridge` while other platforms retain the package-free current directory. The macOS matrix job also runs the installation smoke test because Wrangler's optional `fsevents` resolution is platform-specific. Third-party Actions are pinned to immutable 40-character commit SHAs; architecture tests reject movable tags, and Dependabot groups GitHub Action updates into one atomic PR so coupled suites such as CodeQL cannot drift across versions. Pull-request CI also rebuilds the package and verifies the tracked repository-owner acceptance record before running install/package audit stages. Source release creation additionally requires successful push-triggered CI, CodeQL, Governance, and Scorecard runs for the exact `main` commit.
 
 ## Test design rules
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "machine-bridge-mcp",
-  "version": "1.2.6",
+  "version": "1.2.8",
   "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 privacy:check && npm run privacy:test && npm run release-impact:check && npm run release-impact:test && npm run release:acceptance: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",
     "worker:dry-run": "wrangler deploy --dry-run",
     "worker:integration-test": "node tests/worker-integration-test.mjs",
     "release:check": "node scripts/github-release.mjs --check",
@@ -117,12 +117,17 @@
     "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"
   },
   "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 +166,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/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 repository-owner local 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(`Repository-owner local 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,136 @@
+#!/usr/bin/env node
+
+import {
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+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("Test this exact tarball on the maintainer machine using the documented normal startup path.");
+  console.log("After the repository owner confirms it works, record that confirmation with:");
+  console.log(`npm run release:accept -- --confirm \"${phrase}\"`);
+  console.log("Do not push this release-relevant branch before that command succeeds and its acceptance record is committed.");
+}
+
+function recordAcceptance() {
+  const pkg = readPackage();
+  const supplied = argumentValue("--confirm");
+  const expected = confirmationPhrase(pkg.name, pkg.version);
+  if (supplied !== expected) {
+    throw new Error(`owner 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(),
+  };
+  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(`Local owner 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 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 TESTED ${name} ${version} LOCALLY AND IT WORKS`;
+}
+
+function fail(message) {
+  console.error(`local release acceptance failed: ${message}`);
+  process.exit(1);
+}