@ijfw/install 1.2.3 → 1.2.5

package/CHANGELOG.md

@@ -1,5 +1,118 @@
 # Changelog
 
+## [1.2.5] -- 2026-04-30
+
+**Trident roster opens to the community + actionable auditor errors + Obsidian-friendly memory + audit-cleanup pass.** A one-page contribution playbook plus two new worked examples ship the auditor roster from "what Sean ships" to "what the community can grow." DeepSeek and Kimi land as openai-compat API entries. The 1.2.4 visibility surface gets a translation layer that tells you exactly how to fix a stalled auditor. Memory layer reaffirmed as Obsidian-vault-compatible with a walkthrough. Six surfaces from a full-system Trident audit land alongside as polish. Plus a routine dev-dependency bump.
+
+### Auditor contribution playbook
+
+`docs/CONTRIBUTING-AUDITORS.md` is the new one-page guide for proposing a new auditor for the Trident. It covers when to propose (lineage diversity, reachability gap, local/zero-cost path), the roster entry shape with a fully annotated worked example, what tests are needed, and -- importantly -- what gets declined and why. The goal is to lower the friction for a community contribution from "read three source files and guess" to "fill in the template, copy the qwen entry, ship a 10-line PR."
+
+A companion GitHub issue template at `.github/ISSUE_TEMPLATE/auditor-proposal.yml` lets contributors propose a new auditor without writing a line of code first. It captures the load-bearing answers up front (lineage, diversity gain, access path, auth env var, maintenance commitment) so triage is one read, not a back-and-forth.
+
+Files: `docs/CONTRIBUTING-AUDITORS.md` (new), `.github/ISSUE_TEMPLATE/auditor-proposal.yml` (new), `README.md` (auditor section now references the six-lineage roster and the playbook).
+
+### DeepSeek joins the Trident
+
+DeepSeek-V4 (Chinese open-source lineage, MIT-licensed weights, `deepseek-v4-flash` for the audit path) lands as an openai-compat roster entry. Distinct training data and posttraining recipe from the existing OpenAI / Google / Anthropic / Alibaba lineages, which is exactly what adversarial review wants. Pricing is among the cheapest of any reasoning-capable model on the roster, which makes it attractive for high-volume audit cycles.
+
+API path: `https://api.deepseek.com/v1/chat/completions`, auth via `DEEPSEEK_API_KEY`. No first-party canonical CLI -- multiple third-party CLIs exist, none standardized; this entry treats the API as load-bearing and lets the dispatcher fall back to a CLI if one is on PATH. Self-detection deliberately returns false to avoid false-excluding the entry on machines that have any of the third-party CLIs installed without an active session.
+
+Files: `mcp-server/src/audit-roster.js`, `mcp-server/test-audit-roster.js`.
+
+### Kimi (Moonshot) joins the Trident
+
+Moonshot AI Kimi K2 series (Chinese open-source lineage, separate from DeepSeek; current alias `kimi-k2.6`). Long-context strength makes Kimi useful for whole-file or whole-module audits where context-window budget matters. OpenAI-compatible API via `platform.moonshot.ai`.
+
+API path: `https://api.moonshot.ai/v1/chat/completions`, auth via `MOONSHOT_API_KEY`. Self-detection returns false for the same reason as DeepSeek -- prefer double-coverage over false self-exclusion.
+
+Files: `mcp-server/src/audit-roster.js`, `mcp-server/test-audit-roster.js`.
+
+### Build pipeline upgraded to esbuild 0.28
+
+`installer/`'s esbuild devDependency moves to 0.28.0, picking up TC39 stage-3 `with { type: 'text' }` import support, an integrity-check pass on the fallback download path, and the internal Go-compiler bump from 1.25.7 to 1.26.1. `installer/dist/` rebuilds cleanly on the new version with no shipped-artifact change -- a build-time tooling refresh, end users see the same output.
+
+Files: `installer/package.json`, `installer/package-lock.json`.
+
+### Trident now tells you exactly what to do when an auditor stalls
+
+The 1.2.4 visibility surface that flagged degraded Trident runs got noisier in the right way: instead of dumping the first 80 characters of an auditor's stderr, the new `translateAuditorError()` pattern-matches the common stall signatures and renders one actionable line. Codex auth-refresh failure now reads `Codex auth token expired or stale. Run \`codex login\` to refresh, then re-run.` instead of `codex_models_manager::manager: failed to refre`. Qwen with no auth configured tells you to run `qwen auth`. Gemini's safety filter explains it may be a false negative on this target. Generic 401/403, 429 / quota, ENOTFOUND / network, missing API keys, and spawn-ENOENT each get their own one-line fix. The catch-all preserves the raw error head so nothing's hidden. Thirteen new unit tests cover each pattern.
+
+Files: `mcp-server/src/cross-orchestrator-cli.js` (`translateAuditorError` + degraded surface rewire), `mcp-server/test-translate-auditor-error.js` (new).
+
+### Memory layer is Obsidian-friendly out of the box
+
+A new `docs/OBSIDIAN.md` walks through opening your IJFW memory directory as an Obsidian vault. Plain markdown plus YAML frontmatter is exactly Obsidian's native format; full-text search, property view, graph view of the `MEMORY.md` index, and per-type filtering all work today with zero conversion. You can hand-edit memories from Obsidian and IJFW reads them on the next session.
+
+Files: `docs/OBSIDIAN.md` (new).
+
+### Dispatcher reliability hardening
+
+A second-pass full-lineage Trident audit on the 1.2.5 branch (codex + gemini + kimi consensus) surfaced three reliability surfaces in the cross-audit dispatcher itself, all in `minResponsesFanOut` and `spawnCli`. Fixed before ship:
+
+- **`minResponsesFanOut` no longer counts failed/timeout/aborted auditors toward the minResponses threshold.** Previously a user passing `--with codex,gemini,deepseek` with no `DEEPSEEK_API_KEY` would have deepseek fail fast and count toward minResponses=2, which could abort still-running productive auditors before they returned findings. Productive results (CLI exit 0 or API-fallback success) now count toward the threshold; non-productive settlements still count toward all-done detection so the promise never deadlocks.
+- **`minResponsesFanOut` now `.catch()`-guards the `fireExternal` promise.** `fireExternal` should always resolve with a result object, but a defensive catch arm prevents a synchronous throw anywhere in the future from leaving the orchestrator promise unresolved forever.
+- **`spawnCli` respects stdin backpressure.** For typical 1-50 KB prompts nothing changes (the pipe buffer absorbs the write). For very large requests (long synthesis prompts, big file targets), the write now waits for `drain` before calling `.end()` to avoid dropping bytes on CLI implementations that don't buffer fully on their end.
+
+Files: `mcp-server/src/cross-orchestrator.js` (both functions).
+
+### Audit-cleanup pass
+
+A full-system Trident audit on the 1.2.5 branch surfaced six small surfaces worth landing alongside the new features rather than carrying as backlog:
+
+- **`atomicWrite` honors its fsync claim** -- the function comment promised "write to .tmp, fsync, rename"; the implementation was missing the `fsyncSync(fd)` step. Added so the durability contract matches the documentation. Cost: one syscall per persisted memory write (microseconds). Benefit: data survives a kernel panic between `close()` and `rename()`. (`mcp-server/src/server.js`)
+- **Duplicate SIGINT listener removed** -- two consecutive `process.on('SIGINT', ...)` lines registered the same handler. Cosmetic but obviously unintentional. (`mcp-server/src/server.js`)
+- **`buildGemini` defensive endpoint guard** -- explicit `Error` if `apiFallback.endpoint` is missing instead of an opaque `TypeError` from `String.prototype.replace`. (`mcp-server/src/api-client.js`)
+- **Dropped redundant `?key=` URL parameter on Gemini API calls** -- auth flows entirely through the `x-goog-api-key` header. The URL form was redundant and slightly leakier (logs / proxies can capture URLs more easily than headers). (`mcp-server/src/api-client.js`)
+- **Hook input over 1 MiB exits cleanly with a stderr note** -- the post-tool-use signal-capture hook used to slice mid-JSON and silently exit on `JSON.parse` failure. Now logs an explicit "tool_response > 1 MiB, skipping signal extraction" before exiting. Hooks still never block, but they no longer fail invisibly on edge-case oversize inputs. (`claude/hooks/scripts/post-tool-use.js`)
+- **`install_hook` no longer skips silently when no checksum util is on host** -- on stripped containers without `md5sum`, `md5`, or `sha1sum`, both checksum reads returned empty strings and compared equal, so updates were silently skipped. The function now detects empty checksums, takes a precautionary backup, and forces the copy through. (`scripts/install.sh`)
+
+Audit report at `.planning/audit-1.2.5/REPORT.md` (local). Backlog of remaining deferred items tracked separately.
+
+### Verification
+
+537/537 unit tests across the mcp-server pass at 1.2.5 (two new reachability tests for DeepSeek + Kimi, thirteen new tests for the actionable-error translator). The full e2e smoke harness (60+ gates including isolated-HOME install, every platform's config schema, live `opencode/qwen/kimi/openclaw mcp list` handshakes, MCP server initialize+tools/list handshake) all pass on macOS at 1.2.5.
+
+## [1.2.4] -- 2026-04-29
+
+**Trident lineage diversity + Windows Git Bash parity + auditor reachability sharpening.** Three substantive improvements: a new third foundation-model lineage in the cross-audit roster, end-to-end Windows Git Bash support for the `ijfw` CLI itself (companion to 1.2.3's Windows MCP-spawn parity), and a set of polish improvements to how IJFW detects and surfaces auditor availability. Two community contributions land in this release. No breaking changes.
+
+### Qwen 3 Coder joins the Trident as a third lineage
+
+The cross-audit roster gains **qwen-code** (Qwen 3 Coder, Alibaba, Apache-2.0) alongside codex (openai) and gemini (google). The CLI is a maintained fork of gemini-cli (`npm install -g @qwen-code/qwen-code`), so the invocation pattern is already compatible with the existing dispatcher contract. ~67% SWE-Bench Verified per Qwen3-Coder-480B-A35B's published numbers, comparable to Kimi K2 with a smaller activated model.
+
+Strategic value: when the caller itself is in the openai or google family, the diversity strategy now has a real third lineage to draw from instead of falling back to opencode/aider (which most users don't have installed). Apache-licensed weights also enable a locally-runnable backbone via Ollama for zero-API-cost auditing. Authentication supports `qwen-oauth` (free Coding Plan tier) plus openai/anthropic/gemini auth-types via `qwen auth`.
+
+The roster entry sits between gemini and opencode by deliberate priority placement -- qwen has both a maintained CLI and a working API fallback, so it wins backfill ahead of opencode's weaker SWE-Bench numbers.
+
+Files: `mcp-server/src/audit-roster.js`, `mcp-server/test-audit-roster.js`. Contributed by [@carrmjw](https://github.com/carrmjw) (PR #11).
+
+### Windows Git Bash CLI now works end-to-end
+
+Companion to 1.2.3's MCP-spawn parity. The `ijfw` CLI itself now operates correctly on Windows 11 + Git Bash + MINGW64.
+
+Two issues fixed: the `isMainModule` check at the bottom of `cross-orchestrator-cli.js` previously compared `import.meta.url` against `` `file://${process.argv[1]}` `` directly. On Git Bash, `process.argv[1]` arrives as `/c/Users/.../cli.js` while `import.meta.url` arrives as `file:///C:/Users/.../cli.js` -- neither branch of the comparison matched, the dispatch block was skipped, and Node exited 0 with no output for every subcommand. Replaced with `pathToFileURL(process.argv[1]).href`, which normalizes both Windows drive paths and MSYS-style paths into the same `file:///C:/...` form. Realpath fallback retained so macOS `/tmp -> /private/tmp` symlink hops still resolve. The new behavior verifies live: `ijfw doctor`, `ijfw --help`, and `ijfw status` all produce expected output on a fresh Git Bash session.
+
+Second: `scripts/install.sh`'s symlink wiring at `~/.local/bin` previously trusted `ln -s`'s exit code. On Windows MINGW64 without admin or Developer Mode, `ln -s` silently falls back to a file copy and still returns 0, so the installer printed "5 commands linked" while the launcher's `readlink` walk later failed at runtime. The installer now follows up with a `[ -L "$dst" ]` check, removes copy-fallbacks, and surfaces a yellow hint listing three concrete fixes (Developer Mode, Admin shell, `MSYS=winsymlinks:nativestrict`) plus the PATH-edit fallback. Zero behavior change on macOS or Linux where `ln -s` always produces real symlinks.
+
+Files: `mcp-server/src/cross-orchestrator-cli.js`, `scripts/install.sh`. Contributed by [@BrewsterNZ](https://github.com/BrewsterNZ) (PR #7).
+
+### Auditor reachability sharpening
+
+Reviewing the qwen contribution led us to improve several other things in the surrounding code:
+
+- **Codex now actually participates as the OpenAI leg of the Trident more often.** `detectSelf` previously matched both `CODEX_SESSION_ID` (an active-session marker) AND `CODEX_HOME` (a config-path env var that's set whenever codex is *installed*). On any machine that had codex installed alongside another agent, codex was being silently excluded from every Trident run as if it were the active caller. Self-detection now keys off `CODEX_SESSION_ID` only, so the openai-lineage leg is genuinely available whenever the caller is Claude Code, Cursor, Gemini CLI, or anything non-codex.
+- **OpenAI-compatible provider in `api-client.js`.** `buildOpenAI` accepts an optional endpoint parameter, and `runViaApi` now recognizes `provider: "openai-compat"`. Any chat-completions-shaped backend (Qwen via DashScope, Together, Groq, etc.) can serve as an API fallback without bespoke plumbing -- directly enables qwen's DashScope path added in this release, and keeps the door open for future openai-compatible auditors.
+- **`defaultAuditor` respects reachability.** Previously returned the first non-self entry even when neither its CLI nor its API key was available, so callers got a misleading "ready" pick that fell over on first invoke. Now returns the highest-priority reachable entry.
+- **`formatRoster` reflects API-only reachability.** A user with `OPENAI_API_KEY` set but no codex binary on PATH used to see `install` in the roster output, missing that the API path was already configured. The role label is now `ready` whenever the auditor is reachable via either CLI or API.
+- **`pickAuditors({only:"<self>"})` skips self-audit explicitly.** Requesting the caller's own ID via `--with` collapses the Trident to a single source. The orchestrator now surfaces a clear note explaining the skip instead of silently degrading.
+
+Files: `mcp-server/src/audit-roster.js`, `mcp-server/src/api-client.js`, `mcp-server/test-audit-roster.js`, `mcp-server/test-api-client.js`.
+
+### Verification
+
+522/522 unit tests across the mcp-server pass at 1.2.4 (six new tests covering the auditor-reachability improvements and the openai-compat provider). The full e2e smoke harness (60+ gates including isolated-HOME install, every platform's config schema, live `opencode/qwen/kimi/openclaw mcp list` handshakes, MCP server initialize+tools/list handshake) all pass on macOS at 1.2.4.
+
 ## [1.2.3] -- 2026-04-28
 
 **Cross-platform parity + Trident transparency patch.** Three improvements: Windows now reaches the same MCP-spawn quality as macOS and Linux across every supported platform, gemini-cli auth precedence honors `GEMINI_API_KEY` deterministically, and the Trident no longer fails silently when an auditor returns no findings. No new features, no breaking changes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ijfw/install",
-  "version": "1.2.3",
+  "version": "1.2.5",
   "description": "One-command installer for IJFW -- the AI efficiency layer. One install, every AI coding agent, zero config.",
   "type": "module",
   "bin": {
@@ -25,7 +25,7 @@
     "prepublishOnly": "npm run build && npm run preflight"
   },
   "devDependencies": {
-    "esbuild": "^0.25.0",
+    "esbuild": "^0.28.0",
     "marked": "^18.0.2"
   },
   "engines": {