@ijfw/install 1.2.4 → 1.2.6

package/CHANGELOG.md

@@ -1,5 +1,135 @@
 # Changelog
 
+## [1.2.6] -- 2026-05-01
+
+**Token sandbox + parallel workflow dispatch + DeepSeek frontier upgrade.** A new `ijfw_run` MCP tool keeps large command output out of your context window entirely — builds, test suites, grep runs, and log tails are sandboxed to disk and summarized in a few lines instead of flooding thousands of tokens. The `ijfw-workflow` execution engine gains a formal Wave Table that makes parallel agent dispatch deterministic rather than inferred. DeepSeek moves to `deepseek-v4-pro` — the actual frontier model — so the Trident gets Frontier AI checking Frontier AI.
+
+### `ijfw_run` — command output sandbox
+
+Large shell commands (builds, test suites, `grep -r`, log tails) routinely produce hundreds or thousands of lines that consume a disproportionate share of the context window. `ijfw_run` solves this at the tool level: run the command via `child_process.spawn` (never `exec` — no RAM buffer ceiling), stream output to `~/.ijfw/session-sandbox/`, and return a domain-aware summary to context instead of the raw flood.
+
+**Domain-aware summarizers** detect output type by pattern and extract only what matters:
+- **Test runner** (Jest/Vitest/pytest/go test/cargo test): pass/fail counts + failing test names only
+- **Build** (tsc/cargo/webpack/vite/rollup): error lines only + exit code
+- **Grep**: match count + top file paths
+- **Log**: ERROR/WARN lines + counts
+- **Raw fallback**: first 15 + last 10 lines + "N lines omitted"
+
+Every summary appends the last 10 raw lines as a reliability backstop (catches segfaults, OOM kills, and non-standard failures that heuristics miss), and includes the command, exit code, duration, and a retrieval label. Commands at or under 40 lines / 50 KB return inline with zero overhead — `ijfw_run` only sandboxes when it pays off.
+
+**Retrieval**: full output is indexed to `~/.ijfw/session-sandbox/{label}.txt` with a `.json` metadata sidecar. Retrieve with `ijfw_memory_search({ scope: "sandbox", label: "..." })` or list all current sandbox entries with `ijfw_memory_search({ scope: "sandbox" })`. Sandbox files auto-purge after 24 hours (TTL sweep runs on every `ijfw_run` call).
+
+**Security**: all labels are sanitized before becoming filenames; sandbox files are written at mode `0o600` (user-read-only); all SQLite interactions use parameterized queries; ANSI escape codes are stripped before heuristic detection and before content is returned to the LLM context.
+
+**Routing rule**: `ijfw-core` SKILL.md now carries the one-line routing rule — large-output commands → `ijfw_run`; git, navigation, and quick ops → Bash directly.
+
+**`ijfw_memory_status` retired** to free the MCP tool slot. The case handler is preserved for backward compatibility; the tool no longer appears in `tools/list`. Status information remains available via `ijfw_memory_prelude`.
+
+**New `sanitizeForSandbox()`** in `sanitizer.js`: a sandbox-specific sanitizer that preserves newlines (unlike `sanitizeContent` which collapses to `" | "`), strips ANSI codes, defangs structural markdown elements (`#` headings, fenced code delimiters, `<system>/<prompt>/<assistant>` tags), and truncates lines over 2000 characters. Used for all LLM-facing sandbox output.
+
+**`sandbox-nudge.sh` PreToolUse hook**: registered alongside the existing `pre-tool-use.sh`, this advisory hook pattern-matches known large-output command prefixes (`npm test`, `jest`, `vitest`, `pytest`, `cargo build`, `cargo test`, `make`, `gradle`, `mvn`, `go test`, `node --test`, `tsc --`, `webpack`, `vite build`, `rollup`, `grep -r`, `find /`) and emits a one-line nudge. Advisory only — never blocks.
+
+Files: `mcp-server/src/sandbox.js` (new), `mcp-server/src/server.js`, `mcp-server/src/sanitizer.js`, `mcp-server/test-sandbox.js` (new, 32 tests), `mcp-server/test.js` (slot-swap update), `claude/skills/ijfw-core/SKILL.md`, `claude/hooks/hooks.json`, `claude/hooks/scripts/sandbox-nudge.sh` (new).
+
+### Parallel workflow dispatch — Wave Table
+
+The `ijfw-workflow` execution engine had a structural gap: Step 5 (Plan) described dependency relationships in prose, which meant Step 6 (Execute) had to re-infer parallelism at dispatch time. Re-inference defaults to sequential to avoid mistakes. The result: agents that could run concurrently ran one-by-one.
+
+**Step 5 now emits a Wave Table** as the first section of `plan.md`:
+
+```
+| Wave | Tasks     | Mode       | Depends on | Reason              |
+|------|-----------|------------|------------|---------------------|
+| W1   | t1, t2, t3 | PARALLEL  | —          | independent files   |
+| W2   | t4         | SEQUENTIAL | W1         | needs t2 output     |
+| W3   | t5, t6     | PARALLEL   | W2         | independent of each |
+```
+
+Wave mode is determined by a four-question dependency test before the table is written: (a) shared file writes? (b) one reads what the other writes? (c) output dependency? (d) otherwise → PARALLEL. The Wave Table is the execution contract — decided once at plan time.
+
+**Step 6 reads the Wave Table directly**: PARALLEL waves → all tasks dispatched as Agent tool calls in a single response (they run concurrently); SEQUENTIAL waves → one Agent call, wait for result, advance. If `plan.md` has no Wave Table (legacy plans, quick-mode tasks), Step 6 builds one on the spot using the same four-question test before dispatching anything. The instruction is now unambiguous: parallel waves produce multiple tool calls in one response block, not one-by-one messages.
+
+Files: `claude/skills/ijfw-workflow/SKILL.md`.
+
+### DeepSeek Trident auditor upgraded to `deepseek-v4-pro`
+
+The 1.2.5 DeepSeek roster entry used `deepseek-v4-flash` as the API model ID — a model that does not exist on DeepSeek Platform. Calls returned 4xx errors that surfaced as apparent timeouts. The entry is corrected to `deepseek-v4-pro`: DeepSeek's 1.6T-parameter frontier model (49B activated), supporting 1M context and dual thinking/non-thinking modes. `deepseek-chat` and `deepseek-reasoner` — the previous canonical aliases — are deprecated aliases for V4-Flash non-thinking and thinking modes respectively, scheduled for removal 2026-07-24. `deepseek-v4-pro` is the correct Trident-grade choice: Frontier AI checking Frontier AI.
+
+Files: `mcp-server/src/audit-roster.js`.
+
+## [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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ijfw/install",
-  "version": "1.2.4",
+  "version": "1.2.6",
   "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": {