@evomap/evolver 1.89.2 → 1.89.3

package/README.ja-JP.md

@@ -1,11 +1,9 @@
 # 🧬 Evolver
 
-[![GitHub stars](https://img.shields.io/github/stars/EvoMap/evolver?style=social)](https://github.com/EvoMap/evolver/stargazers)
+[![GitHub stars](https://img.shields.io/badge/Stars-8.5k-2b3137?logo=github&logoColor=white)](https://github.com/EvoMap/evolver/stargazers)
 [![License: GPL-3.0](https://img.shields.io/badge/License-GPL--3.0-blue.svg)](https://opensource.org/licenses/GPL-3.0)
 [![Node.js >= 18](https://img.shields.io/badge/Node.js-%3E%3D%2018-green.svg)](https://nodejs.org/)
-[![GitHub last commit](https://img.shields.io/github/last-commit/EvoMap/evolver)](https://github.com/EvoMap/evolver/commits/main)
 [![npm downloads](https://img.shields.io/npm/dm/@evomap/evolver.svg)](https://www.npmjs.com/package/@evomap/evolver)
-[![GitHub issues](https://img.shields.io/github/issues/EvoMap/evolver)](https://github.com/EvoMap/evolver/issues)
 [![arXiv](https://img.shields.io/badge/arXiv-2604.15097-b31b1b.svg)](https://arxiv.org/abs/2604.15097)
 
 ![Evolver Cover](assets/cover.png)

package/README.ko-KR.md

@@ -1,11 +1,9 @@
 # 🧬 Evolver
 
-[![GitHub stars](https://img.shields.io/github/stars/EvoMap/evolver?style=social)](https://github.com/EvoMap/evolver/stargazers)
+[![GitHub stars](https://img.shields.io/badge/Stars-8.5k-2b3137?logo=github&logoColor=white)](https://github.com/EvoMap/evolver/stargazers)
 [![License: GPL-3.0](https://img.shields.io/badge/License-GPL--3.0-blue.svg)](https://opensource.org/licenses/GPL-3.0)
 [![Node.js >= 18](https://img.shields.io/badge/Node.js-%3E%3D%2018-green.svg)](https://nodejs.org/)
-[![GitHub last commit](https://img.shields.io/github/last-commit/EvoMap/evolver)](https://github.com/EvoMap/evolver/commits/main)
 [![npm downloads](https://img.shields.io/npm/dm/@evomap/evolver.svg)](https://www.npmjs.com/package/@evomap/evolver)
-[![GitHub issues](https://img.shields.io/github/issues/EvoMap/evolver)](https://github.com/EvoMap/evolver/issues)
 [![arXiv](https://img.shields.io/badge/arXiv-2604.15097-b31b1b.svg)](https://arxiv.org/abs/2604.15097)
 
 ![Evolver Cover](assets/cover.png)

package/README.md

@@ -1,11 +1,9 @@
 # 🧬 Evolver
 
-[![GitHub stars](https://img.shields.io/github/stars/EvoMap/evolver?style=social)](https://github.com/EvoMap/evolver/stargazers)
+[![GitHub stars](https://img.shields.io/badge/Stars-8.5k-2b3137?logo=github&logoColor=white)](https://github.com/EvoMap/evolver/stargazers)
 [![License: GPL-3.0](https://img.shields.io/badge/License-GPL--3.0-blue.svg)](https://opensource.org/licenses/GPL-3.0)
 [![Node.js >= 18](https://img.shields.io/badge/Node.js-%3E%3D%2018-green.svg)](https://nodejs.org/)
-[![GitHub last commit](https://img.shields.io/github/last-commit/EvoMap/evolver)](https://github.com/EvoMap/evolver/commits/main)
 [![npm downloads](https://img.shields.io/npm/dm/@evomap/evolver.svg)](https://www.npmjs.com/package/@evomap/evolver)
-[![GitHub issues](https://img.shields.io/github/issues/EvoMap/evolver)](https://github.com/EvoMap/evolver/issues)
 [![arXiv](https://img.shields.io/badge/arXiv-2604.15097-b31b1b.svg)](https://arxiv.org/abs/2604.15097)
 
 ![Evolver Cover](assets/cover.png)

package/README.zh-CN.md

@@ -1,11 +1,9 @@
 # 🧬 Evolver
 
-[![GitHub stars](https://img.shields.io/github/stars/EvoMap/evolver?style=social)](https://github.com/EvoMap/evolver/stargazers)
+[![GitHub stars](https://img.shields.io/badge/Stars-8.5k-2b3137?logo=github&logoColor=white)](https://github.com/EvoMap/evolver/stargazers)
 [![License: GPL-3.0](https://img.shields.io/badge/License-GPL--3.0-blue.svg)](https://opensource.org/licenses/GPL-3.0)
 [![Node.js >= 18](https://img.shields.io/badge/Node.js-%3E%3D%2018-green.svg)](https://nodejs.org/)
-[![GitHub last commit](https://img.shields.io/github/last-commit/EvoMap/evolver)](https://github.com/EvoMap/evolver/commits/main)
 [![npm downloads](https://img.shields.io/npm/dm/@evomap/evolver.svg)](https://www.npmjs.com/package/@evomap/evolver)
-[![GitHub issues](https://img.shields.io/github/issues/EvoMap/evolver)](https://github.com/EvoMap/evolver/issues)
 [![arXiv](https://img.shields.io/badge/arXiv-2604.15097-b31b1b.svg)](https://arxiv.org/abs/2604.15097)
 
 ![Evolver Cover](assets/cover.png)

package/assets/gep/genes.seed.json

@@ -240,6 +240,257 @@
         "tier": "cheap",
         "reasoning_level": "low"
       }
+    },
+    {
+      "type": "Gene",
+      "id": "gene_publish_feishu_doc",
+      "category": "innovate",
+      "signals_match": [
+        "publish_markdown_to_feishu",
+        "create_feishu_doc",
+        "export_report_to_feishu",
+        "把结果发到飞书文档",
+        "发布飞书文档",
+        "把报告导出到飞书",
+        "publish results to a feishu doc",
+        "export notes to lark document",
+        "飞书文档",
+        "发布到飞书",
+        "导出到飞书",
+        "发到飞书",
+        "lark文档",
+        "飞书文档|lark doc|feishu doc"
+      ],
+      "strategy": [
+        "Verify the toolchain: run `lark-cli doctor` and require ok:true with at least one ready identity",
+        "Always use the Docs v2 API (v1 is deprecated): pass `--api-version v2`",
+        "Write the body as Lark-flavored Markdown to a temp file and pass `--content @file.md --doc-format markdown` to avoid shell-escaping bugs",
+        "Create with the user identity so the doc is human-owned: `lark-cli docs +create --api-version v2 --as user --doc-format markdown --content @file.md`",
+        "To place it in a folder or wiki add `--parent-token <token>` (use `--parent-position my_library` for the personal space)",
+        "Parse data.document.url from the JSON response and return it to the user; use `docs +update --api-version v2` with the document_id to amend instead of recreating"
+      ],
+      "validation": [
+        "node --version"
+      ],
+      "constraints": {
+        "max_files": 2,
+        "forbidden_paths": [
+          ".git",
+          "node_modules",
+          "~/.lark-cli/config.json"
+        ]
+      },
+      "preconditions": [
+        "lark-cli installed and on PATH (npm i -g @larksuite/cli)",
+        "lark-cli auth status reports a ready user or bot identity"
+      ],
+      "summary": "Publish Markdown content as a Feishu/Lark document via the official lark-cli (Docs v2). Use --as user for human-owned docs and @file content for long bodies; return the resulting document URL.",
+      "schema_version": "1.6.0",
+      "epigenetic_marks": [],
+      "learning_history": [],
+      "anti_patterns": [],
+      "routing_hint": null,
+      "tool_policy": null,
+      "avoid": [
+        "using the deprecated Docs v1 API or the v1 --markdown flag",
+        "passing long markdown inline (shell-escaping corrupts it) instead of --content @file",
+        "overwriting ~/.lark-cli/config.json (holds the app secret and tokens)"
+      ],
+      "asset_id": "sha256:9ed275fd6394567d0eb6c0fda45193bbeaba7bd84941ea4e75eb7fc859fb0dcf"
+    },
+    {
+      "type": "Gene",
+      "id": "gene_conventional_git_commit",
+      "category": "optimize",
+      "signals_match": [
+        "git_commit",
+        "create_commit",
+        "commit_changes",
+        "conventional_commit",
+        "提交代码",
+        "生成提交信息",
+        "write a commit message",
+        "stage and commit"
+      ],
+      "strategy": [
+        "Inspect the change: `git diff --staged` if anything is staged, else `git diff`, plus `git status --porcelain`",
+        "Pick a Conventional Commits type (feat/fix/docs/style/refactor/perf/test/build/ci/chore/revert) and optional scope from what actually changed",
+        "Stage logically-grouped files explicitly (git add <paths>); NEVER stage or commit secrets (.env, credentials, private keys)",
+        "Write a present-tense imperative description under 72 chars; add a body/footer for breaking changes (type! or BREAKING CHANGE:) and issue refs (Closes #N)",
+        "Commit one logical change with `git commit -m` (heredoc for multi-line)",
+        "Safety: never touch git config, never --force/hard-reset/--no-verify without explicit request, never force-push main; if a hook fails, fix and make a NEW commit (do not amend)"
+      ],
+      "validation": [
+        "node --version"
+      ],
+      "constraints": {
+        "max_files": 50,
+        "forbidden_paths": [
+          ".git",
+          "node_modules"
+        ]
+      },
+      "preconditions": [
+        "a git repository with staged or unstaged changes"
+      ],
+      "summary": "Create a Conventional Commits-style git commit: analyze the diff to pick type/scope, stage logical groups (never secrets), and write an imperative <72-char message.",
+      "schema_version": "1.6.0",
+      "epigenetic_marks": [],
+      "learning_history": [],
+      "anti_patterns": [],
+      "routing_hint": null,
+      "tool_policy": null,
+      "avoid": [
+        "committing secrets or unrelated changes in one commit",
+        "amending or force-pushing to bypass a failing hook",
+        "past-tense or vague messages like \"updated stuff\""
+      ],
+      "asset_id": "sha256:505c207b9984c397255daed61c5f24fb3bfcadedb803d2a4eaa429457f08cd2f"
+    },
+    {
+      "type": "Gene",
+      "id": "gene_poll_bugbot_review",
+      "category": "optimize",
+      "signals_match": [
+        "poll_bugbot",
+        "bugbot_review",
+        "wait_for_ci_review",
+        "pr_review_gate",
+        "等bugbot",
+        "等待评审",
+        "check bugbot",
+        "review the pr",
+        "pr opened"
+      ],
+      "strategy": [
+        "Poll the \"Cursor Bugbot\" check via `gh pr view --json statusCheckRollup` every ~60s until status=COMPLETED (cap ~10min); filter by name, not index",
+        "On SUCCESS: safe to merge ONLY if no other required check is red AND zero open inline comments from the cursor[bot] login (note the [bot] suffix)",
+        "On NEUTRAL: do NOT treat as pass — fetch inline comments `gh api repos/:o/:r/pulls/:n/comments` filtered to user.login==\"cursor[bot]\", surface path/line/severity, hand back to the human",
+        "On FAILURE/ACTION_REQUIRED: surface findings, do not merge",
+        "Auto-merge (squash + delete-branch) only when explicitly authorized AND conclusion is SUCCESS; merge conflicts/CI-red/required-review surface verbatim, never auto-fixed here"
+      ],
+      "validation": [
+        "node --version"
+      ],
+      "constraints": {
+        "max_files": 1,
+        "forbidden_paths": [
+          ".git",
+          "node_modules"
+        ]
+      },
+      "preconditions": [
+        "an open GitHub PR in a repo where Cursor Bugbot runs"
+      ],
+      "summary": "Wait for Cursor Bugbot on a GitHub PR, then gate on the conclusion: SUCCESS may merge, NEUTRAL/FAILURE always pauses to surface inline findings to the human.",
+      "schema_version": "1.6.0",
+      "epigenetic_marks": [],
+      "learning_history": [],
+      "anti_patterns": [],
+      "routing_hint": null,
+      "tool_policy": null,
+      "avoid": [
+        "treating NEUTRAL as pass (it has shipped real bugs before)",
+        "filtering comments on \"cursor\" instead of \"cursor[bot]\" (silently returns nothing)",
+        "auto-merging without explicit authorization or with CI red"
+      ],
+      "asset_id": "sha256:0f50f4cfecb0e6f3a9bd3c9c0a426e56f4f1c0230b4836a9471b38e499410ea9"
+    },
+    {
+      "type": "Gene",
+      "id": "gene_gateway_timeout_recovery",
+      "category": "repair",
+      "signals_match": [
+        "gateway_timeout",
+        "upstream_timeout",
+        "http_524",
+        "request_timed_out",
+        "超时了",
+        "网关超时",
+        "遇到超时",
+        "retry on timeout",
+        "operation timed out"
+      ],
+      "strategy": [
+        "Treat it as transient or size-driven, not a logic failure; do not report it as a hard failure before recovering",
+        "Retry the SAME operation verbatim exactly ONCE (a large fraction clear on immediate retry); do not loop",
+        "If it times out again, STOP retrying the monolith: split the work along a natural seam (per-file/dir/endpoint/record/section/time-window) into small independent units",
+        "Dispatch the units as parallel subagents in a single batch so each finishes under the gateway deadline; merge their results",
+        "If one unit itself times out, apply this same procedure recursively to that slice"
+      ],
+      "validation": [
+        "node --version"
+      ],
+      "constraints": {
+        "max_files": 1,
+        "forbidden_paths": [
+          ".git",
+          "node_modules"
+        ]
+      },
+      "preconditions": [
+        "a tool call / fetch / subagent / long command returned a gateway-class timeout (524/522/502/504)"
+      ],
+      "summary": "Recover from a gateway/upstream timeout: retry the same call once, and if it still times out, decompose the work into parallel subagents and merge — never loop the monolithic call.",
+      "schema_version": "1.6.0",
+      "epigenetic_marks": [],
+      "learning_history": [],
+      "anti_patterns": [],
+      "routing_hint": null,
+      "tool_policy": null,
+      "avoid": [
+        "retrying the same large call more than once",
+        "serial retries instead of parallel decomposition",
+        "surfacing the timeout as a hard failure before recovering"
+      ],
+      "asset_id": "sha256:63c4251dcd8308030194f797051c08672691b52553e00b0eb33772c215712acc"
+    },
+    {
+      "type": "Gene",
+      "id": "gene_github_webhook_listener",
+      "category": "innovate",
+      "signals_match": [
+        "github_webhook_listener",
+        "bugbot_webhook",
+        "passive_pr_notifications",
+        "设置webhook",
+        "部署webhook监听",
+        "notify when bugbot finishes",
+        "webhook tunnel"
+      ],
+      "strategy": [
+        "Run the idempotent deploy: a loopback Python listener (127.0.0.1:8644) validating GitHub X-Hub-Signature-256 HMAC via hmac.compare_digest, writing vetted payloads to ~/.claude/inbox/",
+        "Expose it via a cloudflared quick tunnel (outbound-only, no inbound port); a path-watcher re-PATCHes the GitHub webhook config whenever the tunnel URL changes",
+        "Keep listener + tunnel alive with systemd --user units hardened (ProtectSystem=strict, NoNewPrivileges, MemoryDenyWriteExecute); a SessionStart hook drains the inbox and re-validates PR state via gh api before surfacing",
+        "Security invariants: HMAC on every request, X-GitHub-Delivery dedup against replay, write-only sink (never exec/template/deserialize payload), file modes secret 0600 / inbox 0700",
+        "Add repos with deploy.sh --repos; rotate the secret every 90 days (rotate-secret.sh) and immediately on any leak; never trust the inbox payload without re-fetching"
+      ],
+      "validation": [
+        "node --version"
+      ],
+      "constraints": {
+        "max_files": 20,
+        "forbidden_paths": [
+          ".git",
+          "node_modules"
+        ]
+      },
+      "preconditions": [
+        "a developer machine with systemd --user and cloudflared available"
+      ],
+      "summary": "Deploy a per-developer GitHub webhook listener (HMAC-validated, cloudflared tunnel, systemd-kept) that drops PR/Bugbot events into ~/.claude/inbox for the next session to surface.",
+      "schema_version": "1.6.0",
+      "epigenetic_marks": [],
+      "learning_history": [],
+      "anti_patterns": [],
+      "routing_hint": null,
+      "tool_policy": null,
+      "avoid": [
+        "opening an inbound port instead of an outbound cloudflared tunnel",
+        "trusting the webhook payload without HMAC validation and PR re-fetch",
+        "execing or deserializing anything from the payload"
+      ],
+      "asset_id": "sha256:ac2a2f185390aef37996651ef21355f4beb437049e52a6ca3898619a8d648084"
     }
   ]
 }

package/index.js

@@ -268,23 +268,17 @@ function getLastSignals(statePath) {
 
 // Singleton Guard - prevent multiple evolver daemon instances.
 //
-// Round-4: pidfile location previously defaulted to __dirname, which is a
-// DIFFERENT path per install mode -- /usr/local/lib/node_modules/... for a
-// global install, the dev-clone path for `node index.js`, a transient
-// $NPM_CACHE/_npx/<hash> for `npx evolver`. Two daemons launched under
-// different install modes never saw each other's lock and could run
-// concurrently against the same ~/.evomap/node_secret, ping-ponging on
-// secret rotation and silently entering reauth backoff -- the user-
-// reported "first launch ok, idle, then dead forever" pattern. Default
-// now lives under the per-user state dir so all install modes converge.
-// EVOLVER_LOCK_DIR still overrides for tests / sandboxed runs.
-function getLockFilePath() {
-  if (process.env.EVOLVER_LOCK_DIR) {
-    return path.join(process.env.EVOLVER_LOCK_DIR, 'evolver.pid');
-  }
-  // os.homedir() is cross-platform; process.env.HOME is unset on Windows.
-  return path.join(os.homedir(), '.evomap', 'instance.lock');
-}
+// Lock location + lease tunables live in src/adapters/scripts/_lockPaths.js
+// (issue #176): the session-start hook's auto-restart guard needs the exact
+// same resolution, and inlining it in both places drifted. The Round-4
+// (per-install-mode pidfile convergence) and Round-9 (lease staleness)
+// history notes moved there with the code.
+const {
+  getLockFilePath,
+  lockIsStaleByLease: _lockIsStaleByLease,
+  STALE_LOCK_TTL_MS,
+  LOCK_REFRESH_MS,
+} = require('./src/adapters/scripts/_lockPaths');
 
 function _writeLockAtomic(lockFile, payload) {
   // Round-6 (§19.8): the previous implementation used tmp + rename, which
@@ -372,38 +366,11 @@ function _lockPayload() {
   });
 }
 
-// Round-9: lease tunables for the daemon lock. A live daemon refreshes the
-// lock mtime every LOCK_REFRESH_MS; a lock whose mtime is older than
-// STALE_LOCK_TTL_MS (and that was written by a lease-aware daemon) is
-// treated as stale even if its PID happens to be alive -- closing the
-// "crash + PID reuse -> new daemon silently refuses to start" hole and the
-// "SIGKILL leaves a stale lock nobody reclaims" hole. The TTL is well above
-// the heartbeat interval (default 6min) so a healthy daemon never trips it.
-// On Windows, SIGTERM is implemented as TerminateProcess() (not a catchable
-// signal), so the shutdown() handler that calls releaseLock() never runs.
-// The lock file stays on disk with the dead PID. Reduce the TTL on Windows
-// so a subsequent start doesn't wait 15 minutes to reclaim the stale lock.
-// Unix dropped from 15 min -> 5 min so a wedged daemon does not block takeover
-// for a quarter hour. 5 min is still 2.5x the 2-min Unix refresh cadence.
-// Windows 3 min TTL gets a 1-min refresh (3x margin) since 2-min refresh left
-// only 1.5x margin against transient FS hiccups.
-const STALE_LOCK_TTL_MS = process.platform === 'win32' ? 3 * 60_000 : 5 * 60_000;
-const LOCK_REFRESH_MS = process.platform === 'win32' ? 1 * 60_000 : 2 * 60_000;
+// STALE_LOCK_TTL_MS / LOCK_REFRESH_MS / _lockIsStaleByLease come from
+// src/adapters/scripts/_lockPaths.js (required next to getLockFilePath
+// above) — see issue #176 and the Round-9 history note in that module.
 let _lockRefreshTimer = null;
 
-// Returns true if the lock was written by a lease-aware daemon AND its
-// mtime is older than the stale TTL -- i.e. no live owner is refreshing it,
-// so it is safe to reclaim regardless of whether the recorded PID resolves.
-function _lockIsStaleByLease(lockFile, payload) {
-  if (!payload || payload.lease !== true) return false;
-  try {
-    const ageMs = Date.now() - fs.statSync(lockFile).mtimeMs;
-    return ageMs > STALE_LOCK_TTL_MS;
-  } catch (_) {
-    return false;
-  }
-}
-
 // Start refreshing the lock file's mtime so other processes can tell this
 // daemon is alive without trusting a (recyclable) PID. unref'd: it never
 // keeps the event loop open on its own, but fires for as long as the daemon

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evomap/evolver",
-  "version": "1.89.2",
+  "version": "1.89.3",
   "description": "A GEP-powered self-evolution engine for AI agents. Features automated log analysis and Genome Evolution Protocol (GEP) for auditable, reusable evolution assets.",
   "main": "index.js",
   "bin": {

package/scripts/refresh_stars_badge.js

@@ -0,0 +1,168 @@
+// refresh_stars_badge.js -- Refresh the static "Stars" badge count in the
+// public README sources to the live GitHub star count.
+//
+// Why this exists:
+//   The README stars badge is intentionally STATIC (a plain shields `badge/`
+//   URL, not a dynamic `github/stars` one) so it never renders shields.io's
+//   "Unable to select next GitHub token from pool" error when their shared
+//   GitHub token pool is rate-limited. The trade-off is that the number goes
+//   stale. This script re-stamps it at release time so the badge stays current
+//   without ever depending on the GitHub API to *render*.
+//
+// Usage:
+//   node scripts/refresh_stars_badge.js                 # update in place
+//   node scripts/refresh_stars_badge.js --dry-run       # print, write nothing
+//   node scripts/refresh_stars_badge.js --repo=O/N      # override repo
+//   node scripts/refresh_stars_badge.js --count=12345   # skip fetch (testing)
+//
+// Design notes:
+//   - Counts come from the PUBLIC repo (default EvoMap/evolver), not this
+//     private dev repo.
+//   - Fetch uses the already-authenticated `gh` CLI first (deploy.sh preflight
+//     guarantees gh auth), falling back to the unauthenticated GitHub REST API.
+//   - A fetch failure is NON-FATAL: we warn and exit 0, leaving the badge as
+//     is. A flaky GitHub API must never break a release -- avoiding exactly
+//     that fragility is the whole reason the badge is static.
+//   - It rewrites every README*.md in the repo root that contains the badge,
+//     so new translations are picked up automatically.
+
+const fs = require('fs');
+const path = require('path');
+const https = require('https');
+const { execSync } = require('child_process');
+
+const REPO_ROOT = path.resolve(__dirname, '..');
+const DEFAULT_REPO = 'EvoMap/evolver';
+
+// Matches the value segment of `.../badge/Stars-<value>-<color>...` in a
+// shields static badge URL. The value never contains `-` or `/`. Returns a
+// fresh regex each call so callers never share `lastIndex` state.
+const starsBadgeRe = () => /(img\.shields\.io\/badge\/Stars-)([^-/)]+)(-)/g;
+
+// Replace the Stars badge value in `content` with `value`. Pure; returns the
+// rewritten string (unchanged if there is no badge or it already matches).
+function rewriteStarsValue(content, value) {
+  return content.replace(starsBadgeRe(), (_m, pre, _old, post) => `${pre}${value}${post}`);
+}
+
+function parseArgs(argv) {
+  const opts = { dryRun: false, repo: DEFAULT_REPO, count: null };
+  for (const arg of argv) {
+    if (arg === '--dry-run' || arg === '-n') opts.dryRun = true;
+    else if (arg.startsWith('--repo=')) opts.repo = arg.slice('--repo='.length);
+    else if (arg.startsWith('--count=')) opts.count = Number(arg.slice('--count='.length));
+  }
+  return opts;
+}
+
+// Format an integer the way shields.io's `metric` text formatter does, so the
+// static badge is visually indistinguishable from a dynamic one:
+//   8336 -> "8.3k", 12345 -> "12k", 1100 -> "1.1k", 999 -> "999".
+function metric(n) {
+  n = Number(n);
+  if (!Number.isFinite(n) || n < 0) return String(n);
+  for (const [suffix, size] of [['G', 1e9], ['M', 1e6], ['k', 1e3]]) {
+    if (n >= size) {
+      const value = n / size;
+      const text = value < 10
+        ? value.toFixed(1).replace(/\.0$/, '')
+        : String(Math.round(value));
+      return text + suffix;
+    }
+  }
+  return String(Math.round(n));
+}
+
+function fetchStarsViaGh(repo) {
+  try {
+    const out = execSync(`gh api repos/${repo} --jq .stargazers_count`, {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    const n = Number(out);
+    return Number.isFinite(n) && n > 0 ? n : null;
+  } catch {
+    return null;
+  }
+}
+
+function fetchStarsViaApi(repo) {
+  return new Promise((resolve) => {
+    const req = https.get(
+      `https://api.github.com/repos/${repo}`,
+      { headers: { 'User-Agent': 'evolver-refresh-stars-badge', Accept: 'application/vnd.github+json' } },
+      (res) => {
+        if (res.statusCode !== 200) { res.resume(); return resolve(null); }
+        let body = '';
+        res.on('data', (c) => (body += c));
+        res.on('end', () => {
+          try {
+            const n = Number(JSON.parse(body).stargazers_count);
+            resolve(Number.isFinite(n) && n > 0 ? n : null);
+          } catch { resolve(null); }
+        });
+      },
+    );
+    req.on('error', () => resolve(null));
+    req.setTimeout(10000, () => { req.destroy(); resolve(null); });
+  });
+}
+
+async function resolveStarCount(opts) {
+  if (Number.isFinite(opts.count) && opts.count > 0) return opts.count;
+  return fetchStarsViaGh(opts.repo) || (await fetchStarsViaApi(opts.repo));
+}
+
+function readmeFilesWithBadge() {
+  return fs
+    .readdirSync(REPO_ROOT)
+    .filter((f) => /^README.*\.md$/.test(f))
+    .map((f) => path.join(REPO_ROOT, f))
+    .filter((p) => starsBadgeRe().test(fs.readFileSync(p, 'utf8')));
+}
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+
+  const count = await resolveStarCount(opts);
+  if (count == null) {
+    console.warn('[refresh-stars-badge] could not resolve star count (gh + API both failed); leaving badge unchanged');
+    return; // non-fatal
+  }
+  const value = metric(count);
+  console.log(`[refresh-stars-badge] ${opts.repo} = ${count} stars -> "${value}"`);
+
+  const files = readmeFilesWithBadge();
+  if (files.length === 0) {
+    console.warn('[refresh-stars-badge] no README*.md with a Stars badge found; nothing to do');
+    return;
+  }
+
+  let changed = 0;
+  for (const file of files) {
+    const before = fs.readFileSync(file, 'utf8');
+    const after = rewriteStarsValue(before, value);
+    const rel = path.relative(REPO_ROOT, file);
+    if (after === before) {
+      console.log(`  ${rel}: already "${value}"`);
+      continue;
+    }
+    if (opts.dryRun) {
+      console.log(`  [dry-run] ${rel}: would set Stars -> "${value}"`);
+    } else {
+      fs.writeFileSync(file, after);
+      console.log(`  ${rel}: Stars -> "${value}"`);
+    }
+    changed++;
+  }
+  console.log(`[refresh-stars-badge] ${changed} file(s) ${opts.dryRun ? 'would change' : 'updated'}`);
+}
+
+if (require.main === module) {
+  main().catch((e) => {
+    // Never fail the release over a badge refresh.
+    console.warn(`[refresh-stars-badge] unexpected error (ignored): ${e && e.message}`);
+  });
+}
+
+module.exports = { metric, rewriteStarsValue };

package/src/adapters/hookAdapter.js

@@ -168,6 +168,7 @@ function copyHookScripts(destDir, evolverRoot) {
   const scripts = [
     '_runtimePaths.js',
     '_memoryFiltering.js',
+    '_lockPaths.js',
     'evolver-session-start.js',
     'evolver-signal-detect.js',
     'evolver-session-end.js',
@@ -255,6 +256,7 @@ function removeHookScripts(hooksDir) {
   const scripts = [
     '_runtimePaths.js',
     '_memoryFiltering.js',
+    '_lockPaths.js',
     'evolver-session-start.js',
     'evolver-signal-detect.js',
     'evolver-session-end.js',