@link-assistant/hive-mind 2.17.0 → 2.19.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # @link-assistant/hive-mind
 
+## 2.19.0
+
+### Minor Changes
+
+- ac07514: Stop the model list from ageing with the release: add the models that shipped since 2.17.0, hot-load the live catalogue from every source that costs nothing to read, expose it as `/models` and `hive-models`, teach `--use-router` both of the router's route dialects, and check the agentic CLI for a newer version before a task starts (issue #2202).
+
+  A provider can ship a model on a Tuesday, and until now Hive Mind could not name it until the next release: `src/models/index.mjs` was a static table and `--model` validated against nothing else. Six changes close that gap, none of which can spend a token or fail a run.
+
+  - **The new models are in the bundled table.** Fable 5.1, Mythos 5.1, GPT-6 Astra and GPT-5.6 Cyber, with their aliases, context windows and fallback chains. The additions pushed `src/models/index.mjs` past the 1350-line early warning of `scripts/check-file-line-limits.sh`, so the catalogue itself moved to `src/models/catalog.mjs` and is re-exported — the public surface is unchanged.
+  - **The catalogue hot-loads.** `src/model-catalogue.lib.mjs` merges six sources in a fixed precedence: the Link.Assistant Router's live catalogue, `codex debug models`, Anthropic's and OpenAI's `GET /v1/models`, models.dev for specifications, and the bundled table as the offline floor. models.dev only annotates; it never adds a model to the available list. Answers are cached per source and per tool for at least an hour, and `HIVE_MIND_MODEL_CATALOGUE_TTL_MINUTES` can only raise that floor.
+  - **Listing models cannot cost a token, structurally.** `assertTokenFreeSource` rejects any source that has not explicitly declared `billable: false`, so a source cannot become billable by omission, and `assertTokenFreeUrl` rejects any URL whose path is a completion endpoint no matter which descriptor carried it — a typo turning `/v1/models` into `/v1/messages` throws instead of spending. The four extraction methods that were considered and rejected, including driving either CLI's `/model` picker through its TUI, are recorded with their reasons so a future contributor does not re-derive them.
+  - **`/models` and `hive-models` show the whole spectrum.** Models are grouped as bundled-and-live, hot-loaded (a live source has it, this installation does not ship it), and bundled-only (shipped, unconfirmed), with `--tool`, `--details`, `--refresh`, `--json`, and `--all`. A footer names every source actually consulted, its outcome, and the age of the cache, so "why don't I see X" is answerable from the output — and a source that failed is described from its stderr, never by quoting the command line, so the router's leased token cannot ride a failure message into the footer. In Telegram the same flags are accepted the way a chat writes them: `/models codex`, `/models --tool codex` and `/models --tool=codex` are one command.
+  - **`--use-router` speaks both route dialects.** Router 1.0 removed every root, `/v1/*` and overlapping `/api/*` alias and moved each service under `/api/services/<service>/…` — measured, not assumed: on `1.2.0` every path that answers on `0.119.0` is a 404 and vice versa. `src/router-routes.lib.mjs` derives every base URL, the health probe and the catalogue path from the pinned image, so the pin can move in one line. It stays on `0.x` today, at `0.125.4`, because router `1.x` has no `gh`-reachable REST base and `gh` exposes no path-prefix option; the trade is reported by `describeRouterCoverageGaps` rather than discovered at runtime, and the upstream issues are filed.
+  - **A stale CLI is refreshed before the run needs it.** `/solve`, `/hive`, `/task`, `/fix`, `/models` and `hive-models` check the agentic CLI they are about to drive, because an outdated binary is the usual reason a brand-new model name is rejected. The check is throttled to once every six hours, narrowed to the one CLI in play, deferred entirely while other tasks are running, skipped for `--dry-run` and `--only-prepare-command`, and never fatal. Each run excludes its own task from the idle gate — otherwise a `/solve` asking for an update would find itself in the process table and defer forever. Opt out with `--no-tool-update` or `HIVE_MIND_AGENTIC_CLI_AUTO_UPDATE=0`.
+
+  Documentation is in `docs/MODELS.md` and its `zh`/`hi`/`ru` siblings; the full analysis — the requirement-by-requirement plan, the router route measurement, and what shipped differently from the plan — is in `docs/case-studies/issue-2202/`.
+
+## 2.18.0
+
+### Minor Changes
+
+- 3fc12ef: Recover broken GitHub URLs instead of rejecting them, and say what was repaired (issue #2194).
+
+  A user sent `/Claude https://github.com/G-Ivan-A/aether-orbis/pulls/30`. Telegram drew a healthy GitHub preview card under it, because github.com really does answer `/owner/repo/pulls/30` with **HTTP 200** and a full set of Open Graph tags — a genuinely wrong path like `/pullz/30` 404s and gets no card. The bot then refused the command and told the user to "1. Open the repository: https://github.com/G-Ivan-A/aether-orbis/**pulls/30**" — the same broken link that had just failed. Meanwhile `parseGitHubUrl` had already extracted the number: the pre-fix `case 'pulls'` stored `'30'` in `result.subpath` and nothing ever read it. The data to restore the URL from was sitting in the result object.
+
+  - **`src/github-url-recovery.lib.mjs`** repairs a URL before it is parsed: strips invisible characters (`\p{Cf}`/`\p{Cc}`/`\p{Zl}`/`\p{Zp}`, U+034F, variation selectors), unwraps `[title](url)` / `<url>` / `(url).`, folds full-width and fraction punctuation and full-width digits to ASCII, lower-cases scheme and host, reads `git@github.com:owner/repo.git` and `api.github.com/repos/...` as their web addresses, and reads `/pulls/30` as `/pull/30`, `/issue/123` as `/issues/123`, `/pull/30/files` as the pull request itself.
+  - **Recovery is on by default inside `parseGitHubUrl`**, so all 48 call sites across 14 files get it without changing any of them. `{ recover: false }` reproduces the old code path exactly, which is what makes the before/after evidence reproducible.
+  - **It never invents a GitHub URL.** `gitlab.com`, `bitbucket.org`, `gist.github.com`, `raw.githubusercontent.com`, `github.com.evil.example` and `evil.example/github.com/...` are all still rejected — and so is over-reach in the other direction: `support@github.com` is an email address rather than a repository (`git@github.com:owner/repo.git` still works), and `[the PR](aether-orbis)` stays rejected because unwrapping prose is only worth doing when what comes out already names github.com.
+  - **It never repairs silently.** Every result carries `original`, `repairs[]` and `recovered`, plus `hidden`/`revealed` when something invisible was removed. The Telegram bot (new `telegram.url_recovered` string in `en`/`ru`/`hi`/`zh`), `solve` and `hive` each print what they understood before acting on it.
+  - **Two silent-corruption bugs went with it.** A zero-width space in a repository name used to produce `valid: true` for `aether-orbis%E2%80%8B` — a repository that does not exist. `HTTPS://GITHUB.COM/...` used to parse as a _relative path_ with `HTTPS:` as the owner; the bot's own `url.includes('github.com')` gate had the same flaw and rejected the URL before the parser saw it — that gate now asks the recovery layer whether the text names github.com as its _host_, so `evil.example/github.com/...` no longer passes it either.
+  - **The log could not have proved an invisible character even if there had been one** — it never recorded the message text. `/solve` and its aliases now log raw text through `revealHiddenCharacters()` (a zero-width space appears as `[U+200B]`), and `traceUrlRecovery()` reports each repair stage under `--verbose`.
+
+  `normalize-url@9` and `confusables@1` were installed and measured against these exact inputs rather than assumed: `normalize-url` percent-encodes the zero-width space instead of removing it and **throws** on a full-width colon, and `confusables` turns `github.com/Ćwikła/...` into `github.com/Cwikla/...` — it would silently retarget a real owner. Neither knows that `/pulls/30` means pull request 30.
+
+  77 assertions in `tests/test-issue-2194-broken-url-recovery.mjs`. Timeline, evidence and the full analysis are in `docs/case-studies/issue-2194/README.md`, with reproduction scripts in `experiments/issue-2194/` and `examples/github-url-recovery-demo.mjs`.
+
 ## 2.17.0
 
 ### Minor Changes

package/README.hi.md

@@ -515,6 +515,8 @@ Free Models via Kilo Gateway (with --tool agent):
 
 > **📖 मुफ्त मॉडल गाइड**: OpenCode Zen और Kilo Gateway प्रदाताओं सहित सभी मुफ्त मॉडलों के बारे में व्यापक जानकारी के लिए [docs/FREE_MODELS.hi.md](./docs/FREE_MODELS.hi.md) देखें।
 
+> **📖 लाइव मॉडल सूची**: यह देखने के लिए कि इस समय कौन-से मॉडल उपलब्ध हैं — उनमें वे भी जो इस installation के प्रकाशित होने के बाद जारी हुए — `hive-models` चलाएँ (या Telegram में `/models`)। देखें [docs/MODELS.hi.md](./docs/MODELS.hi.md)।
+
 #### `/hive` - Hive ऑर्केस्ट्रेशन चलाएँ
 
 ```

package/README.md

@@ -533,6 +533,8 @@ See [docs/CONFIGURATION.md](./docs/CONFIGURATION.md) for the full per-tool defau
 
 > **📖 Free Models Guide**: See [docs/FREE_MODELS.md](./docs/FREE_MODELS.md) for comprehensive information about all free models including OpenCode Zen and Kilo Gateway providers.
 
+> **📖 Live model list**: run `hive-models` (or `/models` in Telegram) to see which models are reachable right now, including ones released after this installation was published. See [docs/MODELS.md](./docs/MODELS.md).
+
 #### `/hive` - Run Hive Orchestration
 
 ```

package/README.ru.md

@@ -516,6 +516,8 @@ Free Models via Kilo Gateway (with --tool agent):
 
 > **📖 Руководство по бесплатным моделям**: см. [docs/FREE_MODELS.ru.md](./docs/FREE_MODELS.ru.md) для получения полной информации обо всех бесплатных моделях, включая провайдеры OpenCode Zen и Kilo Gateway.
 
+> **📖 Живой список моделей**: запустите `hive-models` (или `/models` в Telegram), чтобы увидеть, какие модели доступны прямо сейчас, включая вышедшие уже после публикации этой установки. См. [docs/MODELS.ru.md](./docs/MODELS.ru.md).
+
 #### `/hive` — Запуск оркестрации Hive
 
 ```

package/README.zh.md

@@ -512,6 +512,8 @@ Free Models via Kilo Gateway (with --tool agent):
 
 > **📖 免费模型指南**：有关所有免费模型（包括 OpenCode Zen 和 Kilo Gateway 提供商）的全面信息，请参见 [docs/FREE_MODELS.zh.md](./docs/FREE_MODELS.zh.md)。
 
+> **📖 实时模型列表**：运行 `hive-models`（或在 Telegram 中使用 `/models`）即可查看当前可用的模型，包括本次安装发布之后才推出的模型。参见 [docs/MODELS.zh.md](./docs/MODELS.zh.md)。
+
 #### `/hive` - 运行蜂群编排
 
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@link-assistant/hive-mind",
-  "version": "2.17.0",
+  "version": "2.19.0",
   "description": "AI-powered issue solver and hive mind for collaborative problem solving",
   "main": "src/hive.mjs",
   "type": "module",
@@ -14,6 +14,7 @@
     "configure-claude": "./src/configure-claude.mjs",
     "start-screen": "./src/start-screen.mjs",
     "hive-screens": "./src/hive-screens.mjs",
+    "hive-models": "./src/hive-models.mjs",
     "hive-telegram-bot": "./src/telegram-bot.mjs"
   },
   "scripts": {
@@ -30,7 +31,7 @@
     "changeset": "changeset",
     "changeset:version": "changeset version",
     "changeset:publish": "npm run build:pre && changeset publish",
-    "build:pre": "chmod +x src/hive.mjs && chmod +x src/solve.mjs && chmod +x src/task.mjs && chmod +x src/fix.mjs && chmod +x src/cleanup.mjs && chmod +x src/review.mjs && chmod +x src/configure-claude.mjs && chmod +x src/start-screen.mjs && chmod +x src/hive-screens.mjs && chmod +x src/telegram-bot.mjs",
+    "build:pre": "chmod +x src/hive.mjs && chmod +x src/solve.mjs && chmod +x src/task.mjs && chmod +x src/fix.mjs && chmod +x src/cleanup.mjs && chmod +x src/review.mjs && chmod +x src/configure-claude.mjs && chmod +x src/start-screen.mjs && chmod +x src/hive-screens.mjs && chmod +x src/hive-models.mjs && chmod +x src/telegram-bot.mjs",
     "prepare": "husky"
   },
   "repository": {

package/src/agentic-cli-freshness.lib.mjs

@@ -0,0 +1,118 @@
+/**
+ * Pre-flight CLI freshness check (issue #2202, R6).
+ *
+ * R6: "/models and each /solve and other commands that relevant for
+ * claude/codex tools should check if new version available, and before
+ * starting task execution or before providing new models list - we should
+ * update them."
+ *
+ * `updateAgenticClisWhenIdle` already knows how to do the refresh safely — it
+ * throttles registry reads, takes a state lock, and refuses to swap a binary
+ * out from under a running task. What it lacked was a caller other than the
+ * Telegram maintenance tick, and two things a command entry point needs:
+ *
+ *  1. **Narrowing.** `hive-models --tool codex` should not reinstall Gemini.
+ *  2. **Not counting itself as busy.** The idle gate scans `/proc` for running
+ *     solve/task processes by issue reference. A solve run that checks for
+ *     updates after it has started would find *itself* and defer forever, so
+ *     the caller passes its own task reference to be ignored.
+ *
+ * Everything here is best-effort: a refresh failure must never stop the command
+ * the operator actually asked for.
+ *
+ * @see https://github.com/link-assistant/hive-mind/issues/2202
+ */
+
+import { AGENTIC_CLI_TARGETS, isAgenticCliAutoUpdateEnabled, updateAgenticClisWhenIdle } from './agentic-cli-updater.lib.mjs';
+
+const KNOWN_TOOL_IDS = new Set(AGENTIC_CLI_TARGETS.map(target => target.id));
+
+/** Tool aliases Hive Mind commands use that are not the updater's target id. */
+export const FRESHNESS_TOOL_ALIASES = Object.freeze({
+  'claude-code': 'claude',
+  'gemini-cli': 'gemini',
+  'qwen-code': 'qwen',
+  'github-copilot': 'copilot',
+  'opencode-ai': 'opencode',
+});
+
+/** Normalize whatever a command calls its tool into updater target ids. */
+export const resolveFreshnessTools = tools => {
+  const requested = (Array.isArray(tools) ? tools : [tools])
+    .flatMap(entry =>
+      String(entry ?? '')
+        .split(',')
+        .map(part => part.trim().toLowerCase())
+    )
+    .filter(Boolean);
+  const resolved = [];
+  for (const entry of requested) {
+    const id = FRESHNESS_TOOL_ALIASES[entry] ?? entry;
+    if (KNOWN_TOOL_IDS.has(id) && !resolved.includes(id)) resolved.push(id);
+  }
+  return resolved;
+};
+
+/** `https://github.com/o/r/issues/7` → `{owner:'o', repo:'r', number:7}`. */
+export const parseTaskRef = value => {
+  if (!value) return null;
+  if (typeof value === 'object') {
+    const number = Number(value.number);
+    if (!value.owner || !value.repo || !Number.isFinite(number)) return null;
+    return { owner: String(value.owner), repo: String(value.repo), number };
+  }
+  const match = String(value).match(/github\.com\/([^/\s]+)\/([^/\s]+)\/(?:issues|pull)\/(\d+)/i);
+  if (!match) return null;
+  return { owner: match[1], repo: match[2], number: Number(match[3]) };
+};
+
+const sameRef = (a, b) => a.owner.toLowerCase() === b.owner.toLowerCase() && a.repo.toLowerCase() === b.repo.toLowerCase() && a.number === b.number;
+
+/**
+ * Refresh the agentic CLIs a command is about to drive.
+ *
+ * Never throws: every failure path returns a status the caller can log and
+ * ignore. Statuses come from `updateAgenticClisWhenIdle`
+ * (`checked`/`throttled`/`busy`/`disabled`) plus `skipped` for a caller opt-out
+ * and `error` when the refresh itself blew up.
+ *
+ * @param {object} options
+ * @param {string|string[]} options.tools tool ids/aliases the command needs
+ * @param {boolean} options.enabled false for `--no-update`
+ * @param {Array} options.ignoreTasks task refs or GitHub URLs that are *this* run
+ */
+export const ensureAgenticCliFreshness = async ({ tools = [], env = process.env, log = null, verbose = false, force = false, enabled = true, ignoreTasks = [], getActiveTasksImpl = null, updateImpl = updateAgenticClisWhenIdle, minIntervalMs = undefined } = {}) => {
+  const only = resolveFreshnessTools(tools);
+  if (!enabled) return { status: 'skipped', reason: 'the caller disabled the update check (--no-update)', tools: only, updated: [], upToDate: [], failed: [] };
+  if (!isAgenticCliAutoUpdateEnabled(env)) return { status: 'disabled', reason: 'HIVE_MIND_AGENTIC_CLI_AUTO_UPDATE is off', tools: only, updated: [], upToDate: [], failed: [] };
+
+  const ignored = ignoreTasks.map(parseTaskRef).filter(Boolean);
+  let activeTasks = getActiveTasksImpl;
+  if (ignored.length > 0) {
+    const inner = getActiveTasksImpl ?? (await import('./cleanup.os.lib.mjs')).getActiveTasks;
+    activeTasks = async options => {
+      const tasks = await inner(options);
+      return tasks.filter(task => !ignored.some(ref => sameRef(ref, { owner: task.owner, repo: task.repo, number: Number(task.number) })));
+    };
+  }
+
+  try {
+    const result = await updateImpl({ env, log, verbose, force, only, ...(activeTasks ? { getActiveTasksImpl: activeTasks } : {}), ...(minIntervalMs === undefined ? {} : { minIntervalMs }) });
+    return { tools: only, updated: [], upToDate: [], failed: [], ...result };
+  } catch (error) {
+    const message = String(error?.message ?? error);
+    if (verbose && log) await log(`[VERBOSE] agentic-cli-freshness: refresh failed — ${message}`);
+    return { status: 'error', reason: message, tools: only, updated: [], upToDate: [], failed: [] };
+  }
+};
+
+/** One human-readable line summarising a freshness result, or null when there is nothing to say. */
+export const describeFreshnessResult = result => {
+  if (!result) return null;
+  if (result.updated?.length > 0) return `⬆️ Updated ${result.updated.map(entry => `${entry.id} ${entry.from} → ${entry.to}`).join(', ')}`;
+  if (result.failed?.length > 0) return `⚠️ Could not update ${result.failed.map(entry => entry.id).join(', ')}`;
+  if (result.status === 'busy') return 'Skipped the CLI update check: other tasks are running.';
+  return null;
+};
+
+export default { FRESHNESS_TOOL_ALIASES, describeFreshnessResult, ensureAgenticCliFreshness, parseTaskRef, resolveFreshnessTools };

package/src/agentic-cli-updater.lib.mjs

@@ -81,10 +81,14 @@ const parseIdList = value =>
  * `HIVE_MIND_AGENTIC_CLI_UPDATE_ONLY` is an allow-list and
  * `HIVE_MIND_AGENTIC_CLI_UPDATE_EXCLUDE` a deny-list, both by target id.
  */
-export const listAgenticCliUpdateTargets = (env = process.env) => {
+export const listAgenticCliUpdateTargets = (env = process.env, { only: requested = [] } = {}) => {
   const only = parseIdList(env.HIVE_MIND_AGENTIC_CLI_UPDATE_ONLY);
   const excluded = new Set(parseIdList(env.HIVE_MIND_AGENTIC_CLI_UPDATE_EXCLUDE));
-  return AGENTIC_CLI_TARGETS.filter(target => (only.length === 0 || only.includes(target.id)) && !excluded.has(target.id));
+  // A caller-supplied narrowing (issue #2202, R6: refresh the CLIs a command is
+  // about to drive) intersects with the operator's allow-list rather than
+  // overriding it — an operator who excluded a CLI still gets it excluded.
+  const caller = parseIdList(Array.isArray(requested) ? requested.join(',') : requested);
+  return AGENTIC_CLI_TARGETS.filter(target => (only.length === 0 || only.includes(target.id)) && (caller.length === 0 || caller.includes(target.id)) && !excluded.has(target.id));
 };
 
 /** First semantic version in a CLI's `--version` output, which is rarely bare. */
@@ -147,7 +151,7 @@ export const installAgenticCli = async (target, { run = execFileAsync, timeoutMs
  *
  * @returns {Promise<{status: 'disabled'|'busy'|'throttled'|'checked', updated: object[], upToDate: object[], failed: object[]}>}
  */
-export const updateAgenticClisWhenIdle = async ({ env = process.env, fsImpl = fs, run = execFileAsync, log = null, verbose = false, getActiveTasksImpl = null, now = () => new Date(), minIntervalMs = DEFAULT_CLI_UPDATE_INTERVAL_MS, force = false, lockOptions = {} } = {}) => {
+export const updateAgenticClisWhenIdle = async ({ env = process.env, fsImpl = fs, run = execFileAsync, log = null, verbose = false, getActiveTasksImpl = null, now = () => new Date(), minIntervalMs = DEFAULT_CLI_UPDATE_INTERVAL_MS, force = false, only = [], lockOptions = {} } = {}) => {
   if (!isAgenticCliAutoUpdateEnabled(env)) {
     if (verbose && log) await log('[VERBOSE] agentic-cli-updater: disabled by HIVE_MIND_AGENTIC_CLI_AUTO_UPDATE');
     return { status: 'disabled', updated: [], upToDate: [], failed: [] };
@@ -176,7 +180,7 @@ export const updateAgenticClisWhenIdle = async ({ env = process.env, fsImpl = fs
       const failed = [];
       const tools = { ...state.tools };
 
-      for (const target of listAgenticCliUpdateTargets(env)) {
+      for (const target of listAgenticCliUpdateTargets(env, { only })) {
         const installed = await readInstalledCliVersion(target, { run });
         if (!installed) {
           // Not installed on this host (image variants differ); nothing to refresh.

package/src/docker-sidecar.lib.mjs

@@ -49,8 +49,24 @@ export const dockerOk = async (run, args, options) => {
   }
 };
 
+/**
+ * Mask the secrets a `docker` argv carries.
+ *
+ * `execFile` builds a failed command's message as "Command failed: <argv…>",
+ * and the argvs assembled here carry real secrets: the router's
+ * `--env TOKEN_SECRET=…`, a leased `--env ROUTER_CATALOGUE_TOKEN=…`, a
+ * provider's `--api-key …`. stderr is preferred over that message precisely
+ * because it describes the failure without the command line, but stderr is
+ * empty when the process is killed on a timeout — so whatever survives is
+ * masked before anyone reads it.
+ */
+const maskDockerArgvSecrets = text =>
+  String(text ?? '')
+    .replace(/(--env[= ])([A-Za-z_][A-Za-z0-9_]*)=(\S+)/g, '$1$2=***')
+    .replace(/(--(?:api-key|token|secret|password)[= ])(\S+)/g, '$1***');
+
 /** The message a failed `docker` invocation should be reported with. */
-export const dockerErrorMessage = error => error?.stderr?.toString?.().trim() || error?.message || String(error);
+export const dockerErrorMessage = error => maskDockerArgvSecrets(error?.stderr?.toString?.().trim() || error?.message || String(error));
 
 /**
  * Inspect a container without treating "absent" as an error.

package/src/github-url-parser.lib.mjs

@@ -1,8 +1,37 @@
 import { reportError } from './sentry.lib.mjs';
+import { describeHiddenCharacters, repairGitHubPathParts, repairGitHubUrlText, revealHiddenCharacters, traceUrlRecovery } from './github-url-recovery.lib.mjs';
+
+/**
+ * Attach the issue #2194 recovery diagnostics to a parse result.
+ *
+ * `original` is always present so a caller can show the user what they actually
+ * sent; `hidden`/`revealed` only appear when there was something invisible to
+ * reveal, keeping the common result small.
+ *
+ * @param {Object} result - The result object to annotate (mutated and returned).
+ * @param {string} original - The URL exactly as it was passed in.
+ * @param {Array<{code: string, message: string, notable: boolean}>} repairs
+ * @param {Array<{escape: string, name: string}>} hidden
+ * @returns {Object} The same result object.
+ */
+function withRecoveryDiagnostics(result, original, repairs, hidden) {
+  result.original = original;
+  result.repairs = repairs;
+  result.recovered = repairs.length > 0;
+  if (hidden.length > 0) {
+    result.hidden = hidden;
+    result.revealed = revealHiddenCharacters(original);
+  }
+  return result;
+}
 
 /**
  * Universal GitHub URL parser that handles various formats
  * @param {string} url - The GitHub URL to parse
+ * @param {Object} [options] - Parsing options
+ * @param {boolean} [options.recover=true] - Repair recoverable damage (invisible
+ *   Unicode, wrappers, look-alike punctuation, `/pulls/30` for `/pull/30`, …)
+ *   before parsing. Pass `false` to see the URL exactly as it was typed.
  * @returns {Object} Parsed URL information including:
  *   - valid: boolean indicating if the URL is valid
  *   - normalized: the normalized URL (https://github.com/...), query/fragment kept
@@ -13,22 +42,41 @@ import { reportError } from './sentry.lib.mjs';
  *   - number: issue/PR number (if applicable)
  *   - path: additional path components
  *   - error: error message if invalid
+ *   - original: the URL exactly as it was passed in
+ *   - repairs: the list of repairs recovery had to apply (issue #2194)
+ *   - recovered: true when at least one repair was applied
+ *   - hidden/revealed: codepoint diagnostics, present only when the input carried
+ *     invisible or look-alike characters
  */
-export function parseGitHubUrl(url) {
+export function parseGitHubUrl(url, options = {}) {
   if (!url || typeof url !== 'string') {
     return {
       valid: false,
       error: 'Invalid input: URL must be a non-empty string',
     };
   }
+  const { recover = true } = options;
+  // Issue #2194: a URL that renders correctly on screen can still be broken —
+  // `…/pulls/30` previews as a healthy page, a zero-width space is unprintable by
+  // definition. Repair what can be repaired first, and keep a record of it, so the
+  // user is told what was interpreted instead of being told "invalid URL".
+  const hidden = describeHiddenCharacters(url);
+  let repairs = [];
   // Trim whitespace and remove trailing slashes
   let normalizedUrl = url.trim().replace(/\/+$/, '');
+  if (recover) {
+    const repaired = repairGitHubUrlText(normalizedUrl);
+    repairs = repaired.repairs;
+    if (repaired.rejection) {
+      traceUrlRecovery('rejected', { original: url, error: repaired.rejection, repairs, hidden });
+      return withRecoveryDiagnostics({ valid: false, error: repaired.rejection }, url, repairs, hidden);
+    }
+    normalizedUrl = repaired.text.replace(/\/+$/, '');
+    if (repairs.length > 0) traceUrlRecovery('repaired-text', { original: url, repaired: normalizedUrl, repairs, hidden });
+  }
   // Check if this looks like a valid GitHub-related input Reject clearly invalid inputs (spaces in the URL, special chars at the start, etc.)
   if (/\s/.test(normalizedUrl) || /^[!@#$%^&*()[\]{}|\\:;"'<>,?`~]/.test(normalizedUrl)) {
-    return {
-      valid: false,
-      error: 'Invalid GitHub URL format',
-    };
+    return withRecoveryDiagnostics({ valid: false, error: 'Invalid GitHub URL format' }, url, repairs, hidden);
   }
   // Handle protocol normalization
   if (!normalizedUrl.startsWith('http://') && !normalizedUrl.startsWith('https://')) {
@@ -40,10 +88,7 @@ export function parseGitHubUrl(url) {
       normalizedUrl = 'https://github.com/' + normalizedUrl;
     } else {
       // Has github.com somewhere but not at the start - likely malformed
-      return {
-        valid: false,
-        error: 'Invalid GitHub URL format',
-      };
+      return withRecoveryDiagnostics({ valid: false, error: 'Invalid GitHub URL format' }, url, repairs, hidden);
     }
   }
   // Convert http to https
@@ -56,11 +101,16 @@ export function parseGitHubUrl(url) {
     // Generate suggested URL by replacing backslashes with forward slashes
     const suggestedUrl = urlBeforeQueryAndHash.replace(/\\/g, '/');
     const urlAfterPath = normalizedUrl.substring(urlBeforeQueryAndHash.length);
-    return {
-      valid: false,
-      error: 'Invalid character in URL: backslash (\\) is not allowed in URL paths',
-      suggestion: suggestedUrl + urlAfterPath,
-    };
+    return withRecoveryDiagnostics(
+      {
+        valid: false,
+        error: 'Invalid character in URL: backslash (\\) is not allowed in URL paths',
+        suggestion: suggestedUrl + urlAfterPath,
+      },
+      url,
+      repairs,
+      hidden
+    );
   }
   // Parse the URL
   let urlObj;
@@ -74,17 +124,11 @@ export function parseGitHubUrl(url) {
         url: normalizedUrl,
       });
     }
-    return {
-      valid: false,
-      error: 'Invalid URL format',
-    };
+    return withRecoveryDiagnostics({ valid: false, error: 'Invalid URL format' }, url, repairs, hidden);
   }
   // Ensure it's a GitHub URL
   if (urlObj.hostname !== 'github.com' && urlObj.hostname !== 'www.github.com') {
-    return {
-      valid: false,
-      error: 'Not a GitHub URL',
-    };
+    return withRecoveryDiagnostics({ valid: false, error: 'Not a GitHub URL' }, url, repairs, hidden);
   }
   // Normalize hostname
   if (urlObj.hostname === 'www.github.com') {
@@ -92,7 +136,19 @@ export function parseGitHubUrl(url) {
     urlObj = new globalThis.URL(normalizedUrl);
   }
   // Parse the pathname
-  const pathParts = urlObj.pathname.split('/').filter(p => p);
+  let pathParts = urlObj.pathname.split('/').filter(p => p);
+  // Issue #2194: `/owner/repo/pulls/30` carries every byte needed to address pull
+  // request 30 — restore it rather than reporting the pull request list page.
+  if (recover) {
+    const pathRepair = repairGitHubPathParts(pathParts);
+    if (pathRepair.repairs.length > 0) {
+      repairs = repairs.concat(pathRepair.repairs);
+      pathParts = pathRepair.parts;
+      urlObj.pathname = `/${pathParts.join('/')}`;
+      normalizedUrl = urlObj.toString().replace(/\/+$/, '');
+      traceUrlRecovery('repaired-path', { original: url, repaired: normalizedUrl, repairs, hidden });
+    }
+  }
   // Handle different GitHub URL patterns
   const result = {
     valid: true,
@@ -108,6 +164,7 @@ export function parseGitHubUrl(url) {
     protocol: 'https',
     path: urlObj.pathname,
   };
+  withRecoveryDiagnostics(result, url, repairs, hidden);
   // No path - just github.com
   if (pathParts.length === 0) {
     result.type = 'home';