machine-bridge-mcp 1.2.7 → 1.2.9

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 1.2.9 - 2026-07-18
+
+- Repair cross-platform release infrastructure found by PR CI: the layered check runner now invokes the pinned npm CLI through Node instead of spawning `npm.cmd`, and `release:accept` computes and locally validates the portable Git-content digest through a temporary index so CI can verify accepted package content across merge commits without mutating the maintainer index.
+- Correct the release handoff: add `npm run release:candidate:start -- --allow-worker-deploy` for an isolated local installation plus explicitly authorized in-place candidate Worker deployment, require owner-started and agent-observed live verification before acceptance, allow the coding agent to record acceptance and complete commit/push/tag/GitHub Release work, and add `npm run release` as the canonical source-release command. npm publication and Worker deployment remain owner-operated.
+
+### Architecture headroom, verification feedback, and threat model
+
+- Split tool registration, relay adaptation, path redaction, Agent-context projection/rendering, bounded skill discovery and text reading, browser request lifecycle, runtime-client broker routing, authenticated loopback server setup, browser HTTP handling, Windows launcher quoting, managed-job transition locks, runner identity, private storage, public projections, Worker OAuth authorization-page rendering, JSON-RPC framing, and WebSocket protocol cleanup out of near-limit orchestration modules. Tighten architecture budgets around the new boundaries so `runtime`, Agent context, browser broker, Windows service, managed jobs, and `BridgeRoom` retain explicit headroom instead of treating their previous line caps as targets.
+- Replace the monolithic package-script chain with audited `check:fast`, `check:platform`, and `check:full` plans while keeping `npm run check` as the complete gate. Each task reports elapsed time; macOS and Windows CI run the cross-platform behavior plan plus installed-package smoke coverage, while Ubuntu runs the full coverage, browser, package, stdio, Worker/OAuth, and real-browser suites.
+- Expand critical-module coverage gates to state persistence, relay lifecycle, managed jobs, runtime path redaction, Agent-context projection, browser broker/request routing, Worker OAuth, JSON-RPC framing, and WebSocket protocol helpers. Add strict checked-JavaScript coverage for the runtime path/redaction, Agent-context projection, skill-discovery, and bounded text-file boundaries. Repair a detached-process self-test race by waiting monotonically for the child PID handoff file, and remove fixed CI-job-count and implementation-location assumptions from source-shape tests.
+- Replace the oversized README with a decision-oriented entry path, add a component overview and explicit threat model, document the Node 26/npm 12 support trade-off, and add a contributor first-30-minutes workflow. Security objectives, attacker classes, non-goals, and external governance gaps are now stated separately from incident and release audit history.
+
+## 1.2.8 - 2026-07-17
+
+### Owner-tested release gate and dependency workflow repair
+
+- Replace the previous automation-only release assumption with an explicit repository-owner local acceptance boundary. `npm run release:candidate` runs the complete suite and creates the exact npm tarball under ignored local state; `npm run release:accept` records the owner decision only when a second pack is byte-identical. The tracked acceptance record contains package identity, SHA-1, SHA-512 integrity, timestamp, and a fixed confirmation marker, while excluding personal identity, machine paths, logs, credentials, and user content.
+- Add `npm run github:push`, which rejects dirty trees, detached HEAD, direct `main` pushes, untracked acceptance records, or package-hash drift before pushing a release-relevant branch. Pull-request CI and `release:publish` independently rebuild and verify the accepted package. `release:publish` no longer pushes `main`; it requires the accepted branch to have been reviewed and merged so local `HEAD` already equals `origin/main`.
+- Distinguish npm-package changes from GitHub-only repository infrastructure. The release-impact gate now derives package relevance from `package.json.files`, so Action-only Dependabot PRs no longer deadlock on an unrelated npm version bump while source, scripts, browser extension, package metadata, and shipped documentation remain versioned.
+- Consolidate the five pending GitHub Action updates atomically: CodeQL `init`, `analyze`, and `upload-sarif` now use the same 4.37.1 commit; `actions/setup-node` advances to 7.0.0; and `actions/upload-artifact` advances to 7.0.1. Dependabot now groups all GitHub Action updates so coupled action families cannot be split into incompatible PRs.
+- Update Wrangler from 4.111.0 to 4.112.0 and advance the exact reviewed `workerd` install-script allowlist to 1.20260714.1. Complete and production dependency audits remain at zero known vulnerabilities.
+- Rewrite the release, contribution, automation, engineering, architecture, testing, and audit contracts around the owner-tested artifact boundary. Add executable regression coverage for package-impact classification, package-hash acceptance, workflow grouping, CI verification, no automatic `main` push, and package-manifest inclusion of every new helper.
+
 ## 1.2.7 - 2026-07-17
 
 ### Process supervision, lifecycle, and isolation audit

package/CONTRIBUTING.md

@@ -1,10 +1,22 @@
 # Contributing and release discipline
 
-This repository treats every Git-tracked or nonignored repository file as release-relevant, including source code, tests, scripts, examples, documentation, CI configuration, ignore rules, and package metadata.
+Read [docs/PROJECT_STANDARDS.md](docs/PROJECT_STANDARDS.md), [docs/ENGINEERING.md](docs/ENGINEERING.md), [GOVERNANCE.md](GOVERNANCE.md), and the relevant domain documentation before changing behavior.
+
+## First 30 minutes
+
+1. Use Node.js 26 and npm 12, then run `npm ci`.
+2. Read [System overview](docs/OVERVIEW.md), [Engineering](docs/ENGINEERING.md), and the domain document for the code being changed.
+3. Run `npm run check:fast` before editing to establish a clean local baseline.
+4. Make one responsibility-focused change and run its nearest behavior test while iterating.
+5. Run `npm run check` before declaring a package-affecting change complete.
+
+Do not begin by raising a module line cap, weakening a coverage threshold, or adding a parallel policy/protocol shape. First identify the responsibility that belongs in a focused module or the shared contract that should own the rule. Source-shape architecture assertions are supplementary; security and lifecycle changes require behavior, denial, race, or fault-injection coverage for the underlying mechanism.
 
 ## Development workflow
 
-Read [docs/PROJECT_STANDARDS.md](docs/PROJECT_STANDARDS.md), [GOVERNANCE.md](GOVERNANCE.md), and the relevant domain documentation before changing behavior. This repository uses GitHub Flow: branch from current `main`, keep the change coherent, open a pull request, satisfy required checks, squash-merge, and delete the branch. Permanent `develop` or generic release integration branches are not used unless an independently maintained release line creates a concrete need. Repository automation performs GitHub operations only through local `git`, `gh`, and `gh api` commands executed by Machine Bridge; hosted GitHub connectors and ChatGPT GitHub plugins are prohibited for this repository.
+The repository uses GitHub Flow: branch from current `main`, keep one coherent change, validate it locally, open a pull request, satisfy required checks, squash-merge, and delete the branch. Permanent `develop` or generic release integration branches are not used unless an independently maintained release line creates a concrete need.
+
+Repository automation performs GitHub operations only through local `git`, `gh`, and `gh api` commands executed by Machine Bridge. Hosted GitHub connectors and ChatGPT GitHub plugins are prohibited for this repository. Direct pushes to `main` and force pushes are prohibited.
 
 Branch names use a category and purpose such as `feat/browser-downloads`, `fix/relay-timeout`, or `chore/dependency-policy`.
 
@@ -14,21 +26,33 @@ Pull-request titles and final commit subjects use Conventional Commits:
 <type>[optional scope][optional !]: <imperative description>
 ```
 
-Accepted types are `feat`, `fix`, `docs`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `security`, `release`, and `revert`. Explain the causal problem, why the solution is correct, compatibility/security/privacy risk, verification, and release impact in the pull request. Bug fixes require a regression test for the original failure mechanism.
+Accepted types are `feat`, `fix`, `docs`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `security`, `release`, and `revert`. Explain the causal problem, why the solution is correct, compatibility/security/privacy risk, verification, and release impact. Bug fixes require a regression test for the original failure mechanism.
+
+## Package impact
+
+An npm version is required when a change affects `package.json`, `package-lock.json`, or any path included by the package `files` manifest. This includes runtime source, executable scripts, browser-extension files, shared contracts, and shipped documentation. `npm run release-impact:check` derives the decision from the package manifest.
 
-## Required for every release-relevant change
+Repository-only infrastructure changes, such as a `.github/` workflow update, do not require a synthetic npm version when package bytes are unchanged. They still require review and all applicable CI, dependency-review, CodeQL, governance, and Scorecard checks.
 
-Before the reviewed code is pushed to `main`:
+## Required before pushing an npm-package change
 
 1. bump `package.json` to a version newer than the latest reachable `v*` tag;
-2. add the matching dated section to `CHANGELOG.md`;
-3. run `npm run check`, `npm audit`, `npm audit --omit=dev`, and `npm run worker:dry-run`;
-4. inspect the complete diff and the npm package manifest;
-5. commit and push the reviewed change to GitHub.
+2. add the matching dated section to `CHANGELOG.md` and update audit/documentation records;
+3. run targeted tests, both dependency audits, `npm run worker:dry-run`, privacy/history review, signature verification, SBOM generation, and package inspection as applicable;
+4. inspect the complete diff;
+5. run `npm run release:candidate`, which executes the complete suite and creates the exact candidate tarball under ignored `.release-candidate/`;
+6. give the repository owner `npm run release:candidate:start -- --allow-worker-deploy`; the owner explicitly authorizes the in-place candidate Worker deployment, starts the exact candidate locally, and leaves it running;
+7. verify the live candidate through Machine Bridge, including Worker version/hash, remote health, relay readiness, exact local version, and representative functionality relevant to the change;
+8. after observed verification succeeds, have the coding agent run the exact `release:accept` command printed by the candidate tool, creating `release-acceptance/v<version>.json`;
+9. commit the acceptance record and push the clean non-`main` branch only with `npm run github:push`.
 
-After all required pull-request checks pass, repository automation completes the source release under [AGENTS.md](AGENTS.md): squash-merge through local `gh`, verify the exact `main` push CI, CodeQL, Governance, and Scorecard runs, create the annotated version tag, and create or update the matching final GitHub Release. The release operator separately publishes the same version to npm and performs any live machine update. Automation must not publish, deprecate, or unpublish npm packages; install the CLI globally; deploy the Worker; rotate credentials; mutate live deployment state; or start/stop/install/remove the daemon or autostart service without explicit user authorization.
+Automated checks do not authorize step 8. The coding agent may record acceptance only after it has observed the owner-started candidate operating successfully. Any packaged-file change after acceptance changes the npm tarball hash and requires a regenerated candidate and another observed live verification.
 
-Supported upgrade and rollback behavior is defined in [docs/UPGRADING.md](docs/UPGRADING.md). Support requests must follow [SUPPORT.md](SUPPORT.md), and repository participation follows [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
+After all required pull-request checks pass, repository automation completes the source release: squash-merge, verify the exact `main` push CI, CodeQL, Governance, and Scorecard runs, and run `npm run release`. The helper requires `HEAD === origin/main`; it does not push `main`. It creates or verifies the annotated version tag and final GitHub Release only after the accepted package hash and exact-commit checks match. `release:publish` remains a compatibility alias.
+
+The release operator separately authorizes npm publication and any live machine update. Automation must not publish, deprecate, or unpublish npm packages; install the CLI globally; deploy the Worker; rotate credentials; mutate live deployment state; or start, stop, install, remove, or replace the daemon or autostart service without explicit user authorization.
+
+Supported upgrade and rollback behavior is defined in [docs/UPGRADING.md](docs/UPGRADING.md). Support requests follow [SUPPORT.md](SUPPORT.md), and repository participation follows [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
 
 After npm publication, the standard machine update is:
 
@@ -36,15 +60,9 @@ After npm publication, the standard machine update is:
 npm install -g --omit=optional --allow-scripts=esbuild,workerd,sharp,fsevents machine-bridge-mcp@latest && machine-mcp
 ```
 
-The npm command updates the global CLI. Normal `machine-mcp` startup checks the Worker deployment hash, expected version, and health, redeploys when necessary, and reconciles the daemon/autostart flow.
-
-`npm run release-impact:check` enforces the version and changelog parts. It fails when release-relevant files changed after the latest version tag but the package version was not advanced.
-
-A privacy or security correction is always release-relevant. Removing a private identifier only from the current branch is insufficient: publish a replacement npm version, update GitHub, and deprecate or unpublish the affected npm version when policy and authentication permit.
-
 ## Privacy
 
-Use only synthetic names, reserved example domains, and generic paths. Maintain private local identifiers in the ignored `.privacy-denylist` and run `npm run privacy:check` before committing.
+Use only synthetic names, reserved example domains, and generic paths. Maintain private local identifiers in the ignored `.privacy-denylist` and run `npm run privacy:check` before committing. Local acceptance records contain hashes and a fixed marker only; do not add machine paths, personal names, logs, credentials, endpoint URLs, or user content.
 
 ## Engineering standards
 
@@ -52,4 +70,4 @@ Read [docs/ENGINEERING.md](docs/ENGINEERING.md) before changing architecture, po
 
 A log change is behavior: test its level, repetition policy, privacy fields, and recovery message. A transport change must distinguish low-level connectivity from authenticated readiness and test timeout/reconnect branches deterministically. Lock, state deletion, service lifecycle, detached process, and credential changes require behavior-level concurrency or fault-injection tests. Review [docs/AUDIT.md](docs/AUDIT.md) before changing those surfaces.
 
-Reusable decisions belong in tracked documentation. Keep only machine-specific observations in the ignored `.project-local/` directory, and never store credentials there.
+Reusable decisions belong in tracked documentation. Keep only machine-specific observations in ignored `.project-local/`, and never store credentials there.