mcp-pacemaker 1.3.1 → 2.0.2

package/CHANGELOG.md

@@ -7,47 +7,103 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+Target release: **2.0.2**. This candidate has not yet been published.
+
 ### Fixed
 
-- Require a complete, bounded owner stage-list observation before recording no
-  pending stages; keep owner authentication, ledger review and approval separate.
-- Require a stable, safe `total_count` on every GitHub jobs/artifacts page and
-  reject count drift or overshoot before admitting incomplete publication evidence.
-- Require the original stage job's numeric attempt `1` when verifying captured
-  stage evidence; the requested API attempt alone does not establish it.
-- Check each patch's actual runtime layout during npm publication. Legacy 1.3.1
-  does not require 2.0-only editor/file modules, while shared execution and the
-  current line's error module remain required.
-- Accept GitHub's exact unexpanded consumer-matrix job name during source-secret
-  collection validation, while still requiring skipped status and no executed steps.
-- Compare collected report and native-receipt completion against the precision
-  of GitHub's step timestamp without admitting execution in the next second.
-- Preserve exact positive source-CI attempts and accept bounded canonical npm repair tags.
-- Let the 1.3.1 publishing finalizer use approved immutable published 2.0.1 bytes
-  for T32 comparison without a hosted seed, fabricated preparation evidence or
-  stage authority. Candidate consumer, compatibility and publication gates remain required.
-- Resolve native directory watcher paths before watching logs and test control files,
+- Replace the old GitHub-install quick start in the npm package documentation with
+  npm-first installation, exact-version commands, prerequisites and setup boundaries.
+- Preserve npm package-type permissions in isolated consumer checks instead of silently
+  reverting directory, file, Git, or remote dependency restrictions to npm defaults.
+- Resolve native directory watcher paths in publication and compatibility test helpers,
   avoiding Windows short-path watcher crashes without changing the selected files.
+- Restore the legacy publisher's skipped-matrix job and whole-second timestamp handling
+  in reusable secret-collection admission, preserving source and execution checks.
+
+### Changed
+
+- Make the manual npm publisher reusable for explicitly selected stable 1.x/2.x
+  versions, with immutable published comparison peers and no active bootstrap actions.
+- Keep the existing GitHub source-CI, collection/review, preparation, OIDC staging,
+  verification and separately approved owner-publication route for the selected release.
 
 ### Security
 
-- Prepare 1.3.1 with a `smol-toml` minimum and locked version of 1.8.0. Bounded malformed-TOML
-  regressions cover the EOF-comment hang fixed by CVE-2026-85730 without changing legacy
-  pooling, audit-policy, or immediate-save behavior.
+- Record a temporary **2.0.2-only producer risk acceptance** for `smol-toml 1.8.0`
+  in the CLI runtime and `braces 3.0.3`, `postcss-selector-parser 6.1.4` and
+  `source-map-js 1.2.1` in UI build tooling. The October 6 review keeps the
+  original **2026-10-12T00:00:00Z** expiry and binds both unchanged producer
+  locks and the exact native reports. Raw audit/OSV findings remain visible.
+  Dependency upgrades stay deferred from this documentation release.
+  This is not a patch or a clean advisory result; fresh-consumer findings are
+  not exempted. Remediation and exception removal are required
+  before expiry or the next release. See the
+  [exact advisories, exposure, mitigations and follow-up](docs/npm-publishing.md#temporary-202-producer-risk-acceptance).
+
+## [2.0.1]
 
 ### Changed
 
-- Resolve the explicit `legacy` npm channel for same-major, exact-version update guidance.
-  Channel rollback and adoption of an existing backend are not automatic upgrades.
-- Limit legacy maintenance to the newest 1.3.x patch through March 31, 2027; document durable
-  service replacement and platform prerequisites.
+- Prepare 2.0.1 for a separate npm publication, with exact-version guidance from the current
+  major's maintained channel. Channel rollback and backend adoption are not automatic upgrades.
+- Document durable service replacement, explicit legacy maintenance, platform prerequisites,
+  and the difference between npm provenance and Windows executable signing.
 
 ### Added
 
 - Source-bound, manual npm preparation/staging tooling, bundled third-party notices, and
   fresh-consumer package checks.
-- Exact legacy-patch/current-release compatibility gates and an explicit two-patch mode,
-  while retaining the immutable 1.3.0/2.0.0 historical pair. Add maintenance-branch and Node 24 CI.
+- Explicit patch compatibility pairs alongside the unchanged 1.3.0/2.0.0 historical pair;
+  maintenance-branch CI and Node 24 coverage.
+
+## [2.0.0] - 2026-09-12
+
+### Breaking
+
+- Version 2.0 changes the pooling save contract from immediate application to queued batches.
+  API clients must send `x-mcp-pooling-batch: 1` and distinguish HTTP 202 acceptance from
+  activation. Older clients are rejected without staging a change.
+- The `prewarm` CLI returns after staging, not after activation. Scripts must observe the batch
+  result before relying on the new settings. Undo restores the whole batch, not one server.
+- Update the CLI and reload open dashboard pages when upgrading the bridge from 1.3.0.
+  Before downgrading, use 2.0 to resolve any pending or interrupted configuration transaction.
+
+### Changed
+
+- Pooling changes stage a complete configuration copy and reload five seconds after the last
+  accepted change. The UI and CLI distinguish Pending, Applying and completed activation;
+  Reload now flushes a batch, and Cancel/Undo explicitly applies to the whole batch.
+- Batch-capable clients identify the asynchronous save protocol. Older clients are rejected
+  before staging instead of reporting an accepted change as already enabled.
+- Windows configuration saves use directory-inherited auditing without requiring audit-read
+  privilege. A non-blocking notice explains that custom per-file audit rules may not carry
+  forward; ordinary access and supported integrity protections remain required.
+- Windows saves retain an existing owner that matches the caller user or token default owner,
+  preserving supported legacy writes after downgrade. Other owners still use checked transfer,
+  and source write access remains required.
+
+### Added
+
+- Permanent real-version compatibility gates for **1.3.0 and 2.0.0 only**, using pinned
+  published 1.3.0 code and an actual packed 2.0.0 candidate. CI covers CLI/API pairs on
+  Windows/Linux/macOS with Node 20/22 and built dashboard pairs in the Linux Chromium job:
+  immediate legacy saves/Undo, fresh-nonce protocol refusal, actual old-tab restart/refresh,
+  queued save/Cancel/Undo, settled upgrade/downgrade configuration bytes, and same-authority
+  legacy write/Undo capability after downgrade (or the unchanged known Windows audit refusal).
+
+### Fixed
+
+- Preserve recovery checkpoints after uncertain post-placement failures without replaying
+  writes or accepting corrupt journals.
+- Avoid dispatching process-tree termination for children already known to have exited,
+  including failed session resumes.
+
+### Security
+
+- Raise the `smol-toml` minimum and locked version from 1.7.0 to 1.8.0 to address
+  [CVE-2026-85730](https://github.com/squirrelchat/smol-toml/security/advisories/GHSA-7w5x-hrqm-74c2).
+  Malformed TOML ending with a comment in an unclosed array or inline table now produces a
+  parse error instead of hanging the CLI while reading Codex configuration.
 
 ## [1.3.0] - 2026-09-08
 
@@ -419,6 +475,8 @@ one is a trap for anyone building something similar.
 - Do not report a teardown the bridge initiated as a crash. `taskkill /F` exits non-zero, so
   every recycle, idle reap and session close was recorded as a failure, burying real ones.
 
+[2.0.0]: https://github.com/girishkvs/mcp-pacemaker/releases/tag/v2.0.0
+[1.3.0]: https://github.com/girishkvs/mcp-pacemaker/releases/tag/v1.3.0
 [1.2.0]: https://github.com/girishkvs/mcp-pacemaker/releases/tag/v1.2.0
 [1.1.0]: https://github.com/girishkvs/mcp-pacemaker/releases/tag/v1.1.0
 [1.0.0]: https://github.com/girishkvs/mcp-pacemaker/releases/tag/v1.0.0

package/CONTRIBUTING.md

@@ -47,9 +47,12 @@ owned scratch roots and native watcher inputs at their boundaries; keep rejectin
 links, replaced directories, and files outside the approved inventory. A Windows-only pass
 does not establish Linux or macOS correctness; the hosted platform matrix remains required.
 
-The complete Windows suite needs audit-read rights for successful configuration-write cases.
-Security-specific fixtures modify only their own temporary files. Automatic writes deliberately
-fail closed when audit policy is unreadable; the suite also exercises that restricted path.
+Windows configuration-write coverage must exercise the normal interactive startup token,
+not only a test process inheriting an elevated runner. Validate both the actual token context
+and successful staging/activation. Security-oracle fixtures may use already-authorized test
+authority to establish and inspect their own files; production saves must not depend on it.
+Directory-inherited auditing is the default. Test ordinary access restrictions, integrity,
+custom-audit behavior, contender files and crash recovery separately.
 
 Windows automatic edits use the packaged .NET Framework 4.6.2 helper. Changes to its source
 must rebuild the executable and metadata with
@@ -60,6 +63,11 @@ platform; Windows also exercises the real executable. Those checks do not replac
 byte-for-byte rebuild, and a rolling CI image may not contain the recorded compiler.
 No compiler or PowerShell host runs in the production config-write path.
 
+Batch tests must cover the full five-second trailing debounce, merging complete snapshots,
+Reload now, requests during a flip, stale active revisions, whole-batch Cancel/Undo and late
+commit outcomes. Use controlled clocks for scheduling boundaries and real file/HTTP cases for
+integration. A skipped second move is not proof of recovery after actual process termination.
+
 **A regression test must be shown to fail without its fix.** Revert the fix, watch the test
 fail, restore it, watch it pass. Several bugs in this repo were originally "covered" by tests
 that passed against the broken code — a test that cannot fail is worse than no test, because
@@ -69,70 +77,138 @@ sleeping a fixed interval.
 
 ## Real-version compatibility gates
 
-These gates run actual legacy/current CLI, API and built dashboard code, not mocked backend
-responses. Scope is explicitly **1.3.0, 1.3.1, 2.0.0 and 2.0.1**. The maintained branches use
-the same harness, with exact version assertions and separate historical evidence.
-
-| Preparation | Selected legacy / current pair |
-|---|---|
-| Default in this 1.3.1 checkout | Packed 1.3.1 / immutable 2.0.0 |
-| Default in the 2.0.1 checkout | Immutable 1.3.0 / packed 2.0.1 |
-| `npm run compat:prepare:baseline` | Immutable 1.3.0 / immutable 2.0.0 |
-| `npm run compat:prepare -- --peer-root <opposite-patch-checkout>` | Packed 1.3.1 / packed 2.0.1 |
+These are separate, mandatory CI gates, not substitutes for `npm test`. The root CI job runs
+CLI/API pairs on Windows, Linux and macOS with Node 20, 22 and 24. The Linux/Node 22 UI
+job runs one Chromium browser matrix after building the dashboard.
 
 ```bash
+npm ci
 npm run compat:prepare
 npm run test:compat
 npm run compat:clean
 
+# Browser gate: build before packing the candidate.
+npm --prefix ui ci
 npm --prefix ui run build
-# Install the existing Playwright Chromium browser from the ui directory for CI.
-# A local run can instead set MCP_COMPAT_BROWSER_CHANNEL=chrome.
+cd ui
+npx --no-install playwright install --with-deps chromium
+cd ..
 npm run compat:prepare
 npm run test:compat:browser
 npm run compat:clean
 ```
 
-Run both gates for the explicit patch pair before publishing the complete dual-major set;
-the default per-branch pairs alone do not establish that result. Run cleanup before selecting
-another pair or performing `npm ci`. CI covers Windows/Linux/macOS with Node 20/22/24 and a
-Linux/Node 22 Chromium lane. Node 20 is legacy runtime compatibility, not a supported secure runtime.
+For an already installed local Chrome, set `MCP_COMPAT_BROWSER_CHANNEL=chrome` in your shell
+instead of installing bundled Chromium. CI uses bundled Chromium, not that override.
+Both standalone test commands **fail** when preparation is missing or candidate bytes have
+changed. Clean and prepare again after changing package files, built assets, or Node major.
+
+Historical compatibility baselines remain explicitly **1.3.0 and 2.0.0**.
+Candidate versions must be canonical stable **1.x legacy / 2.x current** versions.
+The owner selects the actual release and any exact opposite-major patch pair;
+support in the harness alone is not evidence that every patch was tested.
+The same harness runs in both maintained branches:
+
+| Preparation | Selected legacy / current pair |
+|---|---|
+| Default in the selected 2.0.2 checkout | Immutable 1.3.0 / packed 2.0.2 |
+| Default in the 1.3.1 checkout | Packed 1.3.1 / immutable 2.0.0 |
+| `npm run compat:prepare:baseline` | Immutable 1.3.0 / immutable 2.0.0 |
+| `npm run compat:prepare -- --peer-root <opposite-patch-checkout>` | Packed 1.3.1 / packed 2.0.2 |
+
+These selections are not qualification evidence. The selected 1.3.1/2.0.2 pair
+requires fresh exact-byte gates; earlier 1.3.1/2.0.1 results remain historical.
+
+Run both API and browser gates for the explicit patch pair before publishing either complete
+dual-major release set. The two default CI pairs alone do not establish that combined result.
+Run `compat:clean` before selecting another pair.
 
 Publication artifact gates add `--candidate-tarball <absolute.tgz> --candidate-sha256 <digest>`.
-This supplies the checkout's own candidate role without repacking it: here that is the legacy
-1.3.1 role. Complete input hashes and the archive digest must match; historical mode cannot
-substitute a patch. The manifest also records the exact npm CLI version.
+This supplies the checkout's own candidate role without repacking it, including the legacy
+role when invoked from 1.3.1. The archive must match every package input and the supplied digest;
+historical mode cannot substitute it. The manifest also records the exact npm CLI version.
 
-Historical sources are pinned to `2d525f4ced01b978a5aeb83aef69145e96cced05` (1.3.0) and
+Release sources are pinned to `2d525f4ced01b978a5aeb83aef69145e96cced05` (1.3.0) and
 `db4812a1cbfb8546c814a656397b9a48ccf0f32c` (2.0.0). Missing commits are fetched read-only by
-exact SHA into an owned temporary repository. Archives honor canonical Git line endings and
-committed attributes. Local candidates are packed without lifecycle scripts, compared against
-their source files, and restored using their own unchanged producer locks. Caller-resolved
-registry/cache settings are honored without a fallback; locks must retain public URLs.
-
-The manifest records selection mode, exact versions and references, each archive/file hash,
-candidate inputs and Node major. Editing either candidate invalidates preparation. Owned
-temporary HOME/config/ports keep the user's state isolated. Identity-checked cleanup never
-follows links or claims another directory. Failed cleanup remains retryable.
-
-The selected 2.x client must preserve immediate 1.x HTTP 200 saves/Undo. The selected 1.x
-client gets HTTP 409 from 2.x with a fresh nonce, or HTTP 401 after a real restart with a stale
-nonce; refresh must load the selected new assets. The 2.x cases require HTTP 202 pending
-receipts, actual activation, cancellation and whole-batch Undo. Settled downgrade checks
-active bytes, instance changes and unchanged caller authority. Known Windows audit-unavailable
-legacy HTTP 403 must remain unchanged; it is not counted as a successful legacy write.
-Unresolved transactions, arbitrary ACL changes and OS-service installation are separate gates.
+exact SHA into an owned temporary repository, never through a moving tag or into checkout refs.
+Git archive uses canonical Git line endings and the committed attributes. Local candidates
+are packed with lifecycle scripts disabled and compared against their actual source files.
+
+Each selected package uses its own unchanged producer lock via `npm ci --omit=dev --ignore-scripts`.
+This is producer-locked compatibility, not fresh consumer resolution. The manifest records the
+selection mode, exact versions and release references, per-role archive/file hashes, source
+inputs and Node major. Editing either candidate invalidates prepared fixtures. No patch is
+relabeled as the original historical bytes. Git, tar, Node and npm must be available.
+
+For local restores through an approved registry, preparation honors the caller's resolved
+`npm_config_registry` and `npm_config_replace_registry_host` settings (and npm cache).
+For example, in a POSIX shell:
+
+```bash
+npm_config_registry=https://approved-registry.example.test/npm/ \
+npm_config_replace_registry_host=npmjs npm run compat:prepare
+```
+
+Use your approved registry URL, not the example. These settings are forwarded to isolated
+`npm ci` calls without changing npmrc files or recording registry settings in the manifest.
+CI sets no override and uses the public registry. Both committed lockfiles and the fixture
+lockfiles must retain public URLs; preparation verifies that restore leaves fixture locks
+byte-identical. Registry policy or quarantine rejections fail preparation without a fallback.
+
+Fixtures, private baseline code, configuration and fake HOME/state live in owned OS temporary
+directories, never the user's active configuration. Only a manifest pointer is kept under
+ignored `node_modules/.cache`. This manifest is also the prepared fixture's ownership marker:
+it is created before restore, keeps its identity when preparation finishes, and is removed
+only after its temporary tree is gone. A failed manifest unlink remains retryable. Other
+temporary test directories use adjacent ownership markers. Ports are allocated dynamically.
+Cleanup checks directory and marker identities and removes only owned files without following
+links. Bridge/browser failures retain their original error and diagnostic logs in test output;
+cleanup errors do not replace
+the original failure. Run cleanup before another root `npm ci`, which removes the pointer.
+
+| Pair/case | Required result |
+|---|---|
+| Selected 2.x CLI/API and built UI to selected 1.x backend | Legacy HTTP 200 enable and Undo; original config bytes restored |
+| Selected 1.x CLI/API and built UI to selected 2.x backend, fresh nonce | Protocol HTTP 409, no queued write or config change |
+| Already-open selected 1.x tab through an actual bridge restart | Old nonce gets HTTP 401; refresh loads the selected 2.x assets and can stage/cancel |
+| Selected 2.x CLI and UI to selected 2.x backend | Queued save, Cancel, actual application and whole-batch Undo |
+| Settled selected 1.x / 2.x / 1.x configuration | Edits/Undo and both restarts preserve the expected active bytes |
+| Actual selected 1.x writes before and after that roundtrip, unchanged authority | Supported write/Undo must remain supported; known Windows audit-unavailable refusal must remain HTTP 403 with no change |
+
+**Test-only UI asset serving:** the two mixed UI/backend cases serve exact old/new built
+`ui/dist` files through Playwright, substituting only the current nonce in the HTML. All
+API, admin mutation, SSE and MCP requests go to the real backend, without response mocks.
+Nested JS assets are included. The old-tab upgrade case does not substitute assets: it stops
+the actual selected 1.x process and starts the selected 2.x process on the same port before refresh.
+
+Only the executed exact version pairs establish compatibility. Writable downgrade is checked on a fresh
+synthetic config with default ownership and inherited security. The test does not change
+tokens, elevate, or set ACLs. It checks unchanged caller authority and, on Windows, the actual
+selected 1.x helper's full/partial audit visibility. Caller-context hashes are not direct measurements
+of individual bridge tokens. Only the legacy HTTP 403 audit-unavailable
+condition is accepted as unsupported; unexpected errors and any new HTTP 500 fail the gate.
+The Windows 2.x writer retains a source owner matching the caller user or token default
+owner; other owners still use checked transfer, and source write access remains required.
+These gates do not test a downgrade with an unresolved transaction, installer/service
+replacement, arbitrary Windows ACLs or authority changes, or all host integrations; their
+separate tests and operational checks still apply.
 
 ## npm consumer validation
 
-`npm run consumer:check -- --tarball <absolute-file> --sha256 <digest> --version 1.3.1 --name mcp-pacemaker`
-uses an owned disposable project and a separate global prefix. It does not copy the producer
-lock: it records fresh dependency resolution, checks the installed command shim and exercises
-the packaged bridge, CLI and UI assets with synthetic servers/private state.
+`npm run consumer:check -- --tarball <absolute-file> --sha256 <digest> --version <version> --name mcp-pacemaker`
+installs the exact packed candidate into an owned disposable consumer project without a copied
+producer lock, records the resolved graph, checks a separate global-prefix command shim, and
+starts the real packaged bridge against synthetic servers and private state. It checks the
+packaged UI assets and CLI status, then removes only its owned fixtures.
+
+Run it with normal npm install-script policy and again with `--ignore-scripts`. It never uses
+the user's global prefix, host configuration, live bridge, or npm credentials. It honors the
+resolved caller registry/cache and offline setting without a mirror fallback. Registry
+signatures and provenance are separate post-publication checks, not inferred from this smoke test.
 
-Run with normal npm install-script policy and again with `--ignore-scripts`. Caller registry,
-cache and offline settings are honored, but user credentials and real host configuration are
-not used. Registry signatures and provenance remain separate post-publication checks.
+The consumer preserves npm's effective `allow-directory`, `allow-file`, `allow-git`, and
+`allow-remote` values, including environment overrides. It does not replace restrictions
+with defaults or grant permissions when an install is rejected.
 
 ## Changing how a host is wired