fix(profile): recommender stops pushing trims + doctor flags explicit trimmed profile (26b)

Root of the recurring 'read_range/read_for_edit doesn't exist' pain: the
profile-recommender suggested TOKEN_PILOT_PROFILE=nav (or edit) for read-heavy
usage and printed an 'apply to .mcp.json' snippet. Users applied it; the next
edit session then hit trimmed edit-tools the rules/hooks still demand → dead
'No such tool available' → Read fallback. Past usage doesn't predict future
edits, and this contradicts the v0.45.0 full default (trimming is
penny-wise-pound-foolish).

- recommendProfile now always recommends ; the nav/edit reasons explain
  why trimming is risky (minimal stays a self-serve, warned opt-in).
- formatRecommendation no longer prints the 'apply nav/edit to .mcp.json' trap.
- token-pilot doctor v0.44.0

Install mode:   npm / npx
Node.js:        v20.9.0 ✓
config:         /Users/mhershahinyan/www/token-pilot/.token-pilot.json ✓
git repo:       yes ✓

── token-pilot ──
  installed:    0.44.0
  latest:       0.44.0 ✓ (up to date)

── ast-index ──
  installed:    3.47.0 (bundled: /Users/mhershahinyan/.nvm/versions/node/v20.9.0/lib/node_modules/@ast-index/cli/bin/ast-index)
  latest:       3.47.1 (update available!)
  run:          npx token-pilot install-ast-index
  auto-update:  disabled (set updates.autoUpdate=true in .token-pilot.json)

── context-mode ──
  detected:     no
  setup:        npx token-pilot init

── Claude Code env knobs (savings tips) ──
  ⚠ CLAUDE_CODE_SUBAGENT_MODEL not set to haiku — add `"CLAUDE_CODE_SUBAGENT_MODEL": "haiku"` under `env` in ~/.claude/settings.json to route subagents to Haiku (~80% cheaper).
  ⚠ MAX_THINKING_TOKENS unset (defaults to 32000) — add `"MAX_THINKING_TOKENS": "10000"` under `env` in ~/.claude/settings.json to cap hidden reasoning tokens (~70% saving).
  ⚠ CLAUDE_AUTOCOMPACT_PCT_OVERRIDE unset — add `"CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50"` under `env` in ~/.claude/settings.json to compact context earlier (healthier sessions).

── .claudeignore ──
  not present — run `npx token-pilot init` to add sensible defaults

── CLAUDE.md hygiene ──
  ⚠ /Users/mhershahinyan/www/token-pilot/CLAUDE.md has 72 non-empty lines (threshold: 60).
  This file loads into every Claude Code message — splitting into docs/*.md and loading on-demand saves tokens per turn.

── ecosystem coverage ──
  ✓ caveman        Output compression (terse-speak skill) — cuts ~75% of Claude's response prose
  ✓ context-mode   Sandbox executor — runs shell/python/js, only stdout enters context
  ○ cavemem        missing — Cross-session memory — remember context across restarts
    install:     see https://github.com/JuliusBrussee/cavemem

  token-pilot owns INPUT tokens. Each tool above owns a different
  half of a session — they do not overlap. See docs/ecosystem.md.

── statusline badge ──
  ⚠ statusline points at tp-statusline.sh directly but caveman is
    installed — switch to statusline-chain.sh so both badges show.

── runtime health ──
  errors:       3 recent (top codes):
                    3× unknown
  drill-in:     token-pilot errors --tail=20
  stale hooks:  none ✓
  tp-* agents:  25/25 ✓
  cwd:          /Users/mhershahinyan/www/token-pilot ✓ now LOUDLY flags an explicit TOKEN_PILOT_PROFILE=trim,
  names the hidden tools, and tells the user to remove it / set full.

Live-verified: doctor warns on nav. 1391 tests (recommender tests rewritten).
tsc clean. No version bump — 0.45.0.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: Shahinyanm

src/index.ts

@@ -1520,6 +1520,31 @@ export async function handleDoctor() {
     /* ignore */
   }
 
+  // ── explicit trimmed-profile warning (v0.45.0, token-pilot-26b) ──
+  // An explicit TOKEN_PILOT_PROFILE=nav|edit|minimal hides tools the rules and
+  // the pre-edit hook still reference (read_for_edit / read_range / batch),
+  // trapping edit sessions on "No such tool available". This recurred for two
+  // users. Surface it loudly so they can remove it.
+  try {
+    const raw = process.env.TOKEN_PILOT_PROFILE;
+    if (raw && raw.trim()) {
+      const { parseProfileEnv } = await import("./server/tool-profiles.js");
+      if (parseProfileEnv(raw) !== "full") {
+        console.log(
+          `⚠ TOKEN_PILOT_PROFILE=${raw.trim()} is set — a TRIMMED tool surface.\n` +
+            `  It hides read_for_edit / read_range / batch reads (and code_audit /\n` +
+            `  find_unused / test_summary) that the rules + pre-edit hook still name →\n` +
+            `  calls to them fail with "No such tool available" and the agent falls\n` +
+            `  back to raw Read/Bash.\n` +
+            `  Fix: remove "TOKEN_PILOT_PROFILE" from your .mcp.json env block (or set\n` +
+            `  it to "full"), then restart. Full is the default since v0.45.0.\n`,
+        );
+      }
+    }
+  } catch {
+    /* doctor must never crash over an optional check */
+  }
+
   // ── profile recommendation ──
   // v0.26.4 — data-driven. Reads cumulative tool-calls.jsonl and suggests
   // the narrowest TOKEN_PILOT_PROFILE that wouldn't hide any tool the

src/server/profile-recommender.ts

@@ -65,17 +65,21 @@ export function recommendProfile(
     };
   }
 
+  // v0.45.0 (token-pilot-26b) — we NO LONGER recommend trimming to nav/edit.
+  // Past tool usage doesn't predict future edits, and a trimmed profile hides
+  // read_for_edit / read_range / batch reads that the rules and the pre-edit
+  // hook still reference — so the agent calls them, hits "No such tool
+  // available", and falls back to raw Read/Bash. That recurring trap cost two
+  // users whole sessions. Full is the recommendation; minimal stays a
+  // self-serve, clearly-warned opt-in for context-critical work only.
   const allInNav = [...used].every((t) => NAV_TOOLS.has(t));
   if (allInNav) {
     return {
-      recommended: "nav",
-      reason: `Every tool you've used (${uniqueToolsSeen} distinct) is part of the nav subset. You're a read-only explorer.`,
+      recommended: "full",
+      reason: `You've used only nav-subset tools so far (${uniqueToolsSeen} distinct), but read_for_edit / read_range / batch reads — named by the rules and the pre-edit hook — live in edit/full. Stay on full so an edit doesn't hit "No such tool available". Set TOKEN_PILOT_PROFILE=minimal yourself ONLY if context is critically tight (it hides edit tools).`,
       uniqueToolsSeen,
       totalCalls,
-      wouldHide: [
-        ...[...EDIT_EXTRAS].filter((t) => !used.has(t)),
-        /* full-only — we don't enumerate here, keep the list short */
-      ],
+      wouldHide: [],
       lowConfidence: false,
     };
   }
@@ -85,8 +89,8 @@ export function recommendProfile(
   );
   if (allInEditOrBelow) {
     return {
-      recommended: "edit",
-      reason: `You use edit-preparation tools (read_for_edit, batch reads) but never reach for full-only tools like code_audit/test_summary/find_unused.`,
+      recommended: "full",
+      reason: `You use edit-prep tools but haven't reached for full-only ones (code_audit/test_summary/find_unused) yet. Stay on full — they cost ~1k tokens to advertise but trimming hides them the moment you need one, and dead calls cost more.`,
       uniqueToolsSeen,
       totalCalls,
       wouldHide: [],
@@ -120,20 +124,16 @@ export function formatRecommendation(rec: ProfileRecommendation): string {
   );
   lines.push(`  recommend:    TOKEN_PILOT_PROFILE=${rec.recommended}`);
   lines.push(`  why:          ${rec.reason}`);
-  if (rec.recommended !== "full") {
-    lines.push(
-      `  savings:      ~${rec.recommended === "nav" ? "2200 tokens (−54%)" : "1000 tokens (−25%)"} on every tools/list response`,
-    );
-    lines.push(
-      `  apply:        add "env": { "TOKEN_PILOT_PROFILE": "${rec.recommended}" } to your token-pilot entry in .mcp.json`,
-    );
-  } else if (rec.lowConfidence) {
+  // v0.45.0 (26b) — we no longer print an "apply nav/edit to .mcp.json"
+  // snippet. recommendProfile always returns `full`; the old snippet trapped
+  // users into trimming, which hid edit tools the rules reference.
+  if (rec.lowConfidence) {
     lines.push(
-      `  action:       keep default (full). Re-run \`token-pilot doctor\` after a few real sessions for a data-backed suggestion.`,
+      `  action:       keep default (full). Re-run \`token-pilot doctor\` after a few real sessions for a data-backed view.`,
     );
   } else {
     lines.push(
-      `  action:       keep default (full). You're using what you have.`,
+      `  action:       keep default (full). Trim to minimal yourself only for context-critical, read-only work.`,
     );
   }
   return lines.join("\n");

tests/server/profile-recommender.test.ts

@@ -41,22 +41,23 @@ describe("recommendProfile", () => {
     expect(r.reason).toMatch(/too small|≥20|Only/i);
   });
 
-  it("recommends `nav` when every used tool is a nav tool", () => {
-    // 30 calls, only nav tools used
+  it("recommends `full` even for nav-only usage — no trim trap (v0.45.0, 26b)", () => {
+    // 30 calls, only nav tools used — old behaviour recommended `nav`, which
+    // hid edit tools the rules reference and trapped the next edit session.
     const events = [
       ...many("smart_read", 15),
       ...many("outline", 8),
       ...many("find_usages", 7),
     ];
     const r = recommendProfile(events);
-    expect(r.recommended).toBe("nav");
+    expect(r.recommended).toBe("full");
     expect(r.lowConfidence).toBe(false);
     expect(r.uniqueToolsSeen).toBe(3);
     expect(r.totalCalls).toBe(30);
-    expect(r.reason).toMatch(/read-only|nav/i);
+    expect(r.reason).toMatch(/No such tool|stay on full|edit/i);
   });
 
-  it("recommends `edit` when user calls edit-prep tools but never full-only", () => {
+  it("recommends `full` for edit-prep usage (does not push the edit trim)", () => {
     // 25 calls: nav + read_for_edit + read_symbols, no code_audit etc
     const events = [
       ...many("smart_read", 10),
@@ -65,9 +66,9 @@ describe("recommendProfile", () => {
       ...many("smart_diff", 2),
     ];
     const r = recommendProfile(events);
-    expect(r.recommended).toBe("edit");
+    expect(r.recommended).toBe("full");
     expect(r.lowConfidence).toBe(false);
-    expect(r.reason).toMatch(/edit|read_for_edit|batch/i);
+    expect(r.reason).toMatch(/full|audit|edit-prep/i);
   });
 
   it("recommends `full` when user touches any full-only tool", () => {
@@ -94,10 +95,10 @@ describe("recommendProfile", () => {
   });
 
   it("exactly at MIN_SAMPLE_CALLS boundary behaves correctly", () => {
-    // Exactly 20 calls, all nav → should recommend nav (not lowConfidence)
+    // Exactly 20 calls, all nav → enough data, but recommends full (no trim trap)
     const events = many("smart_read", 20);
     const r = recommendProfile(events);
-    expect(r.recommended).toBe("nav");
+    expect(r.recommended).toBe("full");
     expect(r.lowConfidence).toBe(false);
   });
 
@@ -111,22 +112,24 @@ describe("recommendProfile", () => {
 });
 
 describe("formatRecommendation", () => {
-  it("nav recommendation includes env snippet to paste", () => {
+  it("never prints an apply-trim snippet — even for nav-only usage (26b)", () => {
     const rec = recommendProfile(many("smart_read", 30));
     const out = formatRecommendation(rec);
-    expect(out).toMatch(/TOKEN_PILOT_PROFILE=nav/);
-    expect(out).toMatch(/\.mcp\.json/);
-    expect(out).toMatch(/savings:/);
+    expect(out).toMatch(/TOKEN_PILOT_PROFILE=full/);
+    // The old trap: "apply: add env TOKEN_PILOT_PROFILE=nav to .mcp.json".
+    expect(out).not.toMatch(/TOKEN_PILOT_PROFILE=nav/);
+    expect(out).not.toMatch(/apply:/);
+    expect(out).not.toMatch(/savings:/);
   });
 
-  it("edit recommendation advertises the ~1000 token savings", () => {
+  it("edit-prep usage recommends full, not a trim", () => {
     const rec = recommendProfile([
       ...many("smart_read", 15),
       ...many("read_for_edit", 10),
     ]);
     const out = formatRecommendation(rec);
-    expect(out).toMatch(/TOKEN_PILOT_PROFILE=edit/);
-    expect(out).toMatch(/1000 tokens|−25%/);
+    expect(out).toMatch(/TOKEN_PILOT_PROFILE=full/);
+    expect(out).not.toMatch(/TOKEN_PILOT_PROFILE=edit/);
   });
 
   it("low-confidence reco tells user to come back later", () => {