amicus 4.7.0 → 4.7.1

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "4.7.0",
+  "version": "4.7.1",
   "description": "Multi-model LLM Council + parallel AI window for Claude Code. Run structured council reviews across Gemini, GPT, DeepSeek and more — or fork a conversation to any model and fold the results back.",
   "author": {
     "name": "Christian Wagner"

package/CHANGELOG.md

@@ -5,6 +5,72 @@ All notable changes to Amicus are documented here. Format follows
 
 ## [Unreleased]
 
+## [4.7.1] - 2026-08-09
+
+### Changed
+
+- **`continue`, `resume`, and `--retry-failed` now inherit the parent session's/wave's tag,
+  instead of dropping it.** `amicus list` now shows a TAG for continuations (they no longer group
+  under `(unattributed)` for `--group-by tag`), and `--tag` is now **rejected** on `continue` and
+  `resume` — the tag can only come from the parent, it cannot be overridden. This deletes a
+  documented limitation, not a bug: `docs/usage.md` carried a paragraph headed "Known limitation: a
+  tag is not inherited", and v4.7.0's own release notes called the gap "future work, not
+  oversights." That limitation is now gone.
+- **`opencode-ai` and `@opencode-ai/sdk` are pinned to exactly `1.18.15`** (previously `^1.2.20` /
+  `^1.1.36`). Dev and CI now run on the same engine version end users resolve, so this is the
+  first release whose test suite actually ran against the engine users get. Honest scope: the pin
+  makes the *resolved* engine a pure function of the amicus version — it does nothing for a user
+  whose installed amicus version hasn't moved, and it does not force any existing npx cache to
+  re-resolve (that mechanism was investigated for #133 and found not to exist).
+
+### Fixed
+
+- **The no-output backstop message now reports what it observed, not what it guessed.** The old
+  three-line message asserted "likely a listed-but-not-serving model or a dead endpoint" with no
+  evidence behind it; it now names only what the deadline mechanism actually saw, and names
+  `AMICUS_NO_OUTPUT_BACKSTOP_MS` as the live governing window only when it is one, calling it out
+  as an overridden default otherwise.
+- **The no-output backstop window now doubles on a Stage-1 retry, clamped to the leg timeout, so
+  retries can now heal a class of no-output failure that previously required a manual rerun.**
+  This is not a fix for the backstop class itself — only Stage-1 bench/critic/lens units retry;
+  judges, chair, chair-repair, and debate legs do not, and can still hit the backstop with no
+  automatic recovery.
+- **`doctor` now reports engine version skew between installs instead of only grading on
+  presence.** A stale npx-cached copy of `opencode-ai` next to a newer global install now surfaces
+  as a WARN.
+- **`npm root -g` now resolves on Windows** (it previously threw `ENOENT`/`EINVAL`, making the
+  global amicus install invisible to `doctor`). This also un-blinds `doctor --fix`'s donor
+  selection, which depends on seeing that global install to pick a healthy engine to copy from.
+- **`npm test` no longer fails intermittently with `ENOENT: … src\__sizecheck_tmp__.js`.**
+  `tests/scripts/check-file-sizes.test.js` writes a real `src/__sizecheck_tmp__.js` and unlinks it a
+  few milliseconds later. It cannot move that fixture to a tmpdir: `checkAllTracked()` filters its
+  input through the anchored `src/**/*.js` include glob and only then resolves against
+  `process.cwd()`, so a tmpdir path is dropped before the read and the test would assert on an empty
+  violation list. Three suites walk `src/` in parallel jest workers, and a directory listing taken
+  while that file existed followed by a read issued after the unlink threw ENOENT — killing
+  `no-phantom-dependencies.test.js` during collection ("Test suite failed to run") on roughly 1 full
+  run in 2, with `cli-template-args.test.js` and `council/degrade-invariant.test.js` exposed
+  identically (both confirmed failing under a reproduction that widens the collision window). All
+  three now read through the new `tests/helpers/read-if-present.js`, which skips a file that vanished
+  mid-walk and still throws on any non-ENOENT failure, so an unreadable source file stays loud.
+  Pre-existing — reproduces at 0fe6128, unrelated to the graphify integration.
+
+### Internal
+
+- **`finalizeSpendForReopen` extracted to `src/sidecar/reopen-spend.js`**, out of
+  `sidecar/continue.js`, to keep that file under the 300-line gate; `resume.js` was already
+  reaching across into `continue.js` for it, so the shared home is the honest one.
+- **Deleted three unreachable helpers from `scripts/validate-docs.js`** (dead code with no call
+  site remaining after earlier `--check` work landed).
+- **Three doc/marker-freshness gates, all jest-enforced — one genuinely new, two hardened.**
+  `tests/docs-command-coverage.test.js` and the anchor-link gate
+  (`tests/docs-council-toc-anchors.test.js`) both already existed and already ran in CI; this
+  branch hardens them (the former now derives its command list from `bin/amicus.js`'s switch
+  instead of hardcoding five entries, the latter generalizes from one file to sixteen). Only the
+  CLAUDE.md AUTO-marker/cross-link freshness gate in this changelog entry's own commit is genuinely
+  new — `generate-docs --check` had never run in CI before — so a stale `CLAUDE.md` can no longer
+  pass CI silently.
+
 ## [4.7.0] - 2026-08-08
 
 **"The count is the count."** Every number Amicus shows you is the number — what a council cost,

package/README.md

@@ -450,7 +450,7 @@ $ amicus status demo123 --json
   "taskId": "demo123",
   "status": "complete",
   "elapsed": "5m 0s",
-  "version": "4.7.0",
+  "version": "4.7.1",
   "model": "google/gemini-2.5-flash",
   "phase": "terminal"
 }

package/docs/configuration.md

@@ -460,6 +460,6 @@ aliases, and council presets carry over untouched.
 | `eslint` ^8.0.0 | Code linting |
 | `lint-staged` ^16.3.2 | Run linters on staged files |
 
-`opencode-ai` (>=1.0.0) is the bundled LLM conversation engine — it is installed automatically as a postinstall step and does not need a separate `npm install`.
+The bundled **`opencode-ai`** engine (pinned to `1.18.15`, matched by `@opencode-ai/sdk`) installs automatically as a normal dependency — you don't install it separately. Its own postinstall lays down the per-platform binaries.
 
 > **Legacy names.** Pre-rebrand `SIDECAR_*` environment variables were removed entirely in v2.0.0 — they are no longer read, with no warning. Rename to the `AMICUS_*` equivalents documented above. See [docs/SHIMS.md](./SHIMS.md) for the full removal record and rename table.

package/docs/council.md

@@ -540,8 +540,8 @@ model to the reliability ledger. Thin CLI wrapper over `tally()` (`src/council/t
 ### Tally-input schema
 
 Claude assembles this file at the end of Stage 2 (the full assembly recipe is in
-[SKILL.md](../skills/second-opinion/SKILL.md#stage-2--cross-review), under "Stage-2 → tally
-assembly recipe"). It needs **all five top-level keys** — `tally()` throws
+[SKILL.md](../skills/second-opinion/SKILL.md#the-engine-run--stages-13-plus-the-stage-5-artifacts),
+under "Stage-2 → tally assembly recipe"). It needs **all five top-level keys** — `tally()` throws
 `Cannot read properties of undefined (reading 'map')` if `meta` or `findings` is missing:
 
 | Field | Type | Meaning |

package/docs/testing.md

@@ -523,7 +523,7 @@ Complete mapping of test files to their targets and focus areas.
 | `evals/tests/result_writer.test.js` | Result output | Summary formatting, file writing |
 | `scripts/check-secrets.test.js` | Secret detection | Pattern matching, allowlist, multi-secret |
 | `scripts/check-file-sizes.test.js` | File size limits | Line counting, batch checking |
-| `scripts/validate-docs.test.js` | Doc drift detection | Section extraction, drift comparison, staged file check |
+| `scripts/validate-docs.test.js` | Doc drift detection | Staged file check |
 | `helpers/cdp-client.test.js` | CDP helper | Mock HTTP+WebSocket CDP server, factory methods |
 | `electron-headless-mode.test.js` | Electron headless | Source-level verify `AMICUS_HEADLESS_TEST` guard |
 | `cli-headless-e2e.integration.test.js` | CLI E2E (real LLM) | `start --no-ui`, `list`, `read`, `read --metadata` |

package/docs/troubleshooting.md

@@ -233,13 +233,15 @@ For full headless configuration, see [docs/configuration.md](./configuration.md)
 
 ## Headless Leg Fails with `NO_OUTPUT_BACKSTOP`
 
-**Symptom:** A headless leg (`amicus start --no-ui`, or one leg of a `fanout`/council run) fails with an error starting `NO_OUTPUT_BACKSTOP: model produced no output, reasoning, or tool calls in Ns`.
+**Symptom:** A headless leg (`amicus start --no-ui`, or one leg of a `fanout`/council run) fails with an error starting `NO_OUTPUT_BACKSTOP: no output, reasoning, or tool calls in Ns — the AMICUS_NO_OUTPUT_BACKSTOP_MS window (0 disables)`. You may instead see `...in Ns — a caller-set window overriding the AMICUS_NO_OUTPUT_BACKSTOP_MS default` — this covers two different cases with the same wording: a Stage-1 retry (its window is the resolved `AMICUS_NO_OUTPUT_BACKSTOP_MS` value **doubled**, so a 120 s default reads `240s` on the retry) and the `amicus models --check --live` probe (a fixed, non-tunable `30s` — see below). Both are "caller-set" in the sense that the specific window wasn't read live from the env var at that call, but only the retry case is actually governed by it.
 
-**Cause:** The model endpoint accepted the request but produced nothing — no output, reasoning, or tool calls — for the entire backstop window (120 s by default). This is the "accepted but not serving" class: usually a dead or misconfigured endpoint, or a catalog-listed model that's no longer actually being served upstream.
+**Cause:** The mechanism only knows that the deadline passed with no substantive activity — no output, reasoning, or tool calls — for the backstop window (120 s by default for an ordinary leg). It does **not** know *why*. Do not read this as "the endpoint is dead" or "the model isn't being served" — the message deliberately stops short of that claim, because at one of its two firing sites the backstop can win the race before the prompt send even resolves, so acceptance itself was never observed. Treat `NO_OUTPUT_BACKSTOP` as "silence past the deadline," not a diagnosis.
 
-**Confirm:** `amicus models --check` — audits your configured aliases against the live catalog and flags drift/staleness. A model that still resolves locally but has quietly been retired upstream is exactly this failure mode, but a static audit only compares against the catalog's *listing* — it can't tell you whether a still-listed model actually answers. For that, run `amicus models --check --live` on demand: it sends one tiny real request to every stored alias and reports `SERVED` / `SILENT` / `ERROR` per alias, where `SILENT` (`accepted-but-silent`) is this exact `NO_OUTPUT_BACKSTOP` failure, caught deliberately instead of by accident. It spends real money (one tiny leg per stored alias) — see [docs/usage.md § `amicus models`](./usage.md#amicus-models--the-model-catalog) for cost, scope, and exit-code details.
+**Lesson from #133:** an earlier version of this message *did* guess a cause ("likely a listed-but-not-serving model or a dead endpoint"), and that guess sent 30 minutes of debugging at model ids and API keys on a real incident. The actual cause was an OpenCode engine version skew between the npx-cached copy and the global install — sitting the whole time in `~/.local/share/opencode/log/opencode.log`. **Before chasing model/endpoint theories, check that log for the session's real error.**
 
-**Fix:** Check the alias's target (`amicus models --search <term>` to find the current id, then re-point the alias) — this is the common case. Raise `AMICUS_NO_OUTPUT_BACKSTOP_MS` only if a model legitimately needs more than 120 s to produce its first token; see [docs/configuration.md § Headless Poller Tuning](./configuration.md#headless-poller-tuning).
+**Confirm:** `amicus models --check` — audits your configured aliases against the live catalog and flags drift/staleness. A model that still resolves locally but has quietly been retired upstream is one possible explanation, but a static audit only compares against the catalog's *listing* — it can't tell you whether a still-listed model actually answers. For that, run `amicus models --check --live` on demand: it sends one tiny real request to every stored alias and reports `SERVED` / `SILENT` / `ERROR` per alias, where `SILENT` (`accepted-but-silent`) is this exact `NO_OUTPUT_BACKSTOP` failure, caught deliberately instead of by accident. It spends real money (one tiny leg per stored alias) — see [docs/usage.md § `amicus models`](./usage.md#amicus-models--the-model-catalog) for cost, scope, and exit-code details.
+
+**Fix:** Check the `~/.local/share/opencode/log/opencode.log` for the session's real error first (see #133 above). Then check the alias's target (`amicus models --search <term>` to find the current id, then re-point the alias) — a stale alias is a common case, but not the only one. If the failing leg was a Stage-1 retry (the window read `240s`, or generally double your configured/default value), `AMICUS_NO_OUTPUT_BACKSTOP_MS` **is** the lever — raising it raises both the first attempt's window and the retry's doubled one, unless your `--timeout` is low enough that the doubled window is clamped to the leg timeout. On an ordinary (non-retry) leg, raise it only if a model legitimately needs more than 120 s to produce its first token. The live probe's fixed 30 s window is the one case the env var genuinely cannot touch. See [docs/configuration.md § Headless Poller Tuning](./configuration.md#headless-poller-tuning).
 
 ---
 

package/docs/usage.md

@@ -487,14 +487,18 @@ written at MCP launch time, or falls back to the portion of `briefing-stage1.md`
 MCP-only, since the CLI never lists a council row to search in the first place. A bare `--search`
 with no value is a usage error on the CLI. Tag itself is set at launch with `--tag <t>` on
 `start`/`fanout`/`council run` (see those sections above), and is also a dimension for
-`amicus spend --group-by tag`.
-
-**Known limitation: a tag is not inherited.** `--tag` only ever gets written at launch. `amicus
-continue` and `amicus resume` write their spend rows with no tag, and a `fanout --retry-failed`
-wave does not carry the original wave's tag either (`--tag` combined with `--retry-failed` is
-rejected as a usage error). Since the spend ledger writes `tag: null` whenever none was set, those
-rows group under `(unattributed)` in `amicus spend --group-by tag` rather than under the tag their
-lineage started with.
+`amicus spend --group-by tag`. `amicus continue` and `amicus resume` don't take a `--tag` of
+their own — they automatically inherit the parent session's tag (see below).
+
+**Tag inheritance.** `amicus continue` and `amicus resume` carry the parent session's tag forward
+onto the new/reopened session's metadata and spend row, with no `--tag` flag needed — resume reuses
+the parent's own session directory, and continue copies the tag onto the new session it creates, so
+a multi-hop `continue` chain keeps the same tag at every depth. A `fanout --retry-failed` wave
+likewise replays the original wave's tag automatically. Because the tag in each of these cases
+comes from the session/wave being reopened rather than a fresh launch, `--tag` is rejected as a
+usage error when combined with `continue`, `resume`, or `--retry-failed` — there is nothing new to
+set. An untagged parent still leaves the key absent (not `null`) on the new metadata, and its spend
+row still groups under `(unattributed)`, exactly as an untagged `start`/`fanout` would.
 
 **`amicus status <id>` output.** Human-readable:
 
@@ -514,7 +518,7 @@ $ amicus status demo123 --json
   "taskId": "demo123",
   "status": "complete",
   "elapsed": "5m 0s",
-  "version": "4.7.0",
+  "version": "4.7.1",
   "model": "google/gemini-2.5-flash",
   "phase": "terminal"
 }
@@ -574,7 +578,7 @@ Runs every check below, in order, and prints a ✓/⚠/✗ line for each plus a
 | `aliases` | Your configured aliases still resolve against the catalog | warn |
 | `anthropic-base-url` | `ANTHROPIC_BASE_URL` isn't host-form (host-form 404s every direct-Anthropic leg unless normalized) | warn |
 | `opencode-bin` | The OpenCode engine binary is on `PATH` | error |
-| `engine-mcp` | The engine copy `npx -y amicus@latest mcp` would actually launch (catches a broken npx-cache copy a healthy local install would hide) | warn (error only if there's exactly one npx-cache copy and it's broken) |
+| `engine-mcp` | The engine copy `npx -y amicus@latest mcp` would actually launch (catches a broken npx-cache copy a healthy local install would hide, and a version-skewed one — present but the wrong opencode-ai release vs. the global install, #133) | warn (error only if there's exactly one npx-cache copy and it's broken; also warns, never errors, on engine version skew between the npx copies and the global install) |
 | `electron` | Electron (the interactive GUI) is installed | warn — headless still works |
 | `skills` | Both skills exist under `~/.claude/skills/` | warn |
 | `mcp` | Amicus is registered as an MCP server in Claude Code | warn |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "4.7.0",
+  "version": "4.7.1",
   "mcpName": "io.github.BourbonDog/amicus",
   "description": "Multi-model LLM Council + parallel AI window for Claude Code. Run structured council reviews across Gemini, GPT, DeepSeek and more — or fork a conversation to any model and fold the results back.",
   "keywords": [
@@ -68,6 +68,7 @@
     "generate-docs:check": "node scripts/generate-docs.js --check",
     "validate-docs": "node scripts/validate-docs.js --full",
     "setup-hooks": "node scripts/setup-hooks.js",
+    "graphify:index": "graphify extract . --backend claude-cli",
     "check:secrets": "node scripts/check-secrets.js --all",
     "check:sizes": "node scripts/check-file-sizes.js --all",
     "check:tarball": "node scripts/check-tarball-lifecycle.js"
@@ -75,10 +76,10 @@
   "dependencies": {
     "@electron/get": "^5.0.0",
     "@modelcontextprotocol/sdk": "^1.27.0",
-    "@opencode-ai/sdk": "^1.1.36",
+    "@opencode-ai/sdk": "1.18.15",
     "dotenv": "^17.2.3",
     "extract-zip": "^2.0.1",
-    "opencode-ai": "^1.2.20",
+    "opencode-ai": "1.18.15",
     "tiktoken": "^1.0.0",
     "update-notifier": "^7.3.1",
     "zod": "^3.0.0"

package/scripts/postinstall.js

@@ -110,9 +110,12 @@ async function provisionElectron(deps = {}) {
  * path.
  *
  * Hook setup still needs to happen for devs, so we run setup-hooks.js here.
- * It is a no-op for consumers: setup-hooks.js exits 0 outside a git checkout
- * (the published tarball / github: export has no .git), so this changes
- * nothing for end users while keeping `npm install` wiring hooks for devs.
+ * It is a no-op for consumers, but NOT merely because the published tarball
+ * has no .git: git resolves a repository by walking UP, so during a consumer's
+ * `npm install amicus` (cwd = node_modules/amicus) it finds the CONSUMER'S
+ * .git. setup-hooks.js is what makes this safe — it configures hooks only when
+ * git's toplevel IS the amicus package root, so a dependency install can never
+ * repoint someone else's core.hooksPath. See its docstring for the full story.
  *
  * Best-effort and self-contained: never throws (a hook-setup failure must
  * never roll back the install), so it is safe to call before the optional

package/scripts/setup-hooks.js

@@ -21,20 +21,66 @@
  *
  *   npm run setup-hooks      # or: node scripts/setup-hooks.js
  *
+ * ONLY EVER CONFIGURES THE AMICUS CHECKOUT ITSELF.
+ * ------------------------------------------------
+ * "Are we in a git checkout?" is NOT a sufficient guard, because git resolves
+ * a repository by walking UP the directory tree. When a consumer runs
+ * `npm install amicus` inside their own repo, npm runs this postinstall with
+ * cwd = <consumer>/node_modules/amicus — where `git rev-parse` finds the
+ * CONSUMER'S .git and happily reports success. Writing core.hooksPath there
+ * pointed their repository at a .husky directory that does not exist (it is
+ * not in package.json "files", so it never ships), which silently disabled
+ * every hook in their .git/hooks — no error, no warning, `git commit` just
+ * stops running them. The damage also outlived a failed install: npm rolls
+ * back node_modules, but not writes to someone else's .git/config.
+ *
+ * So the guard asks `git rev-parse --show-prefix` from the package root. That
+ * prints the path of the current directory RELATIVE to the top of the work
+ * tree, so it is empty exactly when the package root IS the repository root,
+ * and non-empty ("node_modules/amicus/") when amicus merely sits inside
+ * someone else's checkout. A dependency install, a vendored copy and a global
+ * install all land below their enclosing repo's root; the dev checkout — and
+ * every linked worktree of it, whose root is the worktree — comes back empty.
+ *
+ * DO NOT "simplify" this into comparing `--show-toplevel` against the package
+ * root as strings. That was the first attempt and it broke on Windows CI: the
+ * runners' %TEMP% is an 8.3 short path (C:\Users\RUNNER~1\...), Node's
+ * fs.realpathSync PRESERVES short components while git always reports the long
+ * form, so the two spellings of one directory never compared equal and the
+ * guard refused to configure a legitimate checkout. Case, separators, symlinks
+ * and 8.3 are four different ways for equal paths to spell differently; asking
+ * git to compute the relationship sidesteps all of them at once.
+ *
+ * Every git call is anchored at the package root rather than process.cwd() for
+ * the same reason: what gets configured must depend on where amicus lives, not
+ * on where the script happened to be invoked from.
+ *
  * Safe to run anywhere: exits 0 outside a git checkout (npm tarball
  * installs, exported archives) and never fails the install.
  */
 
 const { execFileSync } = require('node:child_process');
+const path = require('node:path');
+
+/** This package's root — the parent of the scripts/ directory holding this file. */
+const PKG_ROOT = path.resolve(__dirname, '..');
 
 function git(...args) {
-  return execFileSync('git', args, { encoding: 'utf-8' }).trim();
+  return execFileSync('git', args, { cwd: PKG_ROOT, encoding: 'utf-8' }).trim();
 }
 
+let prefix;
 try {
-  git('rev-parse', '--git-dir');
+  prefix = git('rev-parse', '--show-prefix');
 } catch {
-  process.exit(0); // not a git checkout — nothing to configure
+  process.exit(0); // not a git checkout (or a bare repo) — nothing to configure
+}
+
+if (prefix !== '') {
+  // amicus is nested inside someone else's repository — a dependency install,
+  // a vendored copy, a global install under a tracked directory. Their hooks
+  // are none of our business. Silent: this is the normal consumer path.
+  process.exit(0);
 }
 
 try {

package/skills/sidecar/SKILL.md

@@ -380,7 +380,9 @@ amicus list --json         # Output as JSON
 - `--cwd <path>`: Project directory (default: current directory)
 
 Rows show the `--tag <t>` label set at launch time (`start`/`fanout`/`council run` —
-not a `list` flag itself); untagged sessions show blank.
+not a `list` flag itself), or inherited automatically from the parent session on
+`continue`/`resume` (neither accepts its own `--tag` — the tag comes from the
+parent, so there's nothing new to set); untagged sessions show blank.
 
 ### Resume a Sidecar
 

package/src/cli-handlers-resume-continue.js

@@ -21,6 +21,17 @@ const { GATEWAY_MODES } = require('./utils/model-descriptor');
  */
 async function handleResume(args) {
   const useJson = !!args.json;
+  // v4.7.1 Task 7 (R-D): --tag parses today only because getKnownFlags()
+  // unions every usage block's flags (fanout's/start's/council run's), and is
+  // then read by nobody here — resume reuses the parent session's own dir, so
+  // its tag is already inherited (E-5a) with nothing left to set. Mirrors
+  // handleFanout's --tag/--retry-failed rejection shape (cli-handlers-fanout.js:27-29).
+  if (args.tag !== undefined) {
+    process.exit(failJson(useJson, {
+      code: ERROR_CODES.BAD_ARGS,
+      message: 'Error: --tag is not supported on resume — the tag is inherited from the parent session',
+    }));
+  }
   const taskId = requireValidTaskId(args, useJson, 'resume', 'Usage: amicus resume <task_id>');
   requireNoUiForJson(args, useJson);
 
@@ -51,6 +62,15 @@ async function handleResume(args) {
  */
 async function handleContinue(args) {
   const useJson = !!args.json;
+  // v4.7.1 Task 7 (R-D): same rationale as handleResume above — a continuation
+  // inherits the parent session's tag onto its own metadata.json (createContinueSessionMetadata),
+  // so a user-supplied --tag here would silently be ignored rather than applied.
+  if (args.tag !== undefined) {
+    process.exit(failJson(useJson, {
+      code: ERROR_CODES.BAD_ARGS,
+      message: 'Error: --tag is not supported on continue — the tag is inherited from the parent session',
+    }));
+  }
   const taskId = requireValidTaskId(args, useJson, 'continue', 'Usage: amicus continue <task_id> --prompt "..."');
 
   // BL-1: accept --prompt-file (XOR --prompt) so the MCP handler can pass a long

package/src/council/run-launch.js

@@ -64,7 +64,7 @@ function createLaunchers(deps = {}) {
    * @param {{models: string[], prompt: string, project: string, waveId: string,
    *   timeout?: number, gateway?: string, noValidateModel?: boolean, agent?: string,
    *   councilRunId?: string, councilName?: string, tag?: string, fallback?: object,
-   *   catalog?: Array}} opts
+   *   catalog?: Array, noOutputBackstopMs?: number}} opts
    *   councilRunId/councilName (v4.3 Task 3, spec §7.2) are additive attribution
    *   ids forwarded verbatim into the runFanout call so it can stamp them onto
    *   every leg. tag (v4.7 F8 D16) rides the same forward — every call site
@@ -72,6 +72,9 @@ function createLaunchers(deps = {}) {
    *   fallback/catalog (v4.3 Task 18, spec §6.2) are likewise
    *   additive/opt-in — omitted by callers that must never substitute (the
    *   chair, debate legs); run-stages.js's Stage-1/Stage-2 launches pass them.
+   *   noOutputBackstopMs (Task 5, #129) is opt-in and spread-guarded on
+   *   Number.isFinite (0 is a valid disable value); only run-retry.js sets it,
+   *   to escalate the window on a Stage-1 retry.
    * @returns {Promise<{wave: object|null, exitCode: number}>}
    */
   async function launchWave(opts) {
@@ -118,6 +121,14 @@ function createLaunchers(deps = {}) {
       // undefined when no --tag, so stampLegAttribution's `if (options.tag)`
       // guard (fanout-wave-io.js) simply no-ops, byte-identical to today.
       tag: opts.tag,
+      // Task 5 (#129): spread-guarded on Number.isFinite, NOT on truthiness —
+      // an explicit 0 is this knob's documented disable hatch
+      // (no-output-backstop.js:13-15) and a truthiness guard would silently
+      // drop it. Guarding at all — rather than a plain
+      // `noOutputBackstopMs: opts.noOutputBackstopMs` — keeps the transport
+      // call key-identical for run-stage1-launch / run-stage2 / run-chair /
+      // run-debate, none of which set it.
+      ...(Number.isFinite(opts.noOutputBackstopMs) ? { noOutputBackstopMs: opts.noOutputBackstopMs } : {}),
       // v4.3 Task 18 (spec §6.2): additive/opt-in. Callers that must never
       // substitute (run-chair.js, run-debate.js) simply omit these — runLeg's
       // fallback path only activates when `fallback.enabled` is true.

package/src/council/run-retry.js

@@ -17,6 +17,7 @@
 const briefings = require('./briefings');
 const { materializeReviews, isAbortExit } = require('./run-launch');
 const runState = require('./run-state');
+const { resolveNoOutputBackstopMs } = require('../utils/no-output-backstop');
 const { waveStillDeadNote, srcLegStillDeadNote, retryLegStillDeadNote, missingLegStillDeadNote }
   = require('./run-retry-notes');
 
@@ -143,6 +144,16 @@ async function retryStage1Losses(ctx, { deadWaves = [], deadLegs = [], counts =
   const out = { aborted: null, recoveredLegs: [], stillDeadNotes: [],
     stillDeadWaves: [], stillDeadLegs: [], skippedDeadWaves: [], skippedDeadLegs: [],
     stillDeadRetryLegs: [] };
+  // Task 5 (#129): SL-2 retries the SAME model under the SAME conditions, so a
+  // latency failure is structurally unhealable. Double the window, clamped to
+  // the leg timeout so the failure CLASS stays NO_OUTPUT_BACKSTOP rather than
+  // silently becoming an ordinary timeout at a low --timeout. 2*0 === 0 keeps
+  // the disable hatch. (o.timeout || 15) * 60 * 1000 mirrors fanout.js:254.
+  const legTimeoutMs = (o.timeout || 15) * 60 * 1000;
+  const escalatedBackstopMs = Math.min(
+    2 * (Number.isFinite(o.noOutputBackstopMs) ? o.noOutputBackstopMs : resolveNoOutputBackstopMs()),
+    legTimeoutMs,
+  );
 
   for (const unit of groupStage1Losses(o, deadWaves, deadLegs)) {
     // Task-4 review hardening: a unit this pass cannot even ATTEMPT — an
@@ -171,7 +182,8 @@ async function retryStage1Losses(ctx, { deadWaves = [], deadLegs = [], counts =
       councilRunId: o.runId, councilName: o.councilName,
       tag: o.tag, // v4.7 F8 D16: rides the same forward as councilRunId/councilName.
       fallback: o.fallback, catalog: o.catalog,
-      waveId: unit.waveId, retryOfWaveId: unit.retryOfWaveId, prompt: briefingFor(o, unit) };
+      waveId: unit.waveId, retryOfWaveId: unit.retryOfWaveId, prompt: briefingFor(o, unit),
+      noOutputBackstopMs: escalatedBackstopMs };
     // Dispatch by UNIT TYPE, not model count (spec §4: bench is always a wave —
     // even down to its last surviving seat — critic/lens are always solos).
     // A model-count proxy (`models.length === 1`) is wrong for a bench unit

package/src/headless.js

@@ -154,6 +154,58 @@ function withTimeout(promise, ms, label) {
   ]);
 }
 
+/**
+ * Task 6 (#129, #133): build the NO_OUTPUT_BACKSTOP reason string. Report
+ * ONLY what the mechanism observed — a deadline passed with no substantive
+ * activity (output/reasoning/tool calls) — never a cause. At the pre-send
+ * firing site (runHeadless, ~:506-518) the backstop can win the race against
+ * sendPromptAsync before the send ever resolves, so "the endpoint accepted
+ * the request" is not even something that site observed. The previous text
+ * asserted "likely a listed-but-not-serving model or a dead endpoint" — a
+ * canned guess with no evidence gate — which sent 30 minutes of #133's
+ * debugging at model ids and API keys while the real cause (an opencode
+ * engine version skew) sat in ~/.local/share/opencode/log/opencode.log the
+ * whole time.
+ *
+ * `fromEnv` distinguishes two ways `ms` was decided, NOT whether
+ * AMICUS_NO_OUTPUT_BACKSTOP_MS is relevant — it is relevant on both branches:
+ *   - fromEnv=true: `ms` IS the live env-resolved value (or its documented
+ *     default) — the message says so directly, "(0 disables)" included,
+ *     because raising the env var changes exactly this window.
+ *   - fromEnv=false: `ms` arrived as a direct, caller-set numeric option.
+ *     Task 6 review (Important finding): this is NOT synonymous with "the
+ *     env var doesn't apply" — src/council/run-retry.js:154 computes a
+ *     Stage-1 retry's escalated window as
+ *     `2 * (Number.isFinite(o.noOutputBackstopMs) ? o.noOutputBackstopMs :
+ *     resolveNoOutputBackstopMs())` and forwards that as a direct
+ *     `noOutputBackstopMs` (line 186) — so a 240s retry-fired backstop is
+ *     "caller-set" by this predicate while still being *derived from* the
+ *     env default doubled. Only src/sidecar/models-probe.js:79's hardcoded,
+ *     non-tunable 30s (PROBE_WINDOW_MS; docs/usage.md:406 promises it's "not
+ *     tunable") is truly independent of the env var. Because a real
+ *     `fromEnv` flag distinguishing those two cases would have to ride the
+ *     same value through src/sidecar/fanout.js, which is line-locked at
+ *     EXACTLY 300/300 this release, the caller-set branch instead names the
+ *     var as something this window *overrides* rather than either claiming
+ *     it governs (false on the probe) or omitting it (false/unhelpful on the
+ *     retry) — true on both, and still points a user at the remedy.
+ *
+ * Kept module-scope and pure (not a closure over runHeadless locals) so it
+ * can be asserted on directly in tests without driving the poll loop; the
+ * `noOutputBackstopReason` closure inside runHeadless just forwards to this
+ * with the per-run `noOutputBackstopMs`/`backstopFromEnv` values, so the two
+ * firing sites there stay identical to what's tested here.
+ * @param {{ms: number, fromEnv: boolean}} args
+ * @returns {string}
+ */
+function formatNoOutputBackstopReason({ ms, fromEnv }) {
+  return 'NO_OUTPUT_BACKSTOP: no output, reasoning, or tool calls in '
+    + `${Math.round(ms / 1000)}s — `
+    + (fromEnv
+      ? 'the AMICUS_NO_OUTPUT_BACKSTOP_MS window (0 disables)'
+      : 'a caller-set window overriding the AMICUS_NO_OUTPUT_BACKSTOP_MS default');
+}
+
 /**
  * Wait for the OpenCode server to be ready using SDK health check
  */
@@ -473,16 +525,26 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
     // deadline `nowMs >= deadline` can never satisfy — the backstop would
     // silently never fire. Finite zero (the documented explicit-disable
     // value) still takes the direct branch: Number.isFinite(0) === true.
-    const noOutputBackstopMs = Number.isFinite(options.noOutputBackstopMs)
-      ? options.noOutputBackstopMs : resolveNoOutputBackstopMs(options._env);
+    // Capture the source-of-truth predicate ONCE and reuse it (do not call
+    // Number.isFinite a second time below) — `backstopFromEnv` is just its
+    // complement: options.noOutputBackstopMs is a direct, caller-set value
+    // exactly when Number.isFinite is true, so the window came from
+    // resolveNoOutputBackstopMs's env-resolution seam exactly when it's false.
+    // Reused both to pick noOutputBackstopMs and to decide whether the reason
+    // string below may name the env var, so the two can never drift apart.
+    const backstopFromEnv = !Number.isFinite(options.noOutputBackstopMs);
+    const noOutputBackstopMs = backstopFromEnv
+      ? resolveNoOutputBackstopMs(options._env) : options.noOutputBackstopMs;
     const noOutputBackstop = createNoOutputBackstop({ ms: noOutputBackstopMs, startedAt: Date.now() });
     let backstopFired = false;
     // Single source for the reason string so the pre-send firing site below and
     // the per-poll firing site further down (still ticking the SAME instance)
-    // can never drift apart.
-    const noOutputBackstopReason = () => 'NO_OUTPUT_BACKSTOP: model produced no '
-      + `output, reasoning, or tool calls in ${Math.round(noOutputBackstopMs / 1000)}s `
-      + '— likely a listed-but-not-serving model or a dead endpoint';
+    // can never drift apart. Forwards to the module-scope, pure
+    // formatNoOutputBackstopReason (below/exported) so tests can assert on the
+    // string shape directly without driving the whole poll loop.
+    const noOutputBackstopReason = () => formatNoOutputBackstopReason({
+      ms: noOutputBackstopMs, fromEnv: backstopFromEnv,
+    });
 
     // Send prompt asynchronously (returns immediately, we poll for results) —
     // bounded by the backstop: an endpoint that accepts but never answers must
@@ -1413,6 +1475,7 @@ module.exports = {
   extractSummary,
   findTrailingFoldMarker,
   formatFoldOutput,
+  formatNoOutputBackstopReason,
   DEFAULT_TIMEOUT,
   FOLD_MARKER,
   COMPLETE_MARKER,

package/src/sidecar/continue.js

@@ -88,7 +88,7 @@ Build on the previous sidecar's findings. The user wants to continue or extend t
 
 /** Create session metadata for continuation */
 function createContinueSessionMetadata(taskId, project, options, oldTaskId) {
-  const { model, briefing, headless, agent, gateway, resolutionVersion } = options;
+  const { model, briefing, headless, agent, gateway, resolutionVersion, tag } = options;
 
   const sessionDir = SessionPaths.sessionDir(project, taskId);
   fs.mkdirSync(sessionDir, { recursive: true });
@@ -102,7 +102,11 @@ function createContinueSessionMetadata(taskId, project, options, oldTaskId) {
     agent: agent || (headless ? 'build' : 'chat'),
     status: 'running',
     createdAt: new Date().toISOString(),
-    continuesFrom: oldTaskId
+    continuesFrom: oldTaskId,
+    // v4.7.1 Task 7 (D13): absent-not-null, same idiom as start-metadata.js:50
+    // — a continuation inherits the parent's tag so a continue chain never
+    // scatters into `(unattributed)`.
+    ...(tag ? { tag } : {}),
   };
   // #61 Task 5.2 (best-effort provenance): only present when THIS continue
   // call freshly routed an explicit --model through the gateway router — the
@@ -116,26 +120,6 @@ function createContinueSessionMetadata(taskId, project, options, oldTaskId) {
   return sessionDir;
 }
 
-/**
- * Resolve a reopened session's usage, write it onto metadata, and append one
- * attributed ledger row. Mirrors start.js's finalize (the only sites that
- * dropped usage - BACKLOG.md:280). Best-effort ledger append; never throws.
- * @returns {{usage: object|null}}
- */
-function finalizeSpendForReopen({ taskId, model, mode, op, result, status, project, metadata }, ctx = {}) {
-  const { resolveUsage } = require('../utils/pricing');
-  const usage = result && result.usage ? resolveUsage({ model, usageTotals: result.usage }) : null;
-  if (usage) {
-    metadata.usage = usage; // buildRunResult surfaces metadata.usage into the --json doc for free
-    try {
-      const { appendSpend } = require('../utils/spend-ledger');
-      const gateway = metadata.gateway || (String(model).startsWith('openrouter/') ? 'openrouter' : 'direct');
-      appendSpend({ taskId, model, mode, usage, op, status, project, gateway }, ctx);
-    } catch { /* best-effort */ }
-  }
-  return { usage };
-}
-
 /**
  * Continue from a previous sidecar session - Spec Reference: §4.4, §8.5
  * @returns {Promise<number>} process exit code
@@ -196,6 +180,7 @@ async function continueSidecar(options) {
 
   const sessionDir = createContinueSessionMetadata(newTaskId, project, {
     model, briefing, headless, agent: effectiveAgent, gateway, resolutionVersion,
+    tag: oldMetadata.tag, // v4.7.1 Task 7: inherit the parent's tag (absent if the parent had none).
   }, oldTaskId);
 
   // Lock the NEW continuation session dir too — not just the previous one — so a
@@ -270,6 +255,7 @@ async function continueSidecar(options) {
   // ledger row (status: statusFromResult, matching start.js — not terminal.status).
   {
     const { statusFromResult } = require('../utils/result-schema');
+    const { finalizeSpendForReopen } = require('./reopen-spend');
     const reloaded = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
     const { usage } = finalizeSpendForReopen({
       taskId: newTaskId, model, mode: headless ? 'headless' : 'interactive',
@@ -292,6 +278,5 @@ module.exports = {
   loadPreviousSession,
   buildContinuationContext,
   createContinueSessionMetadata,
-  finalizeSpendForReopen,
   continueSidecar
 };

package/src/sidecar/fanout-retry.js

@@ -73,7 +73,10 @@ function buildRetryPlan(origWaveId, project, { models } = {}) {
     } catch { /* legacy leg — fall back to briefing.md at launch time */ }
     eligible.push({ legId, model, systemPrompt, userMessage, hadSavedContext });
   }
-  return { eligible };
+  // waveMeta has been read since :51 but was discarded; retryFailedWave needs
+  // the tag BEFORE it builds fanoutOpts, and its own origMeta re-read at :176
+  // runs after runFanoutImpl at :153 — too late to influence the launch.
+  return { eligible, tag: waveMeta.tag };
 }
 
 /**
@@ -121,7 +124,7 @@ async function retryFailedWave(origWaveId, project, opts = {}) {
         // --json caller's stdout stays machine-parseable either way.
         const noopDoc = {
           ...buildWaveResult({ waveId: origWaveId, legs: [], status: 'complete' }),
-          retryOf: origWaveId, effective: [], note: 'no failed legs',
+          retryOf: origWaveId, effective: [], note: 'no failed legs', tag: plan.tag,
         };
         process.stdout.write(JSON.stringify(noopDoc, null, 2) + '\n');
       } else {
@@ -148,7 +151,16 @@ async function retryFailedWave(origWaveId, project, opts = {}) {
   // expects (parseModelsList/validateFanoutModels) — an array silently fails
   // every leg pre-flight (BAD_ARGS), matching run-launch.js:41's precedent.
   // Strip our own injection key so it is never forwarded.
-  const fanoutOpts = { ...opts, models: models.join(','), prompt: briefing, project, waveId: newWaveId, retryContexts, retryOfWaveId: origWaveId };
+  const fanoutOpts = {
+    ...opts, models: models.join(','), prompt: briefing, project, waveId: newWaveId, retryContexts, retryOfWaveId: origWaveId,
+    // v4.7.1 Task 8: inherit the ORIGINAL wave's tag — sourced from disk
+    // (plan.tag, off waveMeta) never from opts.tag/args.tag. This is placed
+    // AFTER the `...opts` spread so it wins even if a caller's opts somehow
+    // carried a tag (the CLI itself already rejects --tag + --retry-failed
+    // upstream in cli-handlers-fanout.js). Absent-not-null idiom, matching
+    // fanout.js:152's `...(options.pack ? {...} : {})`.
+    ...(plan.tag ? { tag: plan.tag } : {}),
+  };
   delete fanoutOpts.runFanout;
   const { wave, exitCode } = await runFanoutImpl(fanoutOpts);
 

package/src/sidecar/reopen-spend.js

@@ -0,0 +1,32 @@
+/**
+ * @module sidecar/reopen-spend
+ * Spend finalization for a REOPENED session (continue/resume). Split out of
+ * sidecar/continue.js to keep that file under the 300-line gate; resume.js was
+ * already reaching across for it, so the shared home is the honest one.
+ */
+
+'use strict';
+
+/**
+ * Resolve a reopened session's usage, write it onto metadata, and append one
+ * attributed ledger row. Mirrors start.js's finalize (the only sites that
+ * dropped usage - BACKLOG.md:280). Best-effort ledger append; never throws.
+ * @returns {{usage: object|null}}
+ */
+function finalizeSpendForReopen({ taskId, model, mode, op, result, status, project, metadata }, ctx = {}) {
+  const { resolveUsage } = require('../utils/pricing');
+  const usage = result && result.usage ? resolveUsage({ model, usageTotals: result.usage }) : null;
+  if (usage) {
+    metadata.usage = usage; // buildRunResult surfaces metadata.usage into the --json doc for free
+    try {
+      const { appendSpend } = require('../utils/spend-ledger');
+      const gateway = metadata.gateway || (String(model).startsWith('openrouter/') ? 'openrouter' : 'direct');
+      // v4.7.1 Task 7 D16: null-not-absent, the OPPOSITE convention from
+      // metadata.tag's absent-not-null (D13) — same `|| null` idiom as start.js:237.
+      appendSpend({ taskId, model, mode, usage, op, status, project, gateway, tag: metadata.tag || null }, ctx);
+    } catch { /* best-effort */ }
+  }
+  return { usage };
+}
+
+module.exports = { finalizeSpendForReopen };

package/src/sidecar/resume.js

@@ -251,7 +251,7 @@ async function resumeSidecar(options) {
     // v4.3: attribute resume spend (C9/E4). Reload metadata, write usage + append
     // a ledger row (status: statusFromResult, matching start.js — not terminal.status).
     {
-      const { finalizeSpendForReopen } = require('./continue');
+      const { finalizeSpendForReopen } = require('./reopen-spend');
       const { statusFromResult } = require('../utils/result-schema');
       const reloaded = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
       const { usage } = finalizeSpendForReopen({

package/src/utils/doctor-engine-check.js

@@ -48,6 +48,38 @@ function evaluateEngineInstalls(d) {
 
   const broken = npxCopies.filter((i) => !i.engineOk);
   if (broken.length === 0) {
+    // Version skew (#133): a PRESENT engine can still be the wrong one. The
+    // npx copies and the global install resolve independently and at different
+    // times, and two versions writing one shared opencode.db is what produced
+    // #133's SQLiteError. Compare npx against global ONLY — a genuine source
+    // checkout's engine legitimately differs, so including it would fire red
+    // on every developer machine and in CI (E-1c). Unresolved versions never
+    // signal skew; absence of evidence is not evidence.
+    // WARN, never ERROR: doctor --fix has no skew branch, so an error would be
+    // unfixable, and this file already downgrades to warn at the ambiguous-npx
+    // branch below whenever the copy npx will select is ambiguous.
+    //
+    // Review round 2, finding 1: `kind === 'global'` alone is NOT the whole
+    // baseline. On the documented end-user invocation — `amicus doctor` run
+    // from the globally-installed copy — the running process IS the global
+    // install, so engine-install-scan.js's own dedup drops the separate
+    // `global` record and only `kind:'running'` survives, carrying
+    // `isGlobal: true` instead (see scanEngineInstalls). Without the
+    // `|| i.isGlobal` clause, the skew check was structurally unable to fire
+    // for exactly the users who filed #133. A TRUE source checkout (running,
+    // no isGlobal) is still excluded, as intended.
+    const globalV = (installs.find((i) => i.kind === 'global' || i.isGlobal) || {}).engineVersion;
+    const skewed = globalV
+      ? npxCopies.filter((i) => i.engineVersion && i.engineVersion !== globalV)
+      : [];
+    if (skewed.length > 0) {
+      const detail = skewed.map((i) => `${i.pkgDir} has ${i.engineVersion}`).join('; ');
+      return {
+        id, name, status: 'warn',
+        message: `engine version skew — global install has ${globalV}; ${detail}`,
+        hint: HINTS.engineVersionSkew,
+      };
+    }
     return {
       id, name, status: 'ok',
       message: `engine present in ${npxCopies.length} npx-cache ${plural(npxCopies.length, 'copy', 'copies')}`,

package/src/utils/engine-install-scan.js

@@ -27,12 +27,21 @@ function defaultNpmCacheDir(platform) {
   return path.join(os.homedir(), '.npm');
 }
 
-/** Best-effort `npm root -g`. Never throws; returns null on any failure. */
-function defaultNpmRootG() {
+/**
+ * Best-effort `npm root -g`. Never throws; returns null on any failure.
+ * ⚠️ Windows needs shell:true — npm is a .cmd shim, and Node 24's
+ * CVE-2024-27980 hardening rejects .cmd via execFileSync without a shell
+ * (bare `npm` → ENOENT, `npm.cmd` → EINVAL). Without this the global install
+ * was invisible to the whole scan, which also blinded engine-repair's donor
+ * search: `doctor --fix` reported "no healthy sibling install" while one sat
+ * at %AppData%\npm\node_modules.
+ */
+function resolveNpmRootG({ execFileSync, platform } = {}) {
+  const win = (platform || process.platform) === 'win32';
   try {
-    const { execFileSync } = require('child_process');
-    const out = execFileSync('npm', ['root', '-g'], {
-      encoding: 'utf-8', timeout: 4000, stdio: ['ignore', 'pipe', 'ignore'],
+    const exec = execFileSync || require('child_process').execFileSync;
+    const out = exec(win ? 'npm root -g' : 'npm', win ? [] : ['root', '-g'], {
+      encoding: 'utf-8', timeout: 4000, stdio: ['ignore', 'pipe', 'ignore'], shell: win,
     });
     return String(out).trim() || null;
   } catch (_e) {
@@ -45,13 +54,41 @@ function safe(fn, fallback) {
   try { return fn(); } catch (_e) { return fallback; }
 }
 
+/**
+ * Resolve the engine version from the roots already on the record. Reads
+ * opencode-ai's own package.json, which is a faithful proxy for the executed
+ * binary because opencode-ai exact-pins all 12 platform sub-packages.
+ * ⚠️ Do NOT read next to the binary: hasOpencodeBinary probes
+ * opencode-windows-<arch>/bin/opencode.exe on win32 but .bin/opencode on
+ * POSIX, and .bin/ has no package.json — a binary-adjacent rule would work on
+ * Windows only and silently return nothing on the two POSIX CI legs.
+ * Uses the real `fs` module directly (not a seam) because this is the
+ * PRODUCTION default — tests always inject `readEngineVersion` instead (the
+ * suite's fakeFs implements no readFileSync).
+ * @returns {string|undefined} undefined (never null) so toEqual fixtures survive
+ */
+function defaultReadEngineVersion({ roots }) {
+  for (const root of roots || []) {
+    try {
+      const raw = require('fs').readFileSync(path.join(root, 'opencode-ai', 'package.json'), 'utf-8');
+      const v = JSON.parse(raw).version;
+      if (v) { return String(v); }
+    } catch (_e) { /* try the next root */ }
+  }
+  return undefined;
+}
+
+/** Resolve p's real path via fs.realpathSync, tolerating any throw. */
+function realNorm(p, fs) {
+  return path.normalize(safe(() => fs.realpathSync(p), p));
+}
+
 /** Drop installs whose pkgDir resolves to the same real path; keep the first. */
 function dedupByRealpath(installs, fs) {
   const seen = new Set();
   const out = [];
   for (const inst of installs) {
-    const real = safe(() => fs.realpathSync(inst.pkgDir), inst.pkgDir);
-    const key = path.normalize(real);
+    const key = realNorm(inst.pkgDir, fs);
     if (seen.has(key)) { continue; }
     seen.add(key);
     out.push(inst);
@@ -59,6 +96,21 @@ function dedupByRealpath(installs, fs) {
   return out;
 }
 
+/**
+ * True when pkgDir is the same real install as the npm-global amicus
+ * package (`<gRoot>/amicus`). Recovers "this record IS the global install"
+ * after dedupByRealpath has already dropped the separate `kind:'global'`
+ * record — see the docblock on scanEngineInstalls for why (#133 R-A finding
+ * 1: on the documented end-user invocation, `amicus doctor` run from the
+ * globally-installed copy, `runningPkgDir` IS `<npm root -g>/amicus`, and
+ * listAmicusInstalls pushes `running` first, so dedup keeps `running` and
+ * drops `global`).
+ */
+function isGlobalInstall({ pkgDir, fs, gRoot }) {
+  if (!gRoot) { return false; }
+  return realNorm(pkgDir, fs) === realNorm(path.join(gRoot, 'amicus'), fs);
+}
+
 /**
  * The amicus installs that could serve the MCP, highest-priority first
  * (running, global, then npx-cache copies). All I/O behind seams.
@@ -76,7 +128,7 @@ function listAmicusInstalls(deps = {}) {
   const platform = deps.platform || process.platform;
   const runningPkgDir = deps.runningPkgDir || path.join(__dirname, '..', '..');
   const npmCacheDir = deps.npmCacheDir || defaultNpmCacheDir(platform);
-  const npmRootG = deps.npmRootG || defaultNpmRootG;
+  const npmRootG = deps.npmRootG || (() => resolveNpmRootG({ platform }));
 
   const raw = [{ kind: 'running', pkgDir: runningPkgDir }];
 
@@ -121,22 +173,53 @@ function classifyLaunch(config) {
  * @param {object} [deps] - listAmicusInstalls seams, plus:
  * @param {(d:{pkgDir:string}) => boolean} [deps.hasOpencodeBinary]
  * @param {(d:{pkgDir:string}) => string[]} [deps.opencodeRoots]
+ * @param {(d:{pkgDir:string, roots:string[]}) => (string|undefined)} [deps.readEngineVersion]
  * @param {() => (object|null)} [deps.readAmicusMcpConfig]
- * @returns {{installs: Array<{kind,pkgDir,engineOk,roots}>, mcpLaunch: string}}
+ * @returns {{installs: Array<{kind,pkgDir,engineOk,roots,engineVersion,isGlobal?}>, mcpLaunch: string}}
  */
 function scanEngineInstalls(deps = {}) {
+  const fs = deps.fs || require('fs');
+  const platform = deps.platform || process.platform;
   const hasOpencodeBinary = deps.hasOpencodeBinary || require('./path-setup').hasOpencodeBinary;
   const opencodeRoots = deps.opencodeRoots || require('./path-setup').opencodeRoots;
+  const readEngineVersion = deps.readEngineVersion || defaultReadEngineVersion;
   const readAmicusMcpConfig = deps.readAmicusMcpConfig
     || (() => require('./mcp-discovery').readAmicusMcpConfig());
 
-  const installs = listAmicusInstalls(deps).map((i) => ({
-    ...i,
-    engineOk: !!hasOpencodeBinary({ pkgDir: i.pkgDir }),
-    roots: opencodeRoots({ pkgDir: i.pkgDir }),
-  }));
+  // Resolve `npm root -g` once and feed that SAME resolver into
+  // listAmicusInstalls (below), so the isGlobal recovery here reuses its
+  // result instead of spawning a second `npm root -g` process.
+  let gRootCache;
+  let gRootResolved = false;
+  const npmRootGRaw = deps.npmRootG || (() => resolveNpmRootG({ platform }));
+  const npmRootGOnce = () => {
+    if (!gRootResolved) { gRootCache = safe(() => npmRootGRaw(), null); gRootResolved = true; }
+    return gRootCache;
+  };
+
+  const rawInstalls = listAmicusInstalls({ ...deps, platform, npmRootG: npmRootGOnce });
+  const gRoot = npmRootGOnce(); // already resolved by listAmicusInstalls above; this just reads the cache
+
+  const installs = rawInstalls.map((i) => {
+    const roots = opencodeRoots({ pkgDir: i.pkgDir });
+    // #133 R-A finding 1: recovers "this IS the global install" for a
+    // record whose `kind:'global'` twin was dropped by dedupByRealpath
+    // (see isGlobalInstall's docblock). Deliberately NOT stamped inside
+    // listAmicusInstalls — its output is pinned exact by toEqual in
+    // tests/utils/engine-install-scan.test.js:57 and :89.
+    const isGlobal = i.kind !== 'global' && isGlobalInstall({ pkgDir: i.pkgDir, fs, gRoot });
+    return {
+      ...i,
+      engineOk: !!hasOpencodeBinary({ pkgDir: i.pkgDir }),
+      roots,
+      engineVersion: safe(() => readEngineVersion({ pkgDir: i.pkgDir, roots }), undefined),
+      ...(isGlobal ? { isGlobal: true } : {}),
+    };
+  });
   const mcpLaunch = classifyLaunch(safe(() => readAmicusMcpConfig(), null));
   return { installs, mcpLaunch };
 }
 
-module.exports = { listAmicusInstalls, scanEngineInstalls, classifyLaunch };
+module.exports = {
+  listAmicusInstalls, scanEngineInstalls, classifyLaunch, resolveNpmRootG,
+};

package/src/utils/engine-repair.js

@@ -23,11 +23,105 @@ function runningPkgDir() {
   return path.join(__dirname, '..', '..');
 }
 
-/** First healthy install whose real path differs from the destination. */
+/**
+ * Parse a semver-shaped string into a [major, minor, patch] triple.
+ * Prerelease versions (`1.18.15-beta.1`) return null — treated the same as
+ * unparseable, so they sort LAST rather than tying with (and, via a stable
+ * sort, sometimes beating) the release they're a prerelease of. Only the
+ * exact-release leading triple is a valid donor signal; amicus pins exact
+ * release versions, never prereleases.
+ * @returns {[number,number,number]|null} null for undefined/non-string/non-semver/prerelease
+ */
+function parseVersionTriple(v) {
+  if (typeof v !== 'string') { return null; }
+  const trimmed = v.trim();
+  if (/^\d+\.\d+\.\d+-/.test(trimmed)) { return null; }
+  const m = /^(\d+)\.(\d+)\.(\d+)/.exec(trimmed);
+  if (!m) { return null; }
+  return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+
+/**
+ * Descending version comparator: newest first, unparseable/absent sorts last
+ * (never throws). Two unparseable values compare equal (0).
+ */
+function compareVersionsDesc(a, b) {
+  const ta = parseVersionTriple(a);
+  const tb = parseVersionTriple(b);
+  if (!ta && !tb) { return 0; }
+  if (!ta) { return 1; }
+  if (!tb) { return -1; }
+  for (let i = 0; i < 3; i += 1) {
+    if (ta[i] !== tb[i]) { return tb[i] - ta[i]; }
+  }
+  return 0;
+}
+
+/**
+ * TWO TIERS, not one sort. An explicitly-global healthy donor — `kind:'global'`,
+ * or `isGlobal:true` when engine-install-scan.js's dedup collapsed the
+ * `global` record into `running` (#133 R-A finding 1) — wins OUTRIGHT,
+ * regardless of version. Only when no explicit-global donor exists does
+ * engineVersion rank the remaining candidates (newest first; ties/absent
+ * versions fall back to list order, running-first).
+ *
+ * Review round 2, finding 2: a single version-first sort (this function's
+ * first cut) inverted R-A's own goal three ways, each confirmed by a test in
+ * tests/utils/engine-repair.test.js:
+ *   1. running (dev tree) newer than global → donated the dev tree. R-A's
+ *      stated goal is "--fix stops donating the dev engine"; the dev tree
+ *      running ahead of the pin is the NORMAL direction mid-pin-bump, not a
+ *      reason to trust it over the global install.
+ *   2. running-that-is-global older than a healthy npx sibling → donated the
+ *      npx sibling — the exact outcome the ORIGINAL (pre-engineVersion)
+ *      findDonor test says must never happen, reintroduced via the source
+ *      class this file's own scanEngineInstalls docblock calls LEAST
+ *      trustworthy (npx-cache copies: optional-dependency skips, AV
+ *      quarantine on every re-resolve).
+ *   3. global's version unresolved, npx sibling versioned → donated the npx
+ *      copy despite a `global` record existing at all.
+ * All three share one cause: ranking by version BEFORE asking "is there an
+ * explicit global donor at all". Tiering fixes it without losing what the
+ * version ranking was FOR — Task 3's kind-only rule left a residual hole
+ * (dev checkout, no npm-global install, broken npx destination, healthy npx
+ * sibling — no record has kind:'global' at all) where the old code fell
+ * through to `healthy[0]`, the running dev tree, and could donate a
+ * version-skewed dev engine over a newer healthy sibling. That hole is
+ * exactly the case where tier 1 finds nothing and tier 2's version ranking
+ * takes over.
+ *
+ * A `kind !== 'running'` proxy for tier 1 is wrong: listAmicusInstalls pushes
+ * `running` first and `global` second, and dedupByRealpath keeps the FIRST of
+ * any two entries that resolve to the same real path. So on an ordinary
+ * end-user machine — where the running process IS the global install — the
+ * `global` record never survives dedup; that copy is labeled `kind:
+ * 'running'` (carrying `isGlobal:true` instead, once scanEngineInstalls has
+ * run). A `kind !== 'running'` filter would then skip the good global engine
+ * and donate some other (possibly stale) healthy copy, importing the exact
+ * version skew this self-heal exists to prevent.
+ *
+ * Tier 1 (`kind==='global' || isGlobal`) is correct on both topologies: on a
+ * dev machine the dev tree and the global install are distinct real paths, so
+ * the `global` record survives dedup and wins over the dev tree. On an
+ * end-user machine there is no separate `global` record — the running process
+ * already IS it, flagged `isGlobal:true` — so tier 1 still finds it. Tier 2
+ * (list-order fallback via a stable sort) only applies when tier 1 finds
+ * nothing at all — a pure dev checkout or npx-only machine.
+ */
 function findDonor({ installs, destPkgDir, fs }) {
   const norm = (p) => { try { return path.normalize(fs.realpathSync(p)); } catch { return path.normalize(p); } };
   const destReal = norm(destPkgDir);
-  return installs.find((i) => i.engineOk && norm(i.pkgDir) !== destReal) || null;
+  const healthy = installs.filter((i) => i.engineOk && norm(i.pkgDir) !== destReal);
+  if (healthy.length === 0) { return null; }
+
+  const explicitGlobal = healthy.find((i) => i.kind === 'global' || i.isGlobal);
+  if (explicitGlobal) { return explicitGlobal; }
+
+  // No explicit-global donor on this machine at all — rank the remaining
+  // healthy candidates by engineVersion (newest first; Array#sort is stable,
+  // so ties/absent versions preserve list order, i.e. running-first).
+  const sorted = [...healthy].sort((a, b) => compareVersionsDesc(a.engineVersion, b.engineVersion));
+  return sorted[0];
 }
 
 /** The donor root (nested or hoisted) that actually holds the engine binary. */

package/src/utils/remediation-hints.js

@@ -88,6 +88,35 @@ const REMEDIATION_HINTS = Object.freeze({
   sweepSessionIndexTmp:
     'amicus doctor --fix  (sweeps orphaned .sessions-index.json.*.tmp files left by an interrupted write)',
 
+  /**
+   * Engine version skew (#133 R-A): a PRESENT engine can still be the WRONG
+   * one — the npx-cache copy `npx -y amicus@latest mcp` launches and the
+   * global install resolve independently and at different times, and two
+   * engine versions writing one shared opencode.db is what produced #133's
+   * SQLiteError. Unlike reinstallEngineAv (antivirus quarantine — a MISSING
+   * binary), this is a WRONG-VERSION binary, so the remedy has to touch both
+   * sides: reinstall the global copy (which re-resolves to the exact pinned
+   * opencode-ai/@opencode-ai/sdk version amicus pins as of 4.7.1), and clear
+   * the npx-cache tree so the npx copy re-resolves fresh next time it
+   * launches instead of replaying a stale cached one.
+   *
+   * Review round 2, finding 3: the first cut of this hint said
+   * `npm cache clean --force`, which does NOT touch the npx tree — verified
+   * against npm's own lib/commands/cache.js (npm 11.16.0): `cache clean`
+   * removes `flatOptions.cache` (the registry-metadata cache, `<cache
+   * dir>/_cacache`), while npx installs live at the SEPARATE
+   * `flatOptions.npxCache` (`<cache dir>/_npx`). That command would have left
+   * the skewed npx copy byte-for-byte in place. The correct command is npm's
+   * own npx-cache subcommand: `npm cache npx rm` with no keys and `--force`
+   * empties the whole npx cache (cache.js's `npxRm`: no keys + force →
+   * `fs.rm(npxCache, {recursive:true, force:true})`). Since `doctor --fix`
+   * has no dedicated skew branch (WARN only — see doctor-engine-check.js),
+   * this hint is the ONLY remedy the user gets — it must actually work.
+   */
+  engineVersionSkew:
+    'npm install -g amicus && npm cache npx rm --force  (reinstalls the global engine to the exact pinned opencode-ai version — amicus pins it exactly as of 4.7.1 — '
+    + 'and empties the npx cache, the SEPARATE directory `npm cache clean` does not touch, so the npx-cache copy `npx -y amicus@latest mcp` launches re-resolves fresh to that same pinned version instead of replaying a stale one)',
+
   /**
    * Orphaned per-session metadata.json.*.tmp files (v4.6.3 PR3 Task 3 / D8):
    * same producer shape as sweepSessionIndexTmp above, one level down — a