machine-bridge-mcp 0.16.2 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 0.17.0 - 2026-07-13
+
+### Project governance and contribution flow
+
+- Define a risk-based project standard covering GitHub Flow, Conventional Commits, architecture boundaries, MCP contract ownership, testing, errors, logging, supply-chain security, documentation, review, and explicit exceptions. Add pull-request and structured issue templates plus area ownership through CODEOWNERS.
+- Add an executable Conventional Commit policy for pull-request and main-branch commit titles. Keep the repository on squash-based GitHub Flow rather than introducing permanent develop/release branches that do not match its single-maintainer, continuously released operating model.
+- Require all repository-host operations to use local `git`, `gh`, and `gh api` through Machine Bridge. Explicitly prohibit hosted GitHub connectors or ChatGPT GitHub plugins so remote mutations, credentials, refs, checks, and recovery remain observable from one local control plane.
+- Make repository automation responsible for closing the source-change lifecycle: after all required checks pass it squash-merges the pull request, verifies `main`, creates and pushes the annotated version tag, and creates or updates the matching GitHub Release. npm publication, Worker deployment, credentials, global installation, and daemon/service replacement remain separately authorized live operations.
+
+### Generated contracts and security automation
+
+- Generate a complete MCP tool reference from the shared tool catalog and reject stale output in the required suite. The tool catalog remains the single source for names, availability, annotations, and JSON input schemas; REST-specific Swagger documentation is not duplicated for the MCP surface.
+- Add pinned, least-privilege GitHub workflows for CodeQL analysis, pull-request dependency review, OpenSSF Scorecard publication, and governance checks. Preserve exact dependency versions, registry signature/attestation verification, SBOM generation, history privacy scanning, and cross-platform package tests.
+
+### Cohesion, reuse, and runtime reliability
+
+- Extract optional project-metadata reads, strict integer normalization, plain-record validation, and uninstall/service state inventory into focused shared modules. Remove duplicate numeric clamping, record classification, and no-follow UTF-8 metadata readers while preserving the distinct strict validation semantics used by browser/application commands and Agent Context instruction files. Plain-record validation now rejects class instances instead of treating every non-array object as protocol/configuration data.
+- Reduce the CLI entrypoint from 1,169 to 1,063 lines by moving profile, Worker, active-job, and process-lock inventory behind a dedicated boundary. Add direct failure-path tests and enforce 91% function/73% branch coverage for the new inventory module; raise the CLI branch floor from 5% to 10%.
+- Canonicalize existing state roots before profile enumeration, fixing macOS `/var` versus `/private/var` alias mismatches that could make service removal or lock inspection report inconsistent profile paths. Retry only the final daemon-lock handoff after a verified service stop, and keep daemon fixture subprocesses out of V8 coverage so process teardown does not create platform-timing failures.
+- Generate Wrangler environment declarations through a cross-platform script that creates ignored `.wrangler/` state before invoking Wrangler, instead of writing under `src/worker`; packaging tests reject generated type declarations. This removes clean-runner state dependence and reduces the dry-run package from about 410 KB/1.8 MB unpacked to about 314 KB/1.22 MB while retaining every Worker runtime module.
+- Replace repeated empty WebSocket send/close catches in the Worker and browser extension with small module-local best-effort helpers whose comments preserve the primary failure semantics. Architecture checks reject unexplained empty catches on those protocol boundaries.
+
+### Tests and documentation
+
+- Extend architecture checks to require generated tool documentation, governance scripts, security workflows, explicit workflow permissions, immutable Action references, and rejection of privileged pull-request triggers or write-all permissions.
+- Document why aggregate 80% coverage is not a sufficient quality target, identify the current CLI orchestration branch-coverage weakness, and retain per-module risk thresholds plus behavior-level cross-platform, concurrency, fault-injection, and protocol tests.
+
 ## 0.16.2 - 2026-07-13
 
 ### Fixed

package/CONTRIBUTING.md

@@ -2,6 +2,20 @@
 
 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.
 
+## Development workflow
+
+Read [docs/PROJECT_STANDARDS.md](docs/PROJECT_STANDARDS.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.
+
+Branch names use a category and purpose such as `feat/browser-downloads`, `fix/relay-timeout`, or `chore/dependency-policy`.
+
+Pull-request titles and final commit subjects use Conventional Commits:
+
+```text
+<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.
+
 ## Required for every release-relevant change
 
 Before the reviewed code is pushed to `main`:

package/README.md

@@ -480,7 +480,7 @@ npm pack --dry-run
 
 `npm run check` covers privacy and release-impact gates, architecture/link invariants, generated Worker types, TypeScript, recursively discovered JavaScript syntax, catalog-to-runtime handler parity, deterministic relay lifecycle and secure-file tests, concurrent lock/atomic-replacement/PID-reuse fixtures, fail-closed service lifecycle tests, descendant process-tree termination, local path/write/state/log/service invariants, Ed25519/RSA generation and key-pair validation, real-machine `full` sandbox acceptance, a clean npm package-manifest/mode/sensitive-artifact check, managed-job integrity/redaction/finally/cancellation/recovery, a live stdio MCP flow, and a live local OAuth/Worker/WebSocket/MCP flow. GitHub Actions runs the suite on Linux, macOS, and Windows with the pinned Node 26/npm 12 baseline; macOS and package-audit jobs also exercise the documented isolated global installation.
 
-The cross-cutting 0.12.0 review, corrected failure modes, and residual OS-level limits are recorded in [docs/AUDIT.md](docs/AUDIT.md). See also [docs/AGENT_CONTEXT.md](docs/AGENT_CONTEXT.md), [docs/LOCAL_AUTOMATION.md](docs/LOCAL_AUTOMATION.md), [docs/MANAGED_JOBS.md](docs/MANAGED_JOBS.md), [docs/TESTING.md](docs/TESTING.md), [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md), [docs/ENGINEERING.md](docs/ENGINEERING.md), and [SECURITY.md](SECURITY.md).
+The cross-cutting 0.12.0 review, corrected failure modes, and residual OS-level limits are recorded in [docs/AUDIT.md](docs/AUDIT.md). See also [docs/AGENT_CONTEXT.md](docs/AGENT_CONTEXT.md), [docs/LOCAL_AUTOMATION.md](docs/LOCAL_AUTOMATION.md), [docs/MANAGED_JOBS.md](docs/MANAGED_JOBS.md), [docs/TESTING.md](docs/TESTING.md), [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md), [docs/ENGINEERING.md](docs/ENGINEERING.md), [docs/PROJECT_STANDARDS.md](docs/PROJECT_STANDARDS.md), the generated [MCP tool reference](docs/TOOL_REFERENCE.md), and [SECURITY.md](SECURITY.md).
 
 ## Uninstall
 

package/browser-extension/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "Machine Bridge Browser",
-  "version": "0.16.2",
+  "version": "0.17.0",
   "description": "Connects the current Chromium browser profile to the local Machine Bridge runtime for user-authorized automation.",
   "permissions": [
     "tabs",
@@ -30,5 +30,5 @@
   "action": {
     "default_title": "Machine Bridge Browser"
   },
-  "version_name": "0.16.2"
+  "version_name": "0.17.0"
 }

package/browser-extension/service-worker.js

@@ -67,12 +67,33 @@ function setConnectionState(state) {
       : state === "unconfigured"
         ? "Machine Bridge Browser: click to open pairing"
         : "Machine Bridge Browser: disconnected; click to open pairing";
-  try { ignoreOptionalPromise(chrome.action.setBadgeText({ text: badge })); } catch {}
-  try { ignoreOptionalPromise(chrome.action.setTitle({ title })); } catch {}
+  ignoreBrowserApiCall(() => chrome.action.setBadgeText({ text: badge }));
+  ignoreBrowserApiCall(() => chrome.action.setTitle({ title }));
 }
 
-function ignoreOptionalPromise(value) {
-  if (value && typeof value.catch === "function") value.catch(() => {});
+function ignoreBrowserApiCall(operation) {
+  try {
+    const value = operation();
+    if (value && typeof value.catch === "function") value.catch(() => {});
+  } catch {
+    // Browser UI decoration is optional and must not disrupt broker connectivity.
+  }
+}
+
+function closeSocketQuietly(ws, code, reason) {
+  try {
+    ws?.close(code, reason);
+  } catch {
+    // The socket may already be closed; reconnect state remains authoritative.
+  }
+}
+
+function sendSocketQuietly(ws, payload) {
+  try {
+    ws.send(payload);
+  } catch {
+    // A response cannot be recovered after the broker socket closes.
+  }
 }
 
 async function pairConfiguration(rawEndpoint, rawToken, { replace, senderUrl }) {
@@ -119,27 +140,29 @@ async function confirmRepairFromTab(tab) {
       }),
     });
     const paired = await pairConfiguration(result?.result?.endpoint, result?.result?.token, { replace: true, senderUrl: tab.url });
-    await chrome.scripting.executeScript({
-      target: { tabId: tab.id },
-      func: (ok) => {
-        const status = document.getElementById("status");
-        if (status) status.textContent = ok ? "Paired. You may close this tab." : "Pairing failed.";
-      },
-      args: [paired.ok === true],
-    });
+    await setPairingPageStatus(
+      tab.id,
+      paired.ok === true ? "Paired. You may close this tab." : "Pairing failed.",
+    );
   } catch {
-    try {
-      await chrome.scripting.executeScript({
-        target: { tabId: tab.id },
-        func: () => {
-          const status = document.getElementById("status");
-          if (status) status.textContent = "Pairing failed. Reload this page and confirm that the expected extension build is loaded.";
-        },
-      });
-    } catch {}
+    ignoreBrowserApiCall(() => setPairingPageStatus(
+      tab.id,
+      "Pairing failed. Reload this page and confirm that the expected extension build is loaded.",
+    ));
   }
 }
 
+function setPairingPageStatus(tabId, text) {
+  return chrome.scripting.executeScript({
+    target: { tabId },
+    func: (value) => {
+      const status = document.getElementById("status");
+      if (status) status.textContent = value;
+    },
+    args: [text],
+  });
+}
+
 ensureReconnectAlarm();
 void connectFromStorage();
 
@@ -162,7 +185,7 @@ function connect(endpoint, token, { reconnect = true } = {}) {
   clearTimeout(reconnectTimer);
   reconnectTimer = null;
   if (socket) {
-    try { socket.close(); } catch {}
+    closeSocketQuietly(socket);
   }
   const ws = new WebSocket(endpoint, [`mbm.${token}`]);
   socket = ws;
@@ -181,12 +204,12 @@ function connect(endpoint, token, { reconnect = true } = {}) {
     };
     ws.onopen = () => {
       if (socket !== ws) {
-        try { ws.close(); } catch {}
+        closeSocketQuietly(ws);
         settle(new Error("browser connection was superseded"));
         return;
       }
       ws.handshakeTimer = setTimeout(() => {
-        try { ws.close(1002, "browser broker handshake timed out"); } catch {}
+        closeSocketQuietly(ws, 1002, "browser broker handshake timed out");
       }, HANDSHAKE_TIMEOUT_MS);
     };
     ws.onmessage = (event) => void handleMessage(ws, event.data, () => settle());
@@ -214,12 +237,12 @@ function scheduleReconnect(endpoint, token) {
 async function handleMessage(ws, raw, onReady = () => {}) {
   let message;
   try { message = JSON.parse(String(raw)); } catch {
-    try { ws.close(1007, "invalid broker JSON"); } catch {}
+    closeSocketQuietly(ws, 1007, "invalid broker JSON");
     return;
   }
   if (message?.type === "hello") {
     if (ws.serverHelloSeen || message.role !== "extension" || message.protocol !== BROWSER_EXTENSION_PROTOCOL) {
-      try { ws.close(1002, "browser broker protocol mismatch"); } catch {}
+      closeSocketQuietly(ws, 1002, "browser broker protocol mismatch");
       return;
     }
     ws.serverHelloSeen = true;
@@ -237,7 +260,7 @@ async function handleMessage(ws, raw, onReady = () => {}) {
   }
   if (message?.type === "hello_ack") {
     if (ws.bridgeReady || !ws.serverHelloSeen || message.role !== "extension" || message.protocol !== BROWSER_EXTENSION_PROTOCOL) {
-      try { ws.close(1002, "invalid browser broker acknowledgement"); } catch {}
+      closeSocketQuietly(ws, 1002, "invalid browser broker acknowledgement");
       return;
     }
     clearTimeout(ws.handshakeTimer);
@@ -252,7 +275,7 @@ async function handleMessage(ws, raw, onReady = () => {}) {
     return;
   }
   if (!ws.bridgeReady) {
-    try { ws.close(1002, "browser broker acknowledgement required"); } catch {}
+    closeSocketQuietly(ws, 1002, "browser broker acknowledgement required");
     return;
   }
   if (message?.type === "cancel" && typeof message.id === "string") {
@@ -291,7 +314,7 @@ function sendResponse(ws, id, ok, result, error = "") {
   if (new TextEncoder().encode(payload).byteLength > MAX_RESULT_BYTES) {
     payload = JSON.stringify({ type: "response", id, ok: false, error: "browser result exceeds maximum size" });
   }
-  try { ws.send(payload); } catch {}
+  sendSocketQuietly(ws, payload);
 }
 
 

package/docs/ENGINEERING.md

@@ -1,6 +1,6 @@
 # Engineering principles and maintenance rules
 
-This document records project-wide decisions that must survive individual fixes, releases, and maintainers. It is normative for repository changes. Machine-specific observations belong in the ignored `.project-local/` directory instead.
+This document records project-wide decisions that must survive individual fixes, releases, and maintainers. It is normative for repository changes together with [PROJECT_STANDARDS.md](PROJECT_STANDARDS.md). Machine-specific observations belong in the ignored `.project-local/` directory instead.
 
 ## Product and security invariants
 
@@ -146,6 +146,8 @@ Cross-platform tests must not depend on shell syntax, case-sensitive Windows pat
 - OPERATIONS contains diagnosis and recovery procedures.
 - TESTING records executable coverage and regression expectations.
 - CHANGELOG records externally relevant changes, including documentation and workflow changes.
+- PROJECT_STANDARDS defines collaboration, contract, testing, supply-chain, review, and exception policy.
+- TOOL_REFERENCE is generated from the shared MCP tool catalog and must never be maintained by hand.
 
 Documentation that claims a guarantee must identify the code or test enforcing it. Do not document an aspirational behavior as implemented.
 

package/docs/PROJECT_STANDARDS.md

@@ -0,0 +1,143 @@
+# Project standards
+
+This document defines the repository-wide engineering and collaboration standard. It complements the product and security invariants in [ENGINEERING.md](ENGINEERING.md). A rule is preferred only when it reduces material risk, makes review easier, or can be enforced consistently; ceremony without a credible failure mode is not a quality control.
+
+## 1. Change flow
+
+The repository uses **GitHub Flow**:
+
+1. create a short-lived branch from current `main`;
+2. make one coherent change, including tests and documentation;
+3. open a pull request and let required checks complete;
+4. resolve review conversations and rebase or update the branch when required;
+5. squash-merge into `main` and delete the branch.
+
+Permanent `develop`, `feature`, and `release` integration branches are not used. A supported maintenance line may use a temporary `release/x.y` branch only when an older published version must receive fixes independently of `main`.
+
+Branch names use a short category and purpose, for example `feat/browser-downloads`, `fix/relay-timeout`, `docs/release-guide`, or `chore/dependency-policy`.
+
+Direct pushes to `main`, force pushes, and branch deletion are blocked by repository protection. An exception requires an incident record and an explicit owner decision.
+
+### Completion ownership
+
+Repository automation owns the complete source-change lifecycle. After required checks pass, it updates the pull-request branch when necessary, squash-merges through local `gh`, verifies the resulting `main` commit, and removes the merged branch. A completed change must not remain indefinitely as an open pull request.
+
+Every release-relevant change advances the package version and is completed by an annotated `v<version>` tag plus a final GitHub Release for the exact successful `main` commit. The coding agent performs that tag and GitHub Release work by default through local `git`, `gh`, and `gh api`; repeated per-task authorization is not required. npm publication, Worker deployment, credential mutation, global installation, and daemon/service replacement remain separate live operations requiring explicit authorization.
+
+### Local GitHub control plane
+
+Repository automation must use local `git`, `gh`, and `gh api` commands executed through Machine Bridge for every GitHub read or mutation. A hosted GitHub connector or ChatGPT GitHub plugin must not be used. Mixing control planes can produce stale refs, unreviewed remote-only commits, ambiguous credentials, and recovery paths that cannot be reproduced from the maintainer's machine. Fetch before mutation and verify the remote result afterward.
+
+## 2. Commits and pull requests
+
+Commit and squash-merge subjects follow Conventional Commits:
+
+```text
+<type>[optional scope][optional !]: <imperative description>
+```
+
+Allowed types are `feat`, `fix`, `docs`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `security`, `release`, and `revert`. `feat` and `fix` carry their normal semantic-version meaning. A breaking change uses `!` and explains migration impact in the body or a `BREAKING CHANGE:` footer.
+
+A good change explains both **what changed and why**. Commits should be logically coherent, but intermediate branch history may be amended because the final pull request is squash-merged. Pull-request titles must satisfy the same format because they become the `main` commit subject.
+
+Pull requests must state:
+
+- the problem and causal mechanism;
+- the chosen solution and important rejected alternatives;
+- user-visible, compatibility, security, privacy, and operational risk;
+- tests and manual verification performed;
+- documentation, release, and rollback consequences.
+
+Keep a pull request small enough to review as one argument. Generated files, mechanical renames, or dependency lockfile changes should be isolated when they obscure substantive behavior. Large changes should be split by a stable contract, not into dependent fragments that cannot be evaluated independently.
+
+## 3. Architecture and dependency direction
+
+The architectural dependency direction in [ENGINEERING.md](ENGINEERING.md) is normative. In addition:
+
+- A module owns one coherent reason to change. Related state-machine transitions may stay together when ordering is part of the safety argument.
+- Domain modules do not import CLI, transport, service, presentation, or deployment adapters.
+- Cross-layer calls go through an explicit interface or orchestration boundary; no adapter reaches through another layer to mutate its internals.
+- Policy, schemas, error codes, protocol metadata, and capability inventories have one authoritative source. Adapters translate them but do not maintain parallel copies.
+- Side effects are isolated behind small interfaces so policy and lifecycle behavior can be tested deterministically.
+- Dependency cycles are prohibited. Hidden global state and import-time operational side effects are avoided.
+- Line-count and complexity thresholds are diagnostic guardrails, not design goals. A threshold may not be satisfied by moving incoherent code into a generic utility module.
+- **High cohesion and low coupling:** one source file or function owns one coherent responsibility and reason to change; collaboration occurs through narrow explicit contracts rather than cross-layer reach-through.
+- **KISS:** prefer the simplest explicit implementation that satisfies current requirements. Do not introduce factories, registries, inheritance, generic frameworks, or configuration layers without an observed variation that needs them.
+- **DRY:** extract repeated business rules, validation, security boundaries, or lifecycle logic into one authoritative implementation. Do not merge merely similar code when its semantics or failure policy differ.
+- Design patterns are used only when they remove an observed variation or coupling. A direct function or small module is preferred over speculative abstractions.
+
+Any deliberate boundary exception must document the dependency, reason, owner, test coverage, and removal condition.
+
+## 4. Public contracts and generated documentation
+
+The MCP tool catalog in `src/shared/tool-catalog.json` is the authoritative public API description. Tool names, availability, annotations, and JSON input schemas are rendered into [TOOL_REFERENCE.md](TOOL_REFERENCE.md); CI rejects stale generated documentation.
+
+Swagger/OpenAPI is required only if the project later exposes a user-facing HTTP REST API. It is not a substitute for MCP tool schemas or end-to-end MCP protocol tests. Hand-maintained copies of generated contracts are prohibited.
+
+A public contract change must address:
+
+- backward and forward compatibility;
+- bounded input and output behavior;
+- authorization and destructive-operation annotations;
+- stable error classification;
+- protocol negotiation or versioning when peers may differ;
+- documentation, tests, changelog, and semantic-version impact.
+
+## 5. Testing and quality gates
+
+Tests follow risk rather than a repository-wide aggregate percentage:
+
+- Every defect fix includes a regression test that fails for the original causal reason.
+- Pure policy and normalization logic is tested directly; adapters receive integration coverage proving that they use the policy correctly.
+- Permission expansion includes denial tests. Bounded resources include over-limit tests. Multi-stage mutations include partial-failure and rollback tests.
+- Concurrency, locking, process trees, persistence, cancellation, retry, and recovery require behavior-level or fault-injection coverage.
+- Protocol changes include producer-consumer contract tests and malformed-input tests.
+- Supported operating systems run the required suite in CI.
+- Critical modules have explicit function and branch baselines. Thresholds may rise after better tests or extraction; lowering one requires an audit note explaining why the old measurement was misleading.
+
+An 80% aggregate coverage target is not a repository requirement: it can hide untested critical branches behind trivial files. New or materially changed pure business modules should normally achieve at least 80% function coverage and meaningful branch coverage, but risk-specific tests remain the acceptance criterion.
+
+Flaky tests are defects. A retry may diagnose environmental instability but may not be used to make a nondeterministic test appear healthy.
+
+## 6. Errors, retries, and logs
+
+- Expected operational failures use typed stable error codes and concise operator messages.
+- Unexpected programming errors remain distinguishable from ordinary unavailability.
+- Request boundaries normalize errors once. Lower layers preserve causes and do not repeatedly translate them.
+- Cleanup catches may be best effort only when the primary failure is retained and cleanup failure is observable where useful.
+- Empty catches and catch-and-continue behavior are prohibited unless a comment explains why the event is intentionally irrelevant.
+- Retries require positive transient classification, bounded attempts, backoff, and idempotency or authoritative state reconciliation.
+- Unhandled process-level exceptions are logged with redaction and cause controlled termination; continuing in an unknown state is not a recovery strategy.
+- Operational logs follow [LOGGING.md](LOGGING.md), remain structured, bounded, actionable, and free of secrets or user content.
+
+## 7. Security and software supply chain
+
+- GitHub workflow permissions default to read-only and are expanded per job only when required.
+- Third-party Actions are pinned to immutable commit SHAs and reviewed when Dependabot updates them.
+- npm dependencies use exact versions and a committed lockfile. Registry signatures and attestations are verified in CI.
+- Dependency review blocks newly introduced vulnerable dependencies. CodeQL performs JavaScript/TypeScript and workflow analysis. OpenSSF Scorecard periodically audits repository supply-chain posture.
+- CI generates and validates a CycloneDX SBOM. Release artifacts must be reproducible from a reviewed commit and tied to successful exact-commit CI evidence.
+- Secret scanning and push protection are enabled. Repository examples use synthetic identities and reserved domains; reachable history is scanned before release.
+- Long-lived publication tokens should be replaced by npm trusted publishing with GitHub OIDC. Until that external registry configuration is completed, release credentials remain an explicit operator responsibility and must never be stored in the repository.
+- Security reports follow [SECURITY.md](../SECURITY.md), not public issue templates.
+
+## 8. Documentation and comments
+
+- README covers supported setup, operation, major capabilities, limitations, and risk.
+- Architecture, security, testing, operations, logging, policy, and release documents each own their designated concern; avoid repeating whole procedures across files.
+- Documentation claims a guarantee only when code, configuration, or a test enforces it.
+- Public behavior changes update the changelog and relevant user documentation in the same pull request.
+- Comments explain non-obvious **why**, invariants, external constraints, and safety ordering. They do not narrate self-explanatory syntax.
+- Temporary workarounds state the triggering condition and removal criterion; use an issue reference when one exists.
+
+## 9. Review and ownership
+
+`CODEOWNERS` identifies responsible areas and requests informed review. It does not prove independent review when author and owner are the same person.
+
+Review examines correctness, causal completeness, security/privacy boundaries, compatibility, failure paths, observability, test evidence, and maintainability. Style preferences do not override a simpler correct design without a documented project rule.
+
+This repository currently has one human maintainer. Requiring one independent approval would deadlock maintenance and therefore is not enabled. The first governance priority when another active maintainer is added is to require one non-author approval for security-sensitive, release, policy, Worker, browser, and execution changes.
+
+## 10. Exceptions and evolution
+
+A standard may be changed when evidence shows that it creates more risk or cost than it removes. The change must update this document, relevant automation, and the changelog together. Silent exceptions and permanently waived failing checks are prohibited.

package/docs/RELEASING.md

@@ -12,6 +12,12 @@ The release invariant is:
 
 `npm publish` runs `release:check` through `prepublishOnly`, so npm publication is blocked until all GitHub state is synchronized.
 
+## Default automation responsibility
+
+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.
+
+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.
+
 ## Prepare a version
 
 1. Set the new version without creating an automatic npm tag. The npm version hook synchronizes the Worker and packaged browser-extension versions:
@@ -65,3 +71,9 @@ The npm lifecycle repeats the full project checks and the GitHub synchronization
 - An npm account that owns the package or has maintainer permission.
 
 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.
+
+## Registry publication hardening
+
+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.
+
+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.

package/docs/TESTING.md

@@ -14,12 +14,14 @@ The suite includes:
 
 - release-impact enforcement requiring a new package version and CHANGELOG section for release-relevant changes;
 - release-state diagnostics distinguishing missing local/remote version tags from tags that point to the wrong commit, plus a release-CI gate that rejects missing, pending, failed, pull-request-only, stale, or wrong-commit runs;
-- generated Cloudflare Worker types and strict TypeScript checking, including unused-local and unused-parameter rejection;
+- generated Cloudflare Worker types under ignored `.wrangler/` state and strict TypeScript checking, including unused-local and unused-parameter rejection; packaging rejects generated declarations;
+- Conventional Commit title validation, shared Markdown escaping regression coverage, and generated MCP tool-reference drift detection;
+- direct tests for shared project-metadata reads, strict integer normalization, plain-record classification, and canonical profile/Worker/job/lock inventory;
 - recursive syntax validation for every JavaScript file under the shipped/runtime/test roots plus the shell wrapper;
 - shared tool-catalog schema, annotation, and profile-inventory checks;
 - default working-agreement injection without user files, bounded automatic project metadata, script-body non-disclosure, user-global opt-out, repository opt-out rejection, global `model_instructions_file` injection in stdio/remote initialization, hierarchical precedence, `.agents/skills` and `.codex/skills` compatibility discovery, live project/skill rescanning and fingerprints, automatic task ranking/loading with English inflection normalization, bounded Chinese/English intent aliases, capability-name weighting, and selected-skill instruction loading; automatic `package.*` commands with English/Chinese workflow-intent matching and Windows command-shim execution, explicit command override/removal, direct argv handling, timeout ceilings, runtime-keyed routing-telemetry privacy, and execution-profile denial;
 - concurrent complete-before-visible lock claims, atomic replacement under active readers, malformed-lock grace, snapshot/token-safe reclamation, absolute-age expiry, PID-reuse detection, and bounded startup-lock waiting;
-- foreground takeover of active and orphaned background daemons, legacy lock identification from canonicalized process arguments, foreground-process protection, actual-PID exit waiting, 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;
+- foreground takeover of active and orphaned background daemons, legacy lock identification from canonicalized process arguments, 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;
 - 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, installed-application discovery caching, and name-based task matching;
 - relay environment-proxy direct/bypass/agent selection, unsupported proxy rejection, fail-fast invalid configuration, and route observability without endpoint or credential disclosure;
@@ -67,7 +69,7 @@ For deterministic release validation, perform an isolated-profile smoke test wit
 
 `npm run coverage:test` runs selected in-process and lightweight entrypoint fixtures under V8 coverage and enforces per-module baselines for policy, typed errors, call registration, execution middleware, lifecycle/observability, logging, Runtime/CLI orchestration, and Worker pending/policy/error modules. The full stdio and Worker OAuth/MCP integrations run separately in the main suite and are not duplicated inside coverage collection. The gate deliberately reports each module rather than one aggregate percentage. JavaScript modules enforce function and branch minima; Node's direct TypeScript stripping does not expose trustworthy branch ranges, so TypeScript modules enforce function coverage plus explicit state-machine tests and the real workerd integration suite.
 
-The current CLI entrypoint remains the weakest covered orchestration surface; its baseline is therefore reported and locked independently, while extracted `cli-options` and `cli-policy` pure modules carry substantially higher thresholds. A refactor may raise a threshold, but must not lower one merely to make CI green without an explicit audit explanation.
+The current CLI entrypoint remains the weakest covered orchestration surface; its baseline is therefore reported and locked independently, while extracted `cli-options`, `cli-policy`, `records`, and `state-inventory` modules carry substantially higher thresholds. The state-inventory extraction raised the CLI branch floor from 5% to 10%; a refactor may raise a threshold, but must not lower one merely to make CI green without an explicit audit explanation.
 
 ## Additional release checks
 
@@ -83,7 +85,7 @@ npm run version:check
 npm run release-impact:check
 ```
 
-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 explicitly disables setup-node's automatic package-manager cache and upgrades npm from the runner temporary directory 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. 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.
+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 explicitly disables setup-node's automatic package-manager cache and upgrades npm from the runner temporary directory 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 publish OpenSSF Scorecard results. 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.
 
 ## Test design rules
 
@@ -104,7 +106,7 @@ Run `npm run privacy:check` before committing and before packaging. Run and revi
 
 ## Package manifest
 
-`npm run package:test` executes a real silent `npm pack --dry-run --json`, requires clean parseable JSON, rejects sensitive local artifacts and credential-like file classes, validates every packaged mode as `0644` or `0755`, and verifies that privacy/engineering guidance, runtime/relay/secure-file/lock/service/browser/app modules, all package-script helpers, the packaged browser extension, contribution discipline, and privacy/release-impact checkers are present. `npm run install:test` requires npm 12, installs the real tarball from a package-free directory into an isolated global prefix with the documented options, verifies the packaged npm engine requirement, rejects blocked-script warnings, confirms optional `fsevents` is absent, and runs the installed CLI. The test runs on Linux, macOS, and Windows CI.
+`npm run package:test` executes a real silent `npm pack --dry-run --json`, requires clean parseable JSON, rejects sensitive local artifacts, credential-like file classes, and generated Worker type declarations, validates every packaged mode as `0644` or `0755`, and verifies that privacy/engineering guidance, runtime/relay/secure-file/lock/service/browser/app modules, all package-script helpers, the packaged browser extension, contribution discipline, and privacy/release-impact checkers are present. `npm run install:test` requires npm 12, installs the real tarball from a package-free directory into an isolated global prefix with the documented options, verifies the packaged npm engine requirement, rejects blocked-script warnings, confirms optional `fsevents` is absent, and runs the installed CLI. The test runs on Linux, macOS, and Windows CI.
 
 The stdio integration test also sends an oversized line, verifies bounded rejection, and confirms that the next valid request is still processed.