ai-consultants 2.17.2 → 2.19.2

package/CLAUDE.md

@@ -6,7 +6,7 @@ AI Consultants is a multi-model AI deliberation system that queries up to 15 AI
 
 **Self-Exclusion**: The invoking agent is automatically excluded from the panel to prevent self-consultation. Claude Code won't query Claude, Codex CLI won't query Codex, etc.
 
-**Version**: 2.17.2
+**Version**: 2.19.2
 
 ## Distribution
 
@@ -826,6 +826,37 @@ curl -fsSL https://raw.githubusercontent.com/matteoscurati/ai-consultants/main/s
 
 ## Changelog
 
+### v2.19.2
+- **Cost tracking silently lost on a fresh install — fixed.** `lib/costs.sh::track_session_cost` wrote to `$COST_TRACKING_FILE` (`$XDG_DATA_HOME/ai-consultants/costs.json`, i.e. `~/.local/share/...`) without ever creating the parent directory. That dir doesn't exist until something makes it, and `costs.json` is the only artifact stored there — so on a fresh install every session's cost write failed with "No such file or directory" (swallowed under `set -e` in the caller) and cumulative cost tracking never accumulated. Fix: `mkdir -p "$(dirname "$COST_TRACKING_FILE")"` up front; on failure, `log_warn` + `return 0`.
+- **Function split for lock discipline**: `track_session_cost` (outer) now owns dir creation + locking and delegates the read-modify-write to a new inner `_track_session_cost_update`, which runs with the lock held and never propagates failure. Rationale documented inline: the caller in `consult_all.sh` runs under `set -e` *after* every consultant has already been queried and billed, so a bookkeeping failure must degrade to a warning, never abort the run.
+- **Concurrency**: the RMW of `costs.json` was unguarded, so parallel consultations could interleave and lose records or fail the `mv`. Added a portable `mkdir`-based lock (flock is unavailable on macOS) with a bounded wait (50 × 0.1s = 5s); if the lock stays busy it proceeds unlocked with a warning rather than blocking or aborting. Writes now go through `mktemp "${COST_TRACKING_FILE}.XXXXXX"` instead of a fixed `.tmp` sibling, so an unlocked concurrent writer can't clobber another run's temp file (lost record / failed `mv`).
+- **Corrupt-file self-heal**: a corrupt `costs.json` (truncated write, interleaved update) previously failed every future `jq` update forever and never recovered. Now `jq empty` gates the file; on failure it's moved aside to `${COST_TRACKING_FILE}.corrupt` and reset, so tracking recovers on the next session.
+- **Tests**: `scripts/test_suite.sh::test_cost_tracking_resilience` (5 assertions, wired into `main()`) — costs.json created under a missing nested parent dir (fresh-install path), second session accumulates on the existing file (0.25 → 0.75, both exact in binary float), a corrupt costs.json is reset with the new session recorded, and the corrupt original is preserved as `.corrupt`. Calls guarded with `|| true` so a regression surfaces as a FAIL assertion, not a `set -e` suite abort. 8 suites pass; the new assertions are green; shellcheck clean.
+- **No behavioral change for existing installs** whose data dir already exists; the fix only affects the first-run/absent-dir, concurrent, and corrupt-file paths. Cost bookkeeping remains best-effort by design.
+
+### v2.19.1
+- Cleanup from `/code-review max` on v2.19.0 (the workflow ran degraded under rate limits but surfaced these once it completed; all confirmed inline):
+  - **Report-table mangling fixed**: a failure reason containing a `|` (e.g. a CLI error mentioning a piped command) broke the "Diagnosed Failures" markdown row. The new `lib/common.sh::render_diagnosed_failure <entry> [console|table]` escapes `|`→`\|` in table mode. (Not a security injection — the text is the user's own CLI stderr — but a real rendering bug.)
+  - **DRY**: that helper is now the single source of the `name|reason` decode; the console log (quorum FAILED branch) and the report table both call it, so a future delimiter/encoding change touches one place instead of two.
+  - **Health gate is cache-aware**: it no longer pings a consultant whose response is already cached (Round 1 would serve it free via `check_cache`) — it keeps the cached consultant without a billed probe. Avoids the opt-in gate defeating the semantic cache.
+  - **`ping_consultant` takes the already-lowercased id** (callers compute it for the out/err paths anyway), dropping a redundant `to_lower` fork per consultant on both call sites (`doctor --live`, health gate).
+  - **Documented** the health gate's inherent pre-Round-1 startup latency (serial with the run by definition; up to `HEALTH_GATE_TIMEOUT`) in `config.sh` — it's the cost of pruning up front; opt-in + tunable.
+- Tests: `test_render_diagnosed_failure` (4 assertions incl. pipe-escaping); `test_ping_consultant` updated for the lowercased-id signature. 8 suites pass; shellcheck clean. Smoke-verified: report table renders correctly, health gate still prunes + the min-2 guard fires on the pruned count.
+
+### v2.19.0
+- **Quorum grading + "Diagnosed Failures" report** (the #1 pick from the `/workflows` CLI-reliability investigation — chosen for zero transport/billing risk over the CLI→API fallback, which the workflow's adversarial critique showed would emit persona-less confidence-5 stubs that poison voting). After the round-1 collect loop, `grade_quorum <success> <attempted> <min>` (new pure helper in `lib/common.sh`) classifies the run **MET / DEGRADED / FAILED** vs `QUORUM_MIN` (default 2). The report gains an `**Outcome**:` banner and a **## Diagnosed Failures** table that surfaces each dropped consultant's reason (the v2.18.0 `.err` capture) — so a panel that silently shrank to 2/7 is visibly DEGRADED instead of presenting as authoritative. `QUORUM_ACTION=stop` aborts below quorum; default `warn` continues with the banner. Failures are collected in `_surface_consultant_error` (DRY — same call that already logs the reason).
+- **Health gate (`ENABLE_HEALTH_GATE`, opt-in)** — before the run, ping every selected consultant **in parallel** (new `lib/common.sh::ping_consultant`, `HEALTH_GATE_TIMEOUT` default 30s) and drop the non-responsive ones, so installed-but-unauthenticated CLIs (Cursor/Kimi/stale installs) are pruned up front and the quorum/budget checks see the genuinely-working panel. Script-less custom API agents (no `query_*.sh`) return code 2 and are kept (not probeable). Opt-in because it costs one extra tiny query per consultant; it prunes, it does not switch transport.
+- **DRY**: `doctor --live` refactored to use the shared `ping_consultant`; both surfaces now share one probe implementation.
+- **Explicitly NOT done** (per the workflow synthesis): CLI→API automatic fallback (persona-loss vote poisoning; Gemini already auto-resolves), cold-start retry-timeout escalation (stretches the whole round's worst case), warm-up calls, and the transport-abstraction circuit breaker (racy on-disk state, highest blast radius).
+- **Tests**: `test_functions.sh` — `test_grade_quorum` (5 assertions: MET/DEGRADED/FAILED + boundaries) and `test_ping_consultant` (3: valid→0, no-output→fail, missing-script→2, via stub query scripts). 8 suites pass; shellcheck clean. End-to-end smoke verified: a forced CLI failure yields FAILED outcome + Diagnosed Failures table with the real reason, and the health gate prunes the dead consultant pre-run.
+
+### v2.18.0
+- **Failures are now diagnosable, not silent (Fix A).** `consult_all.sh` launched every consultant with `> /dev/null 2>&1` — discarding stderr — so a failed consultant produced only a bare `Failed`/`Empty response`, with no way to tell *not installed* vs *not authenticated* vs *transient* (this is exactly what led a real session to mis-attribute failures to a timeout). Now each consultant's stderr is captured to `$OUTPUT_DIR/<consultant>.err`, and on FAILED/EMPTY the run surfaces a one-line reason via the new `lib/common.sh::get_consultant_error_reason` helper (ANSI-stripped, prefers an explicit error line, drops orchestration status noise, falls back to "no error captured — CLI likely missing or not authenticated").
+- **`run_query` now embeds the CLI's real error in its failure log.** The per-attempt CLI stderr (`${output_file}.err`, an unpredictable mktemp path the orchestrator can't locate) was only `log_debug`'d. Its first line is now appended to the `Error (code: N)` and `All N attempts failed` warnings, so the actual reason (e.g. `401 Unauthorized`, `command not found`) reaches the captured stderr and the surfaced message.
+- **`doctor.sh --live` (Fix B): real ping per consultant.** The static checks only verify a CLI is installed (`--version`), so `doctor` reports a consultant healthy even when it errors at query time (unauthenticated) — a real source of "All systems healthy" while 3 consultants silently fail. `--live` sends a minimal real query to each *enabled* (and not self-excluded) consultant with a short timeout (`DOCTOR_LIVE_TIMEOUT`, default 45s), and reports ✓/✗ with the captured reason; failures become `doctor` issues (exit 1). Opt-in (costs one tiny query each). Standalone short-circuit mode like `--suggest-preset`.
+- **Tests**: `test_functions.sh::test_get_consultant_error_reason` (5 assertions: explicit-error line, embedded-auth reason, orchestration-noise-not-mistaken, empty/missing file). 8 suites pass; shellcheck clean (CI invocation).
+- **Not fixable in code (documented for users)**: the underlying CLI auth/install state, and cold-start/warm-up retry effects, are environment issues — `--live` *surfaces* them but can't authenticate a CLI for you.
+
 ### v2.17.2
 - **SECURITY: revert v2.17.1's `allow_absolute=true` for context files — it opened a secret-exfiltration surface (caught in `/code-review max`).** v2.17.1 fixed the macOS `/private/tmp` drop by letting `build_context.sh` accept *any* absolute context path behind `validate_file_path`'s prefix-only blocklist (`/etc /root /var/log /proc /sys /dev`). That blocklist covers no home secrets, so a context arg of `~/.ssh/id_rsa`, `~/.aws/credentials`, `~/.netrc`, or `~/.config/gh/hosts.yml` was read verbatim and **sent to the external AI providers**. It also matched literal non-canonical prefixes, so `/private/etc/master.passwd` (the real `/etc` on macOS, via the same symlink aliasing) bypassed the `/etc` rule.
 - **Fix (correct altitude — allowlist, not blocklist)**: context files are now accepted only when (a) relative and in-tree (`validate_file_path ... false` — rejects absolute and `..`), or (b) under a recognized temp root via the new `_is_temp_path` helper (`/tmp`, `/private/tmp`, `$TMPDIR`, and the `/private`-prefixed macOS alias of `$TMPDIR`; `..` rejected so a temp prefix can't traverse out). Still fixes the original macOS scratch-file regression (Claude Code writes `/private/tmp/...`) **without** widening to the whole filesystem. Verified: `/tmp`, `/private/tmp`, `$TMPDIR/...`, relative in-tree → accepted; `~/.ssh/id_rsa`, `/etc/passwd`, `/private/etc/master.passwd`, `/tmp/../etc/passwd` → rejected.

package/README.md

@@ -1,8 +1,8 @@
-# AI Consultants v2.17.2
+# AI Consultants v2.19.2
 
 > **A harness for every question.** A panel of up to 15 frontier models that writes its own playbook per question — fan out, debate to convergence, cross-examine under adversarial review, or run a tournament — and checks its work before it reaches you.
 
-[![Version](https://img.shields.io/badge/version-2.17.2-blue.svg)](https://github.com/matteoscurati/ai-consultants)
+[![Version](https://img.shields.io/badge/version-2.19.2-blue.svg)](https://github.com/matteoscurati/ai-consultants)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 [![Claude Code Skill](https://img.shields.io/badge/Claude%20Code-Skill-orange.svg)](https://docs.anthropic.com/en/docs/claude-code/skills)
 [![GitHub stars](https://img.shields.io/github/stars/matteoscurati/ai-consultants?style=social)](https://github.com/matteoscurati/ai-consultants)
@@ -574,13 +574,16 @@ Full reference (~150 vars): [`references/configuration.md`](references/configura
 Diagnose, suggest, and fix:
 
 ```bash
-ai-consultants doctor                                          # 22 health checks
+ai-consultants doctor                                          # 22 health checks (CLI installed?)
 ai-consultants doctor --fix                                    # Auto-fix common issues
 ai-consultants doctor --json                                   # JSON for automation
+ai-consultants doctor --live                                   # Real ping per consultant — catches installed-but-unauthenticated CLIs
 ai-consultants doctor --suggest-config                         # Print recommended ENABLE_* based on detected CLIs
 ai-consultants doctor --suggest-preset --question "..."        # Recommend preset + strategy for a question
 ```
 
+> When a consultant fails mid-consultation, the run surfaces the captured reason (e.g. `CLI not found`, `401 Unauthorized`) instead of a bare "Failed", so you can tell *not installed* from *not authenticated* from *transient*.
+
 ---
 
 ## How It Works

package/SKILL.md

@@ -5,10 +5,10 @@ license: MIT
 compatibility: Requires bash, jq, and at least 2 AI CLI tools (agy, codex, vibe, etc.). macOS and Linux.
 metadata:
   author: matteoscurati
-  version: 2.17.2
+  version: 2.19.2
 ---
 
-# AI Consultants v2.17.2 - AI Expert Panel
+# AI Consultants v2.19.2 - AI Expert Panel
 
 **A harness for every question.** Convene a panel of AI "consultants" for coding questions — and let the engine pick *how* they deliberate: a quick read, a convergence loop, an adversarial refutation gate, a tournament, or an exhaustive sweep. Each consultant has a **configurable persona** that shapes its analysis.
 
@@ -130,11 +130,14 @@ See [Full Configuration Reference](references/configuration.md) for all variable
 Diagnose and fix issues:
 
 ```bash
-./scripts/doctor.sh              # Full check
+./scripts/doctor.sh              # Full check (CLI installed?)
 ./scripts/doctor.sh --fix        # Auto-fix
 ./scripts/doctor.sh --json       # JSON output
+./scripts/doctor.sh --live       # Real ping per consultant — catches installed-but-unauthenticated CLIs
 ```
 
+When a consultant fails during a consultation, the run prints the captured reason (e.g. "CLI not found", "401 Unauthorized"). The run is also **graded** MET/DEGRADED/FAILED by how many responded (`QUORUM_MIN`), with a "Diagnosed Failures" section in the report. Set `ENABLE_HEALTH_GATE=true` to ping consultants and drop the dead ones *before* the run.
+
 ## Interpreting Results
 
 | Scenario | Recommendation |

package/docs/COST_RATES.md

@@ -1,4 +1,4 @@
-# Cost Rates - AI Consultants v2.17.2
+# Cost Rates - AI Consultants v2.19.2
 
 This page documents the per-token rates used by the cost tracking system.
 

package/docs/cost_rates.json

@@ -1,5 +1,5 @@
 {
-  "version": "2.17.2",
+  "version": "2.19.2",
   "updated": "2026-06-24",
   "models": {
     "_comment_units": "All rates are USD per 1,000 tokens (per-1K). lib/costs.sh computes cost as (token_count / 1000) * rate, so every value here MUST be a per-1K rate = (provider $/1M price) / 1000. Do NOT paste $/MTok figures directly.",

package/docs/releases/v2.18.0.md

@@ -0,0 +1,63 @@
+# Release v2.18.0
+
+**Date:** 2026-06-26
+**Type:** Minor — observability (diagnosable failures + live doctor)
+**Previous:** v2.17.2
+
+## Highlights
+
+- **When a consultant fails, you now see *why*** — "CLI not found", "401 Unauthorized", "Timeout", etc. — instead of a bare "Failed".
+- **`doctor.sh --live`** sends a real ping to each enabled consultant, catching CLIs that are installed but not authenticated (which the static check reports as healthy).
+
+## What's New
+
+### Failures tell you the reason
+
+Previously the orchestrator launched every consultant with its output **and stderr** sent to `/dev/null`, so a failing consultant produced only `Failed` / `Empty response` with no detail — making it impossible to distinguish *not installed* from *not authenticated* from a *transient* error without digging through temp files. (In a real session this led to a wrong diagnosis — blaming a timeout for what were actually auth failures.)
+
+Now each consultant's stderr is captured, and on failure the run prints a one-line reason:
+
+```
+  ✗ Cursor: Failed
+    ↳ Cursor: [ERROR] Cursor CLI not found (command: agent)
+  ✗ GLM: Failed
+    ↳ GLM: All 2 attempts failed: 401 Unauthorized
+```
+
+If nothing diagnostic was captured, it says so plainly ("no output and no error captured — CLI likely missing or not authenticated").
+
+### `doctor.sh --live`
+
+The normal `doctor.sh` only checks that a consultant's CLI is *installed* (`--version`). `--live` goes further: it sends a minimal real query to each **enabled** consultant and reports which actually respond.
+
+```bash
+./scripts/doctor.sh --live
+# ✓ Gemini: responded
+# ✗ Cursor: no valid response — Cursor CLI not found (command: agent)
+# ✗ Kimi: no valid response
+# Live result: 1 responding, 2 failing
+```
+
+It's opt-in (one small query per consultant) and honors `DOCTOR_LIVE_TIMEOUT` (default 45s). Failures are reported as `doctor` issues (exit 1).
+
+## Breaking Changes
+
+None.
+
+## Not fixable in code
+
+`--live` and the surfaced reasons *diagnose* a consultant that's missing or unauthenticated — but installing/authenticating that CLI is up to you. Cold-start/warm-up retry effects are also environmental.
+
+## Upgrade Guide
+
+```bash
+cd ~/.claude/skills/ai-consultants && git pull   # or: npx ai-consultants@latest install
+```
+
+## Commits
+
+- `_______` feat: diagnosable consultant failures + doctor --live (observability)
+
+## Contributors
+
+- @matteoscurati

package/docs/releases/v2.19.0.md

@@ -0,0 +1,66 @@
+# Release v2.19.0
+
+**Date:** 2026-06-26
+**Type:** Minor — reliability (quorum grading + health gate)
+**Previous:** v2.18.0
+
+## Highlights
+
+- **A consultation that quietly ran with fewer panelists no longer looks authoritative.** It's now graded **MET / DEGRADED / FAILED**, and the report lists exactly which consultants dropped and why.
+- **Opt-in health gate** prunes non-responsive consultants *before* the run, so you don't spend the full consultation on CLIs that are installed but not authenticated.
+
+These were chosen from a multi-agent investigation of the "flaky CLI" problem; the adversarial review explicitly steered us *away* from an automatic CLI→API fallback (it would emit persona-less, confidence-5 stubs that poison the vote).
+
+## What's New
+
+### Quorum grading + Diagnosed Failures
+
+After the panel responds, the run is graded by how many consultants actually answered, relative to `QUORUM_MIN` (default 2):
+
+- **MET** — everyone responded
+- **DEGRADED** — some failed, but ≥ quorum
+- **FAILED** — below quorum
+
+The report now opens with an `Outcome:` line and, when anything dropped, a **Diagnosed Failures** table:
+
+```
+**Outcome**: DEGRADED (5/7 responded, quorum=2)
+
+## Diagnosed Failures
+| Consultant | Reason |
+|------------|--------|
+| Cursor | Cursor CLI not found (command: agent) |
+| Kimi   | no output and no error captured — CLI likely missing or not authenticated |
+```
+
+`QUORUM_ACTION=stop` aborts a below-quorum run; the default `warn` continues with the banner so nothing silently passes as a full-panel result.
+
+### Health gate (opt-in)
+
+```bash
+ENABLE_HEALTH_GATE=true ai-consultants "your question"
+```
+
+Pings every selected consultant **in parallel** with a tiny real query (`HEALTH_GATE_TIMEOUT`, default 30s) and drops the ones that don't respond before the real run starts — catching installed-but-unauthenticated CLIs and stale installs. It prunes; it does not switch transport. Custom API agents without a query script are kept (not probeable).
+
+## Breaking Changes
+
+None. Both features are additive; `QUORUM_ACTION` defaults to `warn` (banner only) and the health gate is off by default.
+
+## Not included (deliberately)
+
+The investigation rejected, for now: automatic CLI→API fallback (vote-poisoning persona loss), cold-start retry-timeout escalation (stretches the whole round's worst case), warm-up calls (extra billing/OAuth contention), and a transport-abstraction circuit breaker (racy on-disk state).
+
+## Upgrade Guide
+
+```bash
+cd ~/.claude/skills/ai-consultants && git pull   # or: npx ai-consultants@latest install
+```
+
+## Commits
+
+- `_______` feat: quorum grading + diagnosed-failures report + opt-in health gate
+
+## Contributors
+
+- @matteoscurati

package/docs/releases/v2.19.1.md

@@ -0,0 +1,44 @@
+# Release v2.19.1
+
+**Date:** 2026-06-27
+**Type:** Patch — code-review cleanup for v2.19.0
+**Previous:** v2.19.0
+
+## Highlights
+
+- **Fixes the "Diagnosed Failures" report table breaking** when a consultant's error reason contains a `|`.
+- **The opt-in health gate no longer wastes a ping** on consultants whose answer is already cached.
+
+## What's New
+
+### Report table escapes pipes
+
+A failure reason containing a `|` (e.g. a CLI error that mentions a piped command) used to mangle the markdown row in the **Diagnosed Failures** table. The reason is now escaped (`|` → `\|`) in table mode. (This was a rendering bug, not a security issue — the text is your own CLI's stderr.)
+
+### Cache-aware health gate
+
+When `ENABLE_HEALTH_GATE=true` and semantic caching is on, a consultant whose response is already cached is kept **without** a ping — Round 1 would serve it for free, so probing it would defeat the cache. The gate only pings consultants it would actually run live.
+
+### Internal cleanup (from `/code-review max`)
+
+- A single `render_diagnosed_failure` helper now renders both the console log and the report table — the `name|reason` decode lives in one place.
+- `ping_consultant` takes the already-lowercased consultant id (callers compute it anyway), removing a redundant `to_lower` fork per consultant.
+- The health gate's inherent pre-run startup latency (it's serial with the consultation by design, up to `HEALTH_GATE_TIMEOUT`) is now documented in `config.sh`.
+
+## Breaking Changes
+
+None.
+
+## Upgrade Guide
+
+```bash
+cd ~/.claude/skills/ai-consultants && git pull   # or: npx ai-consultants@latest install
+```
+
+## Commits
+
+- `_______` fix: escape pipes in diagnosed-failures table + cache-aware health gate + review cleanup
+
+## Contributors
+
+- @matteoscurati

package/docs/releases/v2.19.2.md

@@ -0,0 +1,54 @@
+# Release v2.19.2
+
+**Date:** 2026-07-11
+**Type:** Patch — cost-tracking resilience (fresh-install fix + concurrency + corruption self-heal)
+**Previous:** v2.19.1
+
+## Highlights
+
+- **Fresh-install cost tracking is fixed** — sessions no longer fail to record their cost the first time you run the tool.
+- **A corrupt `costs.json` now self-heals** instead of permanently wedging every future cost update.
+- **Concurrent consultations can't lose cost records** — the update is serialized and uses a unique temp file.
+- **Cost bookkeeping can never abort a run** — every failure path degrades to a warning.
+- No configuration changes; no impact on existing installs whose data dir already exists.
+
+## What's New
+
+### Cost tracking resilience (`lib/costs.sh`)
+
+`track_session_cost` records each consultation's cost to `costs.json` under the XDG data dir (`~/.local/share/ai-consultants/`). Four problems are fixed:
+
+| Problem | Before | After |
+|---|---|---|
+| **Fresh install** | Wrote to `costs.json` without creating its parent dir → every session failed with "No such file or directory"; cost tracking silently never accumulated | `mkdir -p` the parent dir on demand |
+| **Corrupt file** | A malformed `costs.json` failed every future `jq` update, forever | Detected via `jq empty`, moved aside to `costs.json.corrupt`, and reset |
+| **Concurrency** | Unguarded read-modify-write; parallel runs could interleave and lose records | Serialized with a portable `mkdir` lock (5s bounded wait, then proceeds unlocked) |
+| **Temp file** | Fixed `.tmp` sibling shared across runs → clobbered writes / failed `mv` | Unique `mktemp` temp file per write |
+
+All failure paths now log a warning and return success: cost bookkeeping is best-effort and can never abort a consultation. This matters because the caller in `consult_all.sh` runs under `set -e` *after* every consultant has already been queried and billed — a bookkeeping hiccup must not throw away the run's results.
+
+The function is split into an outer `track_session_cost` (directory creation + lock management) and an inner `_track_session_cost_update` (the read-modify-write, run with the lock held).
+
+### Tests
+
+New `test_cost_tracking_resilience` in `scripts/test_suite.sh` (5 assertions, wired into `main()`) covers the fresh-install path (costs.json created under a missing nested parent dir), cross-session accumulation (0.25 → 0.75), and the corrupt-file self-heal including the `.corrupt` backup. All 8 suites pass; shellcheck clean.
+
+## Breaking Changes
+
+None. Backwards-compatible. Installs whose data dir already exists see no behavioral change.
+
+## Upgrade Guide
+
+```bash
+cd ~/.claude/skills/ai-consultants && git pull   # or: npx ai-consultants@latest install
+```
+
+No configuration changes required.
+
+## Commits
+
+- `_______` fix(costs): harden track_session_cost against fresh-install, concurrency, and corruption
+
+## Contributors
+
+- @matteoscurati

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-consultants",
-  "version": "2.17.2",
+  "version": "2.19.2",
   "description": "A harness for every question - a panel of up to 15 AI models that picks its own deliberation strategy per question (convergence, adversarial verification, tournament) and checks its work before answering",
   "bin": {
     "ai-consultants": "bin/ai-consultants"

package/scripts/config.sh

@@ -574,6 +574,35 @@ CONVERGENCE_STALL_EPSILON="${CONVERGENCE_STALL_EPSILON:-5}"
 # and runs anonymous peer review as a refutation gate before synthesis.
 ENABLE_ADVERSARIAL_VERIFY="${ENABLE_ADVERSARIAL_VERIFY:-true}"
 
+# =============================================================================
+# QUORUM GRADING (v2.19.0)
+# =============================================================================
+# Grade the consultation outcome by the number of consultants that actually
+# responded, so a run that silently shrank to a few panelists is reported as
+# DEGRADED/FAILED instead of presenting as authoritative. Failures are listed
+# with their diagnosed reason (from the v2.18.0 .err capture) in the report.
+# Minimum successful responses below which the outcome is FAILED.
+QUORUM_MIN="${QUORUM_MIN:-2}"
+# warn (default: banner + continue) | stop (abort if below quorum)
+QUORUM_ACTION="${QUORUM_ACTION:-warn}"
+
+# =============================================================================
+# HEALTH GATE (v2.19.0, opt-in)
+# =============================================================================
+# Before the consultation, send a cheap real "ping" query to each selected
+# consultant in parallel and drop the non-responsive ones (installed-but-
+# unauthenticated CLIs, stale installs), so the panel only spends the full run
+# on consultants that actually work. Opt-in: it costs one tiny extra query per
+# consultant. Prunes; it does not switch transport. Consultants whose response
+# is already cached are kept WITHOUT a ping (cache-aware).
+#
+# TRADE-OFF: the gate runs BEFORE Round 1 and is serial with it (a pre-flight
+# probe can't overlap the real run by definition), so it adds up to
+# HEALTH_GATE_TIMEOUT of blocking startup latency when a consultant is slow/dead.
+# That's the cost of pruning up front; keep it opt-in and tune the timeout.
+ENABLE_HEALTH_GATE="${ENABLE_HEALTH_GATE:-false}"
+HEALTH_GATE_TIMEOUT="${HEALTH_GATE_TIMEOUT:-30}"
+
 # --- Debate Optimization ---
 # Optimize debate rounds for token efficiency: skip debate when consensus is
 # already high (confidence spread below DEBATE_CONFIDENCE_SPREAD_THRESHOLD).
@@ -858,4 +887,4 @@ EOF
 # VERSION
 # =============================================================================
 
-AI_CONSULTANTS_VERSION="2.17.2"
+AI_CONSULTANTS_VERSION="2.19.2"

package/scripts/consult_all.sh

@@ -369,6 +369,45 @@ else
     _discover_custom_api_agents
 fi
 
+# --- Health Gate (v2.19.0, opt-in) ---
+# Ping each selected consultant in parallel and drop the non-responsive ones
+# (installed-but-unauthenticated CLIs, stale installs) BEFORE the real run, so
+# the quorum/budget checks below see the genuinely-working panel. Opt-in: costs
+# one tiny extra query per consultant. Prunes; does not switch transport.
+if [[ "${ENABLE_HEALTH_GATE:-false}" == "true" && ${#SELECTED_CONSULTANTS[@]} -gt 0 ]]; then
+    HG_DIR=$(mktemp -d)
+    declare -a HG_PIDS=() HG_NAMES=() RESPONSIVE=()
+    for _c in "${SELECTED_CONSULTANTS[@]}"; do
+        _cl=$(to_lower "$_c")
+        # Cache-aware: a consultant whose response is already cached costs nothing
+        # in Round 1 (check_cache short-circuits), so keep it without a billed ping.
+        if is_cache_enabled && [[ -n "$(check_cache "$QUERY" "$QUESTION_CATEGORY" "$_cl" "$CONTEXT_FILE" 2>/dev/null || echo "")" ]]; then
+            RESPONSIVE+=("$_c")
+            log_debug "  Health gate: $_c cached, kept (not pinged)"
+            continue
+        fi
+        ( ping_consultant "$_cl" "$SCRIPT_DIR" "${HEALTH_GATE_TIMEOUT:-30}" "$HG_DIR/${_cl}.json" "$HG_DIR/${_cl}.err" ) &
+        HG_PIDS+=("$!"); HG_NAMES+=("$_c")
+    done
+    [[ ${#HG_PIDS[@]} -gt 0 ]] && log_info "Health gate: pinging ${#HG_PIDS[@]} consultants in parallel..."
+    for _i in "${!HG_PIDS[@]}"; do
+        if wait "${HG_PIDS[$_i]}" 2>/dev/null; then _rc=0; else _rc=$?; fi
+        _nm="${HG_NAMES[$_i]}"
+        if [[ $_rc -eq 0 || $_rc -eq 2 ]]; then
+            RESPONSIVE+=("$_nm")
+            [[ $_rc -eq 2 ]] && log_debug "  Health gate: $_nm not probeable (no query script), kept"
+        else
+            _cl=$(to_lower "$_nm")
+            _reason=$(get_consultant_error_reason "$HG_DIR/${_cl}.err")
+            log_warn "  Health gate dropped $_nm${_reason:+: $_reason}"
+        fi
+    done
+    rm -rf "$HG_DIR"
+    _hg_total=${#SELECTED_CONSULTANTS[@]}
+    SELECTED_CONSULTANTS=(${RESPONSIVE[@]+"${RESPONSIVE[@]}"})
+    log_info "Health gate: ${#SELECTED_CONSULTANTS[@]} of ${_hg_total} usable"
+fi
+
 if [[ ${#SELECTED_CONSULTANTS[@]} -eq 0 ]]; then
     log_error "No consultant enabled or selected"
     exit 1
@@ -421,6 +460,9 @@ declare -a CACHE_HITS=()
 for consultant in "${SELECTED_CONSULTANTS[@]}"; do
     consultant_lower=$(to_lower "$consultant")
     local_output_file="$OUTPUT_DIR/${consultant_lower}.json"
+    # Capture each consultant's stderr so a failure (auth/CLI-missing/transient)
+    # can be surfaced instead of silently discarded (was `2>&1` to /dev/null).
+    local_err_file="$OUTPUT_DIR/${consultant_lower}.err"
     OUTPUT_FILES+=("$local_output_file")
     NAMES+=("$consultant")
 
@@ -456,21 +498,21 @@ for consultant in "${SELECTED_CONSULTANTS[@]}"; do
                     apply_launch_stagger
                     export "$model_var=$local_model"
                     "$query_script" "" "$CONTEXT_FILE" "$local_output_file"
-                ) > /dev/null 2>&1 &
+                ) > /dev/null 2>"$local_err_file" &
                 PIDS+=($!)
                 update_progress "$consultant" 10 "running"
                 continue
             fi
         fi
         # Standard launch (inherits current environment models)
-        ( apply_launch_stagger; "$query_script" "" "$CONTEXT_FILE" "$local_output_file" ) > /dev/null 2>&1 &
+        ( apply_launch_stagger; "$query_script" "" "$CONTEXT_FILE" "$local_output_file" ) > /dev/null 2>"$local_err_file" &
     else
         # Fallback: custom API agent via generic API query
         (
             apply_launch_stagger
             source "$SCRIPT_DIR/lib/api_query.sh"
             run_api_consultant "$consultant" "" "$CONTEXT_FILE" "$local_output_file"
-        ) > /dev/null 2>&1 &
+        ) > /dev/null 2>"$local_err_file" &
     fi
 
     PIDS+=($!)
@@ -482,10 +524,25 @@ if [[ ${#CACHE_HITS[@]} -gt 0 ]]; then
     log_info "Cache hits: ${CACHE_HITS[*]}"
 fi
 
+# Surface the captured stderr reason for a consultant that produced no usable
+# output, so the user sees WHY (auth error, CLI missing, transient) instead of a
+# bare "Failed". Derives the .err path from the .json output path.
+_surface_consultant_error() {
+    local cname="$1" out="$2"
+    local ef="${out%.json}.err"
+    local reason
+    reason=$(get_consultant_error_reason "$ef")
+    local detail="${reason:-no output and no error captured — CLI likely missing or not authenticated (run doctor.sh --live)}"
+    log_warn "    ↳ ${cname}: ${detail}"
+    # Record for the report's "Diagnosed Failures" section (quorum grading, v2.19.0).
+    DIAGNOSED_FAILURES+=("${cname}|${detail}")
+}
+
 # --- Wait and Collect Results ---
 log_info "Waiting for responses from ${#PIDS[@]} consultants..."
 
 declare -a RESULTS=()
+declare -a DIAGNOSED_FAILURES=()
 SUCCESS_COUNT=0
 
 for i in "${!PIDS[@]}"; do
@@ -521,11 +578,13 @@ for i in "${!PIDS[@]}"; do
             fi
         else
             log_warn "  $name: Empty response"
+            _surface_consultant_error "$name" "$output_file"
             RESULTS+=("$name:EMPTY")
             update_progress "$name" 100 "failed"
         fi
     else
         log_error "  $name: Failed"
+        _surface_consultant_error "$name" "$output_file"
         RESULTS+=("$name:FAILED")
         update_progress "$name" 100 "failed"
     fi
@@ -533,6 +592,27 @@ done
 
 echo "" >&2
 
+# --- Quorum Grading (v2.19.0) ---
+# Grade the run by how many consultants actually responded, so a silently-shrunk
+# panel is reported as DEGRADED/FAILED instead of presenting as authoritative.
+QUORUM_ATTEMPTED=${#PIDS[@]}
+QUORUM_MIN_EFF="${QUORUM_MIN:-2}"
+QUORUM_OUTCOME=$(grade_quorum "$SUCCESS_COUNT" "$QUORUM_ATTEMPTED" "$QUORUM_MIN_EFF")
+
+if [[ "$QUORUM_OUTCOME" == "DEGRADED" ]]; then
+    log_warn "Quorum: DEGRADED — ${SUCCESS_COUNT}/${QUORUM_ATTEMPTED} consultants responded"
+elif [[ "$QUORUM_OUTCOME" == "FAILED" ]]; then
+    log_error "Quorum: FAILED — only ${SUCCESS_COUNT}/${QUORUM_ATTEMPTED} responded (need >= ${QUORUM_MIN_EFF})"
+    if [[ ${#DIAGNOSED_FAILURES[@]} -gt 0 ]]; then
+        log_error "Diagnosed failures:"
+        for _df in "${DIAGNOSED_FAILURES[@]}"; do log_error "$(render_diagnosed_failure "$_df")"; done
+    fi
+    if [[ "${QUORUM_ACTION:-warn}" == "stop" ]]; then
+        log_error "Aborting below quorum (QUORUM_ACTION=stop). Set QUORUM_ACTION=warn to continue."
+        exit 1
+    fi
+fi
+
 # --- Budget Check: After Round 1 ---
 CURRENT_COST=0
 if [[ "$ENABLE_COST_TRACKING" == "true" && $SUCCESS_COUNT -gt 0 ]]; then
@@ -792,9 +872,29 @@ REPORT_FILE="$OUTPUT_DIR/report.md"
     echo "**Directory**: $(pwd)"
     echo "**Version**: AI Consultants v${AI_CONSULTANTS_VERSION}"
     echo "**Category**: $QUESTION_CATEGORY"
-    echo "**Successes**: $SUCCESS_COUNT/${#PIDS[@]} consultants"
+    echo "**Outcome**: ${QUORUM_OUTCOME:-MET} (${SUCCESS_COUNT}/${QUORUM_ATTEMPTED:-${#PIDS[@]}} responded, quorum=${QUORUM_MIN_EFF:-2})"
     echo "**Consensus**: ${CONSENSUS_SCORE}% ($CONSENSUS_LEVEL)"
     echo ""
+
+    # Diagnosed failures (quorum grading, v2.19.0) — surface WHY consultants
+    # dropped, so a degraded panel is visible instead of silently authoritative.
+    if [[ ${#DIAGNOSED_FAILURES[@]} -gt 0 ]]; then
+        echo "## Diagnosed Failures"
+        echo ""
+        if [[ "${QUORUM_OUTCOME:-MET}" == "FAILED" ]]; then
+            echo "> ⚠️ Below quorum (${SUCCESS_COUNT}/${QUORUM_MIN_EFF:-2}). Treat the recommendation as low-confidence."
+        elif [[ "${QUORUM_OUTCOME:-MET}" == "DEGRADED" ]]; then
+            echo "> Some consultants did not respond — the panel ran with ${SUCCESS_COUNT}/${QUORUM_ATTEMPTED:-${#PIDS[@]}}."
+        fi
+        echo ""
+        echo "| Consultant | Reason |"
+        echo "|------------|--------|"
+        for _df in "${DIAGNOSED_FAILURES[@]}"; do
+            echo "$(render_diagnosed_failure "$_df" table)"
+        done
+        echo ""
+    fi
+
     echo "---"
     echo ""
 

package/scripts/doctor.sh

@@ -32,6 +32,7 @@ VERBOSE=false
 QUICK_MODE=false
 SUGGEST_CONFIG=false
 SUGGEST_PRESET=false
+LIVE_MODE=false
 QUESTION=""
 
 while [[ $# -gt 0 ]]; do
@@ -60,6 +61,10 @@ while [[ $# -gt 0 ]]; do
             SUGGEST_PRESET=true
             shift
             ;;
+        --live)
+            LIVE_MODE=true
+            shift
+            ;;
         --question)
             QUESTION="${2:-}"
             shift 2
@@ -78,6 +83,9 @@ while [[ $# -gt 0 ]]; do
             echo "  --suggest-config   Print recommended ENABLE_* configuration"
             echo "  --suggest-preset   Recommend preset + strategy for a question"
             echo "  --question \"...\"   Question text for --suggest-preset"
+            echo "  --live             Send a real ping query to each enabled consultant"
+            echo "                     (catches installed-but-unauthenticated CLIs that the"
+            echo "                     static check reports as healthy). Costs a tiny query each."
             exit 0
             ;;
         *)
@@ -1080,6 +1088,62 @@ suggest_preset() {
 # MAIN
 # =============================================================================
 
+# --- Live consultant ping (--live) ---------------------------------------------
+# The static checks above only verify a CLI is installed (`--version`), so they
+# report a consultant as healthy even when its CLI errors at query time (e.g.
+# not authenticated). This sends a real, minimal query to each ENABLED consultant
+# and reports pass/fail with the captured error reason. Opt-in (costs one tiny
+# query per consultant).
+check_live_consultants() {
+    print_section "Live Consultant Check (real ping query)"
+
+    local timeout_s="${DOCTOR_LIVE_TIMEOUT:-45}"
+    local tmpdir
+    tmpdir=$(mktemp -d)
+
+    # name|enable-flag — mirrors consult_all's selection set.
+    local entries=(
+        "Gemini|ENABLE_GEMINI"   "Codex|ENABLE_CODEX"   "Mistral|ENABLE_MISTRAL"
+        "Kilo|ENABLE_KILO"       "Cursor|ENABLE_CURSOR" "Aider|ENABLE_AIDER"
+        "Amp|ENABLE_AMP"         "Kimi|ENABLE_KIMI"     "Claude|ENABLE_CLAUDE"
+        "Qwen3|ENABLE_QWEN3"     "GLM|ENABLE_GLM"       "Grok|ENABLE_GROK"
+        "DeepSeek|ENABLE_DEEPSEEK" "MiniMax|ENABLE_MINIMAX" "Ollama|ENABLE_OLLAMA"
+    )
+
+    local live_pass=0 live_fail=0 e name flagvar lower out err reason rc
+    for e in "${entries[@]}"; do
+        name="${e%%|*}"; flagvar="${e##*|}"
+        if [[ "${!flagvar:-false}" != "true" ]]; then
+            [[ "$VERBOSE" == "true" ]] && _print "  ○ $name: disabled"
+            continue
+        fi
+        if should_skip_consultant "$name" 2>/dev/null; then
+            _print "  ○ $name: excluded (invoking agent)"
+            continue
+        fi
+        lower=$(to_lower "$name")
+        out="$tmpdir/${lower}.json"; err="$tmpdir/${lower}.err"
+        if ping_consultant "$lower" "$SCRIPT_DIR" "$timeout_s" "$out" "$err"; then rc=0; else rc=$?; fi
+        if [[ $rc -eq 2 ]]; then
+            _print "  ✗ $name: query script missing"
+            add_issue "live" "$name query script missing" "reinstall the skill"
+            check_fail; live_fail=$((live_fail + 1))
+        elif [[ $rc -eq 0 ]]; then
+            _print "  ✓ $name: responded"
+            check_pass; live_pass=$((live_pass + 1))
+        else
+            reason=$(get_consultant_error_reason "$err")
+            _print "  ✗ $name: no valid response${reason:+ — $reason}"
+            add_issue "live" "$name failed live ping${reason:+: $reason}" "check that the $name CLI is installed and authenticated"
+            check_fail; live_fail=$((live_fail + 1))
+        fi
+    done
+
+    rm -rf "$tmpdir"
+    _print ""
+    _print "  Live result: ${live_pass} responding, ${live_fail} failing"
+}
+
 main() {
     print_header
     check_dependencies
@@ -1112,4 +1176,11 @@ if [[ "$SUGGEST_PRESET" == "true" ]]; then
     exit 0
 fi
 
+if [[ "$LIVE_MODE" == "true" ]]; then
+    print_header
+    check_live_consultants
+    print_summary
+    [[ ${#ISSUES[@]} -gt 0 ]] && exit 1 || exit 0
+fi
+
 main

package/scripts/lib/common.sh

@@ -192,11 +192,17 @@ run_query() {
         local error_msg=""
         [[ -f "$error_file" ]] && error_msg=$(head -5 "$error_file" 2>/dev/null)
 
+        # First line of the CLI's own stderr — the actual reason (auth error,
+        # command not found, etc.). Kept for the final failure message so it
+        # reaches the orchestrator's captured stderr (the per-CLI error_file is a
+        # mktemp path the caller can't locate).
+        local error_first=""
+        [[ -n "$error_msg" ]] && error_first=$(printf '%s\n' "$error_msg" | grep -v '^[[:space:]]*$' | head -1 | cut -c1-200)
+
         if [[ $exit_code -eq 124 ]]; then
             log_warn "[$consultant_name] Timeout after ${timeout_seconds}s"
         else
-            log_warn "[$consultant_name] Error (code: $exit_code)"
-            [[ -n "$error_msg" ]] && log_debug "Details: $error_msg"
+            log_warn "[$consultant_name] Error (code: $exit_code)${error_first:+: $error_first}"
         fi
 
         ((attempt++)) || true
@@ -206,7 +212,7 @@ run_query() {
         fi
     done
 
-    log_error "[$consultant_name] All $MAX_RETRIES attempts failed"
+    log_error "[$consultant_name] All $MAX_RETRIES attempts failed${error_first:+: $error_first}"
     return 1
 }
 
@@ -923,6 +929,76 @@ build_error_response() {
 # fallback-only: if the input already parses as JSON it is returned unchanged
 # (a real fence makes the text invalid JSON, so the gate reliably detects it).
 # Usage: cleaned=$(strip_json_fence "$raw")
+# Extract a concise, ANSI-stripped failure reason from a consultant's captured
+# stderr (.err) file, for surfacing WHY a consultant produced no output (auth
+# error, CLI not installed, transient init failure, ...) instead of a bare
+# "Failed". Prefers an explicit error-ish line; falls back to the last non-empty
+# line. Returns empty string if the file is missing/empty.
+# Usage: reason=$(get_consultant_error_reason "$err_file")
+get_consultant_error_reason() {
+    local ef="$1"
+    [[ -s "$ef" ]] || return 0
+    local esc cleaned line
+    esc=$(printf '\033')
+    # Strip ANSI, blank lines, AND our own orchestration status logs first — those
+    # carry no failure info and would otherwise be mis-picked (e.g. the
+    # "Consulting X (timeout: 180s...)" header matches the 'timeout' pattern below).
+    cleaned=$(sed "s/${esc}\[[0-9;]*m//g" "$ef" 2>/dev/null \
+        | grep -v '^[[:space:]]*$' \
+        | grep -ivE '\[INFO\].*(Consulting|Response received|Waiting .* before|Attempt [0-9]|Querying)')
+    # Prefer a line that names an actual error; else the last remaining line.
+    line=$(printf '%s\n' "$cleaned" | grep -iE 'error|fail|not found|no such|denied|unauthor|invalid|timed? ?out|missing|command not found|exit code' | tail -1)
+    [[ -z "$line" ]] && line=$(printf '%s\n' "$cleaned" | tail -1)
+    printf '%s' "$line" | cut -c1-200
+}
+
+# Render one DIAGNOSED_FAILURES entry ("name|reason") for a given surface.
+# Single source of the "name|reason" decode (used by both the console log and the
+# report table), and the table mode escapes any '|' in the reason so a CLI error
+# containing a pipe doesn't mangle the markdown row.
+# Usage: render_diagnosed_failure "<name>|<reason>" [console|table]
+render_diagnosed_failure() {
+    local entry="$1" mode="${2:-console}" name reason
+    name="${entry%%|*}"
+    reason="${entry#*|}"
+    if [[ "$mode" == "table" ]]; then
+        printf '| %s | %s |' "$name" "${reason//|/\\|}"
+    else
+        printf '  - %s: %s' "$name" "$reason"
+    fi
+}
+
+# Grade a consultation by how many consultants responded (v2.19.0).
+# Usage: grade_quorum <success_count> <attempted_count> <min_quorum>
+# Echoes: FAILED (< min) | DEGRADED (>= min but some failed) | MET (all responded)
+grade_quorum() {
+    local success="$1" attempted="$2" min="$3"
+    if [[ "$success" -lt "$min" ]]; then
+        echo "FAILED"
+    elif [[ "$success" -lt "$attempted" ]]; then
+        echo "DEGRADED"
+    else
+        echo "MET"
+    fi
+}
+
+# Send a trivial real "ping" query to a consultant's query script and report
+# whether it produced a structurally valid response. Shared by `doctor --live`
+# and the consult_all health gate. Persona is disabled (we only need a parseable
+# envelope, not a full analysis). Caller provides scratch out/err paths.
+# <id> is the ALREADY-lowercased consultant id. Callers compute the lowercase
+# form anyway (for the out/err paths), so we take it directly instead of forking
+# to_lower again per consultant.
+# Usage: ping_consultant <id> <scripts_dir> <timeout_s> <out_file> <err_file>
+# Returns: 0 = responded, 1 = failed/empty, 2 = no query script (not probeable)
+ping_consultant() {
+    local id="$1" scripts_dir="$2" timeout_s="$3" out="$4" err="$5"
+    local qs="$scripts_dir/query_${id}.sh"
+    [[ -x "$qs" ]] || return 2
+    ENABLE_PERSONA=false run_with_timeout "$timeout_s" "$qs" "Reply with exactly: OK" "" "$out" >/dev/null 2>"$err" || true
+    [[ -s "$out" ]] && jq -e '.response' "$out" >/dev/null 2>&1
+}
+
 strip_json_fence() {
     local text="$1"
     if echo "$text" | jq -e '.' > /dev/null 2>&1; then

package/scripts/lib/costs.sh

@@ -365,23 +365,80 @@ COST_TRACKING_FILE="${COST_TRACKING_FILE:-${_AI_CONSULTANTS_XDG_DATA:-/tmp/ai_co
 
 # Record session cost
 # Usage: track_session_cost <session_id> <cost>
+# Best-effort: cost tracking is bookkeeping. The caller in consult_all.sh runs
+# under set -e *after* every consultant has already been queried and billed,
+# so failures here degrade to a warning instead of aborting the run.
 track_session_cost() {
     local session_id="$1"
     local cost="$2"
+
+    # The XDG data dir may not exist yet on a fresh install — costs.json is
+    # the only artifact stored there
+    if ! mkdir -p "$(dirname "$COST_TRACKING_FILE")" 2>/dev/null; then
+        log_warn "Cost tracking skipped: cannot create $(dirname "$COST_TRACKING_FILE")"
+        return 0
+    fi
+
+    # Serialize the read-modify-write against concurrent consultations with a
+    # portable mkdir lock (flock is unavailable on macOS). Bounded wait, then
+    # proceed unlocked: bookkeeping must never block or abort the run.
+    local lock_dir="${COST_TRACKING_FILE}.lock" locked=false _i
+    for _i in {1..50}; do
+        if mkdir "$lock_dir" 2>/dev/null; then locked=true; break; fi
+        sleep 0.1
+    done
+    if [[ "$locked" != "true" ]]; then
+        log_warn "Cost tracking lock busy for 5s (stale ${lock_dir}?), proceeding unlocked"
+    fi
+
+    _track_session_cost_update "$session_id" "$cost" || true
+
+    if [[ "$locked" == "true" ]]; then
+        rmdir "$lock_dir" 2>/dev/null || true
+    fi
+    return 0
+}
+
+# Inner update for track_session_cost — runs with the lock held.
+# Never propagates failure; logs a warning and returns instead.
+_track_session_cost_update() {
+    local session_id="$1"
+    local cost="$2"
     local timestamp=$(date -Iseconds)
 
-    # Create file if it doesn't exist
+    # A corrupt file (truncated write, interleaved concurrent update) would
+    # fail every future jq update and never self-heal: set it aside and reset
+    if [[ -f "$COST_TRACKING_FILE" ]]; then
+        if ! jq empty "$COST_TRACKING_FILE" 2>/dev/null; then
+            log_warn "Cost tracking file corrupt, resetting (backup: ${COST_TRACKING_FILE}.corrupt)"
+            mv -f "$COST_TRACKING_FILE" "${COST_TRACKING_FILE}.corrupt" 2>/dev/null || true
+        fi
+    fi
     if [[ ! -f "$COST_TRACKING_FILE" ]]; then
-        echo '{"sessions": [], "total_cost": 0}' > "$COST_TRACKING_FILE"
+        if ! { echo '{"sessions": [], "total_cost": 0}' > "$COST_TRACKING_FILE"; } 2>/dev/null; then
+            log_warn "Cost tracking skipped: cannot write $COST_TRACKING_FILE"
+            return 0
+        fi
     fi
 
-    # Add session and update total
-    jq --arg id "$session_id" \
-       --arg cost "$cost" \
-       --arg ts "$timestamp" \
-       '.sessions += [{id: $id, cost: ($cost | tonumber), timestamp: $ts}] | .total_cost += ($cost | tonumber)' \
-       "$COST_TRACKING_FILE" > "${COST_TRACKING_FILE}.tmp" && \
-       mv "${COST_TRACKING_FILE}.tmp" "$COST_TRACKING_FILE"
+    # Unique temp file: even an unlocked writer must not share a fixed .tmp
+    # sibling with other runs (lost records, failed mv)
+    local tmp_file
+    if ! tmp_file=$(mktemp "${COST_TRACKING_FILE}.XXXXXX" 2>/dev/null); then
+        log_warn "Cost tracking skipped: cannot create temp file for $COST_TRACKING_FILE"
+        return 0
+    fi
+    if jq --arg id "$session_id" \
+          --arg cost "$cost" \
+          --arg ts "$timestamp" \
+          '.sessions += [{id: $id, cost: ($cost | tonumber), timestamp: $ts}] | .total_cost += ($cost | tonumber)' \
+          "$COST_TRACKING_FILE" > "$tmp_file" 2>/dev/null; then
+        mv -f "$tmp_file" "$COST_TRACKING_FILE" 2>/dev/null || rm -f "$tmp_file"
+    else
+        rm -f "$tmp_file"
+        log_warn "Cost tracking update failed for session $session_id"
+    fi
+    return 0
 }
 
 # Get total tracked cost

package/scripts/test_suite.sh

@@ -1011,6 +1011,43 @@ test_cost_per1k_contract() {
     if [[ -n "$saved" ]]; then COST_RATES_FILE="$saved"; else unset COST_RATES_FILE; fi
 }
 
+# Fresh-install regression: track_session_cost wrote to $COST_TRACKING_FILE
+# without creating its parent directory, so on a fresh install (XDG data dir
+# ~/.local/share/ai-consultants absent) every session ended with
+# "No such file or directory" and cumulative cost tracking was lost.
+# Also covers the corrupt-file self-heal path (a bad costs.json previously
+# wedged every future update).
+test_cost_tracking_resilience() {
+    suite "costs.sh: track_session_cost resilience (fresh-install + corrupt-file)"
+
+    local saved="$COST_TRACKING_FILE"
+    COST_TRACKING_FILE="$TEST_TMPDIR/cost_tracking/nonexistent/nested/costs.json"
+
+    # Calls are guarded with || true: a recurrence of the guarded bugs must
+    # surface as FAIL assertions below, not abort the suite under set -e
+    track_session_cost "test_session_1" "0.25" 2>/dev/null || true
+
+    # 0.25 and 0.5 are exact in binary floating point, so the jq sum is exact
+    assert_exit_code_success "costs.json created under a missing parent dir" test -f "$COST_TRACKING_FILE"
+    assert_equals "0.25" "$(get_total_tracked_cost)" "session cost recorded on fresh install"
+
+    # Second call must append, not re-initialize
+    track_session_cost "test_session_2" "0.5" 2>/dev/null || true
+    assert_equals "0.75" "$(get_total_tracked_cost)" "second session accumulates on existing file"
+
+    # A corrupt costs.json must be set aside and reset, not wedge every
+    # future update. The dir is created explicitly: this block tests the
+    # self-heal path, not dir creation, and the setup write must not be able
+    # to abort the suite under set -e
+    mkdir -p "$(dirname "$COST_TRACKING_FILE")"
+    echo '{"sessions": [' > "$COST_TRACKING_FILE"
+    track_session_cost "test_session_3" "0.5" 2>/dev/null || true
+    assert_equals "0.5" "$(get_total_tracked_cost)" "corrupt costs.json is reset and the new session recorded"
+    assert_exit_code_success "corrupt file preserved as .corrupt backup" test -f "${COST_TRACKING_FILE}.corrupt"
+
+    COST_TRACKING_FILE="$saved"
+}
+
 # =============================================================================
 # TESTS: costs.sh - Cost formatting
 # =============================================================================
@@ -1616,6 +1653,7 @@ main() {
     test_cost_rates
     test_cost_estimation
     test_cost_per1k_contract
+    test_cost_tracking_resilience
     test_cost_formatting
     test_budget_checking
     test_query_complexity