chore(sync): merge upstream main through 8e85a0fd

.coderabbit.yaml

@@ -2,7 +2,7 @@
 #
 # Auto-review is DISABLED repo-wide: the app was enabled at the org level on
 # 2026-08-14 and immediately began reviewing every opened PR. This repo's
-# merge gate is CI ("All required checks pass") plus maintainer review —
+# merge gate is CI ("All required checks pass (v2)") plus maintainer review —
 # CodeRabbit reviews carry no merge weight (protect-main ruleset requires
 # 0 approving reviews), so auto-firing on the full PR firehose adds comment
 # noise without gating value.

.github/CODEOWNERS

@@ -10,6 +10,9 @@
 # same review for the same reason.
 /.github/                       @NousResearch/hermes-agent-core
 /scripts/ci/                    @NousResearch/hermes-agent-core
+# The code-health gate decides whether a PR passes; weakening it is a CI change.
+/scripts/check                  @NousResearch/hermes-agent-core
+/scripts/code_health/           @NousResearch/hermes-agent-core
 
 # eslint configs can define custom ``fix`` functions that run arbitrary code.
 eslint.config.*                 @NousResearch/hermes-agent-core

.github/PULL_REQUEST_TEMPLATE.md

@@ -47,6 +47,7 @@ Fixes #
 - [ ] I searched for [existing PRs](https://github.com/NousResearch/hermes-agent/pulls) to make sure this isn't a duplicate
 - [ ] My PR contains **only** changes related to this fix/feature (no unrelated commits)
 - [ ] I've run `pytest tests/ -q` and all tests pass
+- [ ] `python scripts/check` passes (the blocking lint and code-health checks CI runs)
 - [ ] I've added tests for my changes (required for bug fixes, strongly encouraged for features)
 - [ ] I've tested on my platform: <!-- e.g. Ubuntu 24.04, macOS 15.2, Windows 11 -->
 

.github/workflows/ci.yaml

@@ -23,6 +23,11 @@ on:
         required: false
         type: boolean
         default: false
+      strict_acceptance:
+        description: "Acceptance runs only: known_failure owners whose gaps FAIL this run instead of xfailing ('upd-txn', a comma list, or '1' for every gap). Sets HERMES_E2E_STRICT_ACCEPTANCE for the E2E suites (tests/e2e/core/_pending_fixes.py)."
+        required: false
+        type: string
+        default: ''
   workflow_call:
     inputs:
       release:
@@ -162,7 +167,9 @@ jobs:
   tests:
     name: Python tests
     needs: detect
-    if: needs.detect.outputs.python == 'true'
+    # Its E2E jobs are lanes of their own: a lane the classifier sets must reach
+    # its job whatever `python` says (tests/ci/test_update_ci_routing.py).
+    if: needs.detect.outputs.python == 'true' || needs.detect.outputs.e2e == 'true' || needs.detect.outputs.e2e_upgrade == 'true'
     uses: ./.github/workflows/tests.yml
     with:
       # NousResearch runs the full unit suite on one 32-core runner. Forks
@@ -173,17 +180,19 @@ jobs:
       e2e_mode: full
       e2e: ${{ github.repository != 'NousResearch/hermes-agent' || needs.detect.outputs.e2e == 'true' }}
       e2e_upgrade: ${{ github.repository != 'NousResearch/hermes-agent' || needs.detect.outputs.e2e_upgrade == 'true' }}
+      strict_acceptance: ${{ inputs.strict_acceptance || '' }}
 
   # macOS + Windows lanes. The main `tests` lane above is Linux-only, and
   # the OS-marked tests it collects are skipped there by design (see the
   # `_OS_MARKS` comment in tests/conftest.py) — this is where they run.
-  # Same `python` lane gate: if no Python changed, neither runs.
-  # Only this fork's non-release Windows-native results are advisory.
-  # Shared tests/runners and the upstream/release matrix stay unchanged.
+  # Gated on `python` and on each lane it consumes: desktop_updater is set by
+  # TypeScript-only changes too (the Electron marker / result readers), and with
+  # `python` alone those never reached the Windows hand-off tests below.
+  # This fork's Windows-native advisory callers retain visible results.
   tests-os:
     name: OS-specific tests
     needs: detect
-    if: needs.detect.outputs.python == 'true'
+    if: needs.detect.outputs.python == 'true' || needs.detect.outputs.desktop_updater == 'true' || needs.detect.outputs.e2e == 'true' || needs.detect.outputs.e2e_upgrade == 'true'
     uses: ./.github/workflows/tests-os.yml
     with:
       platform_scope: ${{ needs.detect.outputs.os_tests_scope }}
@@ -193,25 +202,29 @@ jobs:
       desktop_updater: ${{ needs.detect.outputs.desktop_updater == 'true' }}
       e2e: ${{ github.repository != 'NousResearch/hermes-agent' || needs.detect.outputs.e2e == 'true' }}
       e2e_upgrade: ${{ github.repository != 'NousResearch/hermes-agent' || needs.detect.outputs.e2e_upgrade == 'true' }}
+      strict_acceptance: ${{ inputs.strict_acceptance || '' }}
 
   tests-windows-advisory:
     name: Windows-only tests (advisory)
     needs: detect
-    if: needs.detect.outputs.python == 'true' && needs.detect.outputs.advisory_windows == 'true'
+    if: (needs.detect.outputs.python == 'true' || needs.detect.outputs.desktop_updater == 'true' || needs.detect.outputs.e2e == 'true' || needs.detect.outputs.e2e_upgrade == 'true') && needs.detect.outputs.advisory_windows == 'true'
     uses: ./.github/workflows/tests-os.yml
     with:
       platform_scope: windows
       desktop_updater: ${{ needs.detect.outputs.desktop_updater == 'true' }}
       e2e: ${{ github.repository != 'NousResearch/hermes-agent' || needs.detect.outputs.e2e == 'true' }}
       e2e_upgrade: ${{ github.repository != 'NousResearch/hermes-agent' || needs.detect.outputs.e2e_upgrade == 'true' }}
+      strict_acceptance: ${{ inputs.strict_acceptance || '' }}
 
   lint:
     name: Python lints
     needs: detect
-    if: needs.detect.outputs.python == 'true'
+    # frontend too: the code-health ratchet in lint.yml also covers TypeScript.
+    if: needs.detect.outputs.python == 'true' || needs.detect.outputs.frontend == 'true'
     uses: ./.github/workflows/lint.yml
     with:
       event_name: ${{ needs.detect.outputs.event_name }}
+      python: ${{ needs.detect.outputs.python == 'true' }}
 
   js-tests:
     name: JS & TS checks
@@ -278,8 +291,11 @@ jobs:
     needs: detect
     # apps/desktop/e2e/update: a real install.sh install + packaged Desktop,
     # first run, "Update now" hand-off/relaunch, concurrent-update refusal.
-    # Advisory until it has proven stable on CI: its shards run with continue-on-error, so a
-    # red shard shows on the PR but does not fail all-checks-pass.
+    # Required when it runs: a PR that touches the Desktop update path (the
+    # classifier's e2e_desktop_update lane) cannot merge on a red shard. Like
+    # the Linux e2e-upgrade shards and the Windows install + update journey
+    # (tests / tests-os, gated on e2e_upgrade), it is skipped — and the skip
+    # counts as success — when the PR does not touch that path.
     if: ${{ needs.detect.outputs.python_prod == 'true' || needs.detect.outputs.frontend == 'true' || needs.detect.outputs.e2e_desktop_update == 'true' }}
     uses: ./.github/workflows/e2e-desktop-update.yml
 
@@ -396,7 +412,8 @@ jobs:
   # Gate: runs after everything. ``if: always()`` ensures it reports a
   # status even when some deps were skipped.
   #
-  #   Non-release (PR/push): failure fails, skipped counts as success.
+  #   Non-release (PR/push): failure fails. Update/E2E consumers selected
+  #   by detect.outputs must succeed; only unselected consumers may skip.
   #   Release (inputs.release): strict — every required job must be
   #   `success`. A skipped required lane fails the gate; only the PR-only
   #   jobs (history-check, lockfile-diff, supply-chain, review-labels) and
@@ -407,11 +424,19 @@ jobs:
   # named Windows-native advisory callers keep their real results visible
   # without joining these required dependencies. Shared checks stay required.
   #
+  # The check name carries a version. The ruleset requires a check NAME, and a
+  # green check run recorded on a PR head stays valid forever, so a PR whose
+  # last CI predates a new required job still merges on that old green (32
+  # PRs merged without the code-health ratchet that way). When the required
+  # set gains a job every open PR must pass, bump the version here and in the
+  # protect-main ruleset in the same rollout: older greens then no longer
+  # count, and each PR needs one fresh CI run before it can merge.
+  #
   # Outputs ``needs-json`` — a compact ``{job_name: result}`` dict — so
   # the live comment poller can list failed jobs in the PR comment.
   # ─────────────────────────────────────────────────────────────────────
   all-checks-pass:
-    name: All required checks pass
+    name: ${{ github.repository == 'NousResearch/hermes-agent' && 'All required checks pass (v2)' || 'All required checks pass' }}
     needs:
       - detect
       - tests

.github/workflows/docs-site-checks.yml

@@ -25,6 +25,10 @@ jobs:
           command: npm ci
           working-directory: website
 
+      - name: Check Docusaurus Tinypool compatibility
+        run: node scripts/check-tinypool-compat.mjs
+        working-directory: website
+
       - name: Install ascii-guard
         uses: ./.github/actions/retry
         with:
@@ -59,3 +63,8 @@ jobs:
         # Same pattern Docusaurus uses internally (build:fast --locale en).
         run: npm run build:fast
         working-directory: website
+
+      - name: Audit website dependencies
+        # Fails on any high/critical advisory except the allow-listed ones (braces has no
+        # patched release); see scripts/ci/npm_audit_gate.py.
+        run: python3 scripts/ci/npm_audit_gate.py website

.github/workflows/e2e-desktop-update.yml

@@ -28,8 +28,8 @@ jobs:
     name: Desktop install/update E2E (Linux, ${{ matrix.cell }})
     runs-on: ${{ github.repository == 'NousResearch/hermes-agent' && 'ubuntu-latest-32-core' || 'ubuntu-latest' }}
     timeout-minutes: 30
-    # Advisory until stable on CI (see ci.yaml): a red shard does not fail the caller.
-    continue-on-error: true
+    # Required whenever the e2e_desktop_update lane fires (see ci.yaml): it was
+    # advisory until it proved stable, and every main push shard since has passed.
     strategy:
       fail-fast: false
       # One install per shard (every spec restores it; paths are baked in, so

.github/workflows/install-e2e.yml

@@ -130,11 +130,12 @@ on:
       - 'setup-hermes.*'
       - 'hermes_bootstrap.py'
       - 'pm/**'
+      - '!pm/**/*.md'
       - 'hermes_cli/update*'
       - 'hermes_cli/*update*'
       - 'hermes_cli/pm*'
       - 'hermes_cli/*install*'
-      - 'hermes_cli/_early_recovery.py'
+      - 'hermes_cli/_early_recovery*.py'
       - 'hermes_cli/_launchers.py'
       - 'hermes_cli/managed_uv.py'
       - 'hermes_cli/venv_sync.py'

.github/workflows/js-tests.yml

@@ -102,6 +102,8 @@ jobs:
         uses: ./.github/actions/setup-pm
         with:
           toolchain: node
+      - name: Check bounded npm configuration resolution
+        run: node --test scripts/build/node-options.test.mjs
       - name: Install locked native test tooling without lifecycle scripts
         if: matrix.runner != 'windows-2025'
         run: npm ci --workspace apps/desktop --workspace tests-js --include-workspace-root --include=dev --ignore-scripts --no-audit --no-fund

.github/workflows/lint.yml

@@ -1,12 +1,14 @@
 name: Lint (ruff + ty)
 
-# Two things here:
+# Three things here:
 #   1. Advisory diff — ruff + ty diagnostics as a diff vs the target branch.
 #      Writes a Markdown summary to the run page. Exit zero always.
 #   2. Blocking ``ruff check .`` — enforces the explicit rules in
 #      ``[tool.ruff.lint.select]`` (currently PLW1514). Failure blocks merge.
 #      Separate job so the advisory diff still runs even when enforcement
 #      fails.
+#   3. Blocking code-health ratchet (``scripts/code_health``) for Python and TypeScript.
+# ``python scripts/check`` runs every blocking check here locally with the same pinned tools.
 #
 # The fork's CI-sensitive review remains in review-labels.yml; CODEOWNERS
 # additionally routes these files where a code-owner ruleset is configured.
@@ -18,6 +20,10 @@ on:
         description: The event name from the calling orchestrator (pull_request or push).
         type: string
         required: true
+      python:
+        description: Python changed. A frontend-only PR runs just the code-health ratchet (TS).
+        type: boolean
+        default: true
 
 permissions:
   contents: read
@@ -29,7 +35,7 @@ concurrency:
 jobs:
   lint-diff:
     name: ruff + ty diff
-    if: inputs.event_name == 'pull_request'
+    if: inputs.event_name == 'pull_request' && inputs.python
     runs-on: ubuntu-latest
     # Checkout alone has been observed taking >10 min on this fork right after
     # a large upstream-sync merge (materializing/transferring the huge
@@ -53,7 +59,7 @@ jobs:
       - name: Install ruff + ty
         uses: ./.github/actions/retry
         with:
-          command: python -m scripts.ci.python_packages ruff==0.15.10 ty==0.0.82
+          command: python -m scripts.ci.python_packages "$(python -m scripts.code_health --print-pins)" ty==0.0.82
 
       - name: Determine base ref
         id: base
@@ -138,6 +144,7 @@ jobs:
     # ``lint-diff`` job above runs independently so reviewers still get
     # the diff comment even when enforcement fails.
     name: ruff enforcement (blocking)
+    if: inputs.python
     runs-on: ubuntu-latest
     timeout-minutes: 10
     steps:
@@ -152,20 +159,49 @@ jobs:
       - name: Install ruff
         uses: ./.github/actions/retry
         with:
-          command: python -m scripts.ci.python_packages ruff==0.15.10
+          command: python -m scripts.ci.python_packages "$(python -m scripts.code_health --print-pins)"
 
       - name: ruff check .
         # No --exit-zero, no || true. Exit code propagates to the job,
         # which propagates to the required-check gate.
         run: |
           ruff check .
 
+  code-health:
+    # Per-unit ratchet: every function and file keeps its own cap (its value on main when it is
+    # already over target, else the target) and pattern rules compare fingerprints, so a PR
+    # cannot trade one violation for another. The merge commit is compared with its first
+    # parent (current main), so an improvement that lands on main is locked in at once.
+    name: code health ratchet (blocking)
+    if: inputs.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@f548e57e544e1ff5a4c46bf1e1b8685f8e4a348a # v7.0.1
+        with:
+          fetch-depth: 2 # the merge commit and its first parent (the base branch tip)
+
+      - uses: ./.github/actions/setup-pm
+        with:
+          cache-python: true
+          prune-python-cache: true
+
+      - name: Install pinned ruff
+        uses: ./.github/actions/retry
+        with:
+          command: python -m scripts.ci.python_packages "$(python -m scripts.code_health --print-pins)"
+
+      - name: Ratchet the PR against the base branch tip
+        run: python scripts/check --only health --base HEAD^1
+
   windows-footguns:
     # Static guardrails on Windows-unsafe Python primitives — os.kill(pid, 0),
     # os.killpg, os.setsid, signal.SIGKILL without getattr fallback,
     # shebang scripts via subprocess, bare open() without encoding=, etc.
     # See scripts/check-windows-footguns.py for the full rule list.
     name: Windows footguns (blocking)
+    if: inputs.python
     runs-on: ubuntu-latest
     timeout-minutes: 10
     steps:
@@ -198,14 +234,19 @@ jobs:
 
       # The OS lanes import only files carrying the matching marker, so a test that fakes
       # macOS (is_macos -> True, sys.platform -> "darwin") without `platforms("macos")` is green on
-      # Linux over a faked branch and never runs on macOS (#111866, AGENTS.md § Don't fake the host OS).
+      # Linux over a faked branch and never runs on macOS (#111866, tests/AGENTS.md § Don't fake the host OS).
       - name: Forbid unmarked macOS fakes in tests
         run: python scripts/ci/check_os_marker_fakes.py
 
+      # Every AGENTS.md from the git root down to the working directory loads as one
+      # project-context block (30,720 chars on a 128k window); chains are capped at 30k.
+      - name: Keep every AGENTS.md under its truncation cap
+        run: python scripts/ci/check_agents_md_size.py
+
       # Advisory: profile-scope hazard shapes on the lines this PR adds (child env from os.environ,
       # raw os.getenv of a platform credential, HOME-only RPC binding, bare-PID liveness). One
       # process serves many profiles; every pattern leaked the launch profile at least once. Printed
-      # into the log for the reviewer; never fails the job (root AGENTS.md § Code Shape Rules).
+      # into the log for the reviewer; never fails the job (root AGENTS.md § Rules that apply everywhere).
       - name: Profile-scope patterns on added lines (advisory)
         if: github.event_name == 'pull_request'
         continue-on-error: true

.github/workflows/nix.yml

@@ -160,13 +160,16 @@ jobs:
         env:
           RELEASE_VERSION: ${{ inputs.version }}
         run: |
-          package="$(nix build "path:$RUNNER_TEMP/release-source#hermes-agent" --no-link --print-out-paths)"
+          source="path:$RUNNER_TEMP/release-source"
+          package="$(nix build "$source#default" --no-link --print-out-paths)"
           actual="$("$package/bin/hermes" --version)"
           ACTUAL_VERSION="$actual" python3 - <<'PY'
           import os
 
           expected = os.environ["RELEASE_VERSION"]
-          actual = os.environ["ACTUAL_VERSION"].split()[-1].removeprefix("v")
+          # Line one is "Hermes Agent v<version> (...)"; later lines (Python, OpenAI SDK) carry other versions.
+          first = os.environ["ACTUAL_VERSION"].splitlines()[0].split()
+          actual = first[2].removeprefix("v") if first[:2] == ["Hermes", "Agent"] and len(first) > 2 else ""
           if actual != expected:
               raise SystemExit(f"Nix package version mismatch: expected {expected}, got {actual}")
           PY

.github/workflows/plugin-catalog-ci.yml

@@ -53,9 +53,12 @@ jobs:
     steps:
       - uses: actions/checkout@f548e57e544e1ff5a4c46bf1e1b8685f8e4a348a # v7.0.1
         with:
-          # The pull_request checkout is GitHub's merge commit; depth 2 brings its
-          # first parent (the base tip), which is all the diff below needs.
-          fetch-depth: 2
+          # Full commit graph + tags, blobs on demand: the diff below needs the
+          # merge commit's first parent, and Hermes resolves its own version
+          # from the release tags merged into HEAD. A shallow checkout reports
+          # "unknown", which plugins checking the host version reject (omh).
+          fetch-depth: 0
+          filter: blob:none
           # `hermes plugins validate` below runs pinned-repo code; keep the
           # job's token out of .git/config where that code could read it.
           persist-credentials: false

.github/workflows/pm-bundle.yml

@@ -34,6 +34,7 @@ on:
   pull_request:
     paths:
       - 'pm/**'
+      - '!pm/**/*.md'
       - 'scripts/bundles/**'
       - 'scripts/ci/desktop_build_cache.py'
       - '.github/actions/desktop-build-cache/**'

.github/workflows/termux-verify.yml

@@ -6,12 +6,14 @@ on:
     paths:
       - 'scripts/termux/**'
       - 'pm/**'
+      - '!pm/**/*.md'
       - 'tests/scripts/test_termux*'
       - '.github/workflows/termux-verify.yml'
   pull_request:
     paths:
       - 'scripts/termux/**'
       - 'pm/**'
+      - '!pm/**/*.md'
       - 'tests/scripts/test_termux*'
       - '.github/workflows/termux-verify.yml'
   workflow_dispatch: