ashlr-plugin 1.36.4 → 1.37.1

package/docs/competitive-wozcode.md

@@ -25,7 +25,7 @@ Three technical capabilities are worth adopting or beating. One pricing model (p
 | Per-tool measured savings | No (aggregate self-report) | Yes |
 | Open source + auditable | No (minified, account-gated) | Yes |
 | Opt-in telemetry | No (PostHog on-by-default, hardcoded token) | Yes |
-| Tool breadth | Narrow (deliberate) | 40 tools, 33 commands |
+| Tool breadth | Narrow (deliberate) | 40 MCP tools, 34 slash commands |
 | `llms.txt` | Yes | No |
 | Public savings leaderboard | Yes (gamified) | No |
 | Multi-surface install (VS Code / Cursor / Windows) | Yes | macOS/Linux primary |
@@ -79,7 +79,7 @@ Message these proactively in docs, README, and the benchmark blog:
 - **Open source + auditable.** WozCode is minified and requires account creation to inspect behavior. Ashlr is fully open — every tool, hook, and genome interaction is readable.
 - **Measured savings, not self-reported.** Ashlr tracks per-tool token and cost savings with a verifiable methodology. WozCode's numbers are inconsistent across their own pages.
 - **Opt-in telemetry.** WozCode ships PostHog with a hardcoded token, on by default. Ashlr's telemetry is opt-in and documented.
-- **Breadth.** 40 tools, 33 commands, genome RAG, `/ashlr-brief`, `/ashlr-efficient`. WozCode's surface is deliberately narrow.
+- **Breadth.** 40 MCP tools, 34 slash commands, genome RAG, `/ashlr-brief`, `/ashlr-efficient`. WozCode's surface is deliberately narrow.
 - **No account required.** Ashlr installs with one curl command and one slash command. WozCode requires account creation before the plugin is functional.
 
 ---

package/docs/embeddings-gateway.md

@@ -0,0 +1,39 @@
+# Embeddings through LiteLLM or another OpenAI-compatible endpoint
+
+This is opt-in and off by default. Without `ASHLR_EMBED_FORMAT=openai`, nothing changes. `ASHLR_EMBED_URL` keeps its Ollama format (`{ model, prompt }` in, `{ embedding }` out), sends no key, and the BM25 embedder still runs when no URL is set.
+
+## Turning it on
+
+```sh
+ASHLR_EMBED_FORMAT=openai
+ASHLR_EMBED_URL=http://127.0.0.1:4000/v1     # a local LiteLLM proxy, for example
+ASHLR_EMBED_MODEL=text-embedding-3-small     # whatever model name your gateway serves
+ASHLR_EMBED_KEY=sk-...                       # optional
+```
+
+With the format set, the plugin POSTs `{ "model": ..., "input": <text> }` to `<ASHLR_EMBED_URL>/embeddings` and reads `data[0].embedding`. A URL that already ends in `/embeddings` is used as is. `ASHLR_EMBED_KEY` is sent as `Authorization: Bearer <key>` and only in this mode. In the Ollama format it is ignored.
+
+Any failure falls back to the built-in BM25 embedder, as the Ollama path does. Failures include a refused URL, a timeout after 5 s, an error status, and a body without a numeric `data[0].embedding`.
+
+## Gateway rules
+
+These are the same rules as the other keyed model calls (see [llm-providers.md](llm-providers.md)):
+
+- The URL must be https, or plain http only to `127.0.0.1` or `[::1]`. `localhost` by name is refused, as is plain http to any other host.
+- Credentials in the URL (`https://user:pass@...`) are refused.
+- Redirects are not followed. A 3xx is a refusal, so the key never follows one.
+- With `ASHLR_GATEWAY_STRICT=1`, the target must also be loopback, an exact https `host:port` in `ASHLR_GATEWAY_HOSTS`, or a built-in provider host.
+
+A refused URL makes no request.
+
+## Phantom
+
+Under `phantom exec -- <cmd>`, set `ASHLR_EMBED_KEY` to the session's `phm_` placeholder and `ASHLR_EMBED_URL` to the proxy URL for your provider. The proxy URL is `http://127.0.0.1:<port>/...`, so it passes the rules above. The placeholder is sent unchanged and the proxy swaps in the real key on the way out. The plugin never resolves a `phm:` vault reference and never runs `phantom reveal`. If `ASHLR_EMBED_KEY` is a `phm:` reference, no request is made and BM25 is used.
+
+## What is never logged
+
+The embedding call writes nothing to stdout or stderr: not the key, not the text being embedded, and not the response. `scripts/context-status.ts` names an openai-format endpoint as `scheme://host:port` only, so a Phantom session token in the URL path is not printed.
+
+## Caveats
+
+The URL handling, rules and request shape are covered by tests against local stub servers. The plugin has not been tested against a live LiteLLM or Phantom session here. A remote model's vectors have a different dimension than the 256-dim BM25 vectors, as with the existing Ollama mode, so keep one embedder per context database.

package/docs/index.html

@@ -12,7 +12,7 @@
   <meta property="og:site_name" content="ashlr" />
   <meta property="og:url" content="https://plugin.ashlr.ai/" />
   <meta property="og:title" content="ashlr · The Token Ledger" />
-  <meta property="og:description" content="Open-source Codex and Claude Code plugin. Mean −57% token savings across reference repos. MIT." />
+  <meta property="og:description" content="Open-source Codex and Claude Code plugin. Per-call savings: reads about −75%, greps about −50% (not end-to-end). MIT." />
   <meta property="og:image" content="https://plugin.ashlr.ai/assets/og.png" />
   <meta property="og:image:width" content="1200" />
   <meta property="og:image:height" content="630" />
@@ -21,7 +21,7 @@
   <!-- Twitter / X -->
   <meta name="twitter:card" content="summary_large_image" />
   <meta name="twitter:title" content="ashlr · The Token Ledger" />
-  <meta name="twitter:description" content="Open-source Codex and Claude Code plugin. Mean −57% token savings across reference repos. MIT." />
+  <meta name="twitter:description" content="Open-source Codex and Claude Code plugin. Per-call savings: reads about −75%, greps about −50% (not end-to-end). MIT." />
   <meta name="twitter:image" content="https://plugin.ashlr.ai/assets/og.png" />
 
   <link rel="canonical" href="https://plugin.ashlr.ai/" />
@@ -1670,7 +1670,7 @@
       <p style="margin-top: 28px; font-family: var(--font-display); font-variation-settings: 'opsz' 16; font-size: 16px; line-height: 1.5; color: var(--ink-55); max-width: 720px;">
         <em>Files under 2 KB see 0% savings — snipCompact only fires on tool-results
         over 2,000 chars. That's by design: there's nothing to trim on a small file.
-        The story is: <strong style="color: var(--debit);">mean −57% across reference repos.</strong> Agents read big files; big files see big savings.</em>
+        The story is: <strong style="color: var(--debit);">per-call reads about −75%, greps about −50% (not end-to-end).</strong> Agents read big files; big files see big savings.</em>
       </p>
 
       <p style="margin-top: 20px; font-family: var(--font-mono); font-size: 13px; color: var(--ink-55);">

package/docs/legal.md

@@ -10,7 +10,7 @@ Last reviewed: 2026-04-18
 
 ### Entity and policy text
 
-- [x] **Entity name confirmed.** Privacy, Terms, and DPA now say "AshlrAI Inc" (Delaware corporation). Contact email is `support@ashlr.ai` across all pages.
+- [x] **Entity name confirmed.** Privacy, Terms, and DPA now say "AshlrAI Inc" (Virginia corporation). Contact email is `support@ashlr.ai` across all pages.
 - [x] **Governing law clause.** Delaware, in `site/app/terms/page.tsx` section 10. Placeholder removed.
 - [ ] **Data residency claims.** Privacy Policy section 8 states "US-East (iad)" for Fly.io and Neon. Verify this matches the actual region in `fly.toml` and the Neon project settings before go-live.
 - [ ] **Age verification.** Both Privacy Policy (section 9) and Terms (section 3) set a 13+ minimum. If you ever target education or government markets you may need FERPA/COPPA review.

package/docs/llm-providers.md

@@ -46,7 +46,7 @@ Connects to an OpenAI-compatible server (LM Studio, Ollama, etc.).
 
 | Var | Default | Purpose |
 |-----|---------|---------|
-| `ASHLR_LLM_URL` | `http://localhost:1234/v1` | Base URL of the local server |
+| `ASHLR_LLM_URL` | `http://127.0.0.1:1234/v1` | Base URL of the local server |
 | `ASHLR_LLM_KEY` | `local-llm` | Bearer token (most local servers don't validate) |
 | `ASHLR_LLM_MODEL` | `qwen/qwen3-coder-30b@8bit` | Model name to request |
 
@@ -97,3 +97,17 @@ Implementation lives in `servers/_llm-providers/`:
 | `index.ts` | `selectProvider()` + `summarizeIfLarge()` facade |
 
 `servers/_summarize.ts` re-exports `summarizeIfLarge` from `index.ts` — all existing callers are unchanged.
+
+## Strict gateway targets (opt-in)
+
+Off by default. Set `ASHLR_GATEWAY_STRICT=1` to restrict where a model call that carries a key (`Authorization` or `x-api-key`) may go:
+
+- `127.0.0.1` or `[::1]` by IP literal, over http or https on any port (a local LiteLLM, LM Studio or Ollama). `localhost` by name does not count.
+- https to an exact `host:port` listed in `ASHLR_GATEWAY_HOSTS`, comma-separated, for example `ASHLR_GATEWAY_HOSTS=litellm.internal:4000,gw.example.com:443`. Port 443 is assumed when the URL has none. An entry without a port makes every listed target refuse until it is fixed.
+- https to the built-in provider hosts on 443: `api.anthropic.com`, `api.openai.com`, `api.ashlr.ai`.
+
+In strict mode, credentials in the URL are refused and redirects are never followed: a 3xx is a refusal, because fetch forwards a custom header such as `x-api-key` to the redirect target. A refused call fails the same way a network error does, so summarization falls back and orient and genome merging fall back to their offline paths. Refusal messages name the scheme, host and port only, never the key, path or query.
+
+Covered calls: the local provider (`ASHLR_LLM_URL`, availability probe and chat), the legacy internal `endpointOverride` path, the Anthropic and cloud providers, token measurement, `ashlr__orient`'s LLM call, `ashlr__genome_consolidate`'s LLM merge, and the genome auto-consolidate reachability probes.
+
+`ashlr__orient`, `ashlr__genome_consolidate`, the local and cloud providers (`ASHLR_LLM_URL`, `ASHLR_API_URL`), the Anthropic summarizer, token measurement and the genome auto-consolidate Anthropic and OpenAI probes apply the base rules even without strict mode (for the Anthropic and OpenAI calls the URL is `ANTHROPIC_BASE_URL` / `OPENAI_BASE_URL`). For orient and genome, the endpoint comes only from `ASHLR_LLM_URL` (default `http://127.0.0.1:1234/v1`), which must be https or http to `127.0.0.1` / `[::1]`, with no credentials in the URL and no redirects followed. A tool argument cannot change it; genome's `model` argument only chooses `none` (offline) or LLM merging. Keyless calls (Ollama setup, `ASHLR_EMBED_URL` in its default Ollama format) are unchanged. The opt-in OpenAI-compatible embedding mode follows these rules; see [embeddings-gateway.md](embeddings-gateway.md).

package/docs/multi-host-mcp.md

@@ -47,6 +47,8 @@ ASHLR_MCP_HOST=claude-code    # default — preserved for back-compat
 ASHLR_MCP_HOST=cline
 ASHLR_MCP_HOST=claude-desktop
 ASHLR_MCP_HOST=codex-cli
+ASHLR_MCP_HOST=gemini-cli
+ASHLR_MCP_HOST=cursor
 ASHLR_MCP_HOST=generic        # safe default for anything else
 ```
 
@@ -61,7 +63,7 @@ If the env var is missing, the server infers `claude-code` when it sees
 ## Cline (cline_mcp_settings.json)
 
 Cline's MCP config lives in your OS-specific Cline settings dir (see
-[Cline MCP docs](https://github.com/cline/cline/blob/main/docs/mcp/README.md)).
+[Cline MCP docs](https://docs.cline.bot/mcp/mcp-overview)).
 The file is typically at:
 
 - macOS: `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
@@ -121,6 +123,26 @@ Windows). Add:
 
 Quit and reopen Claude Desktop. The tool count appears next to the input box.
 
+## Gemini CLI (~/.gemini/settings.json)
+
+Gemini CLI reads MCP servers from `~/.gemini/settings.json` (user) or
+`.gemini/settings.json` (project) under `mcpServers`:
+
+```json
+{
+  "mcpServers": {
+    "ashlr": {
+      "command": "bun",
+      "args": ["run", "/abs/path/to/ashlr-plugin/scripts/ashlr-mcp.ts"],
+      "env": { "ASHLR_MCP_HOST": "gemini-cli" }
+    }
+  }
+}
+```
+
+Run `gemini mcp list` to confirm the server loads. Cursor uses the same shape in
+`.cursor/mcp.json` with `ASHLR_MCP_HOST` set to `cursor`.
+
 ## OpenAI Codex CLI (~/.codex/config.toml)
 
 Codex can install Ashlr as a plugin from `.codex-plugin/plugin.json`, or use
@@ -171,7 +193,7 @@ These features are host-agnostic and Just Work everywhere:
   host. `ashlr-plugin stats --json` CLI works everywhere Bun runs.
 - **Genome retrieval** — `.ashlrcode/genome/` lookups work identically.
   Cloud-genome sync requires Pro/Team auth (see limitations below).
-- **Telemetry consent** — `ASHLR_TELEMETRY_OPT_IN=1` honored identically.
+- **Telemetry consent** — `ASHLR_TELEMETRY=on` honored identically.
   No host ever auto-enables it.
 - **Per-handler crash isolation** — one tool throwing won't kill the
   process. Stack traces redirect to `~/.ashlr/crash-dumps/`.
@@ -203,7 +225,7 @@ conventions; we don't try to fight them.
 Install Bun once: `curl -fsSL https://bun.sh/install | bash` (or use the
 node trampoline shown above — it auto-installs Bun on first invocation).
 
-**Tools register but every call returns "no stats yet"**
+**Tools register but `ashlr-plugin stats --json` shows an empty ledger**
 Stats are written on tool _call_, not on registration. Run any `ashlr__*`
 tool from your host once, then `ashlr-plugin stats --json` will return data.
 

package/docs/phantom-preflight.md

@@ -0,0 +1,23 @@
+# Phantom agent preflight in `ashlr doctor`
+
+`ashlr doctor` can run Phantom's value-free agent preflight,
+`phantom agent doctor --json --strict`, and show its verdict as a
+`phantom preflight` line in the install section. It is off by default.
+
+| `ASHLR_PHANTOM_PREFLIGHT` | Line status |
+|---|---|
+| unset, `0` | No line; phantom is not run. |
+| `1`, `true`, `on` | `ready` ok, `degraded` or `unknown` warn, `blocked` fail. |
+| `strict` | `ready` ok, anything else fail. |
+
+The preflight follows phantom-secrets
+[docs/agent-preflight-contract.md](https://github.com/ashlrai/phantom-secrets/blob/main/docs/agent-preflight-contract.md)
+(schema version 1; `--strict` exits 0 ready, 2 degraded, 1 blocked, 3 could
+not evaluate). It reads only project files and environment variables: no vault
+open, no keychain access.
+
+The line shows the verdict and, when blocked, the critical check ids. It never
+shows secret names, values or phantom's own messages. A missing `phantom`, or a
+version without `agent doctor --json`, gives a warning line and nothing else.
+Run `phantom agent doctor` for the full report and fix commands, and run tools
+with `phantom exec -- <cmd>` so they get `phm_` placeholders instead of keys.

package/docs/team-genome.md

@@ -428,7 +428,8 @@ bun run scripts/genome-key.ts export <genomeId>
 # Prints base32-encoded key after confirmation prompt
 
 # On each team member's machine:
-bun run scripts/genome-key.ts import <genomeId> <BASE32_KEY>
+bun run scripts/genome-key.ts import <genomeId>
+# paste the key when asked (input is hidden), or pipe it on stdin
 ```
 
 Once the key file exists at `~/.ashlr/team-keys/<genomeId>.key`, every push is

package/hooks/_hook-timing-ledger.ts

@@ -16,6 +16,7 @@ import {
   writeFileSync,
 } from "fs";
 import { basename, dirname, join } from "path";
+import { pidAlive } from "../servers/_pid-alive";
 
 export const HOOK_TIMING_FILE_MAX_BYTES = 16 * 1024 * 1024;
 export const HOOK_TIMING_BATCH_MAX_BYTES = 256 * 1024;
@@ -135,14 +136,6 @@ function readOwner(lockPath: string): LockOwner | null {
   }
 }
 
-function processIsAlive(pid: number): boolean {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (error) {
-    return (error as NodeJS.ErrnoException).code !== "ESRCH";
-  }
-}
 
 interface LockIdentity {
   lockDev: number;
@@ -219,7 +212,7 @@ function inspectStaleLock(lockPath: string): LockIdentity | null {
     const age = Math.max(0, now - Math.min(created, mtimeMs));
     if (age > LOCK_HARD_STALE_MS) return identity;
     if (age <= LOCK_STALE_MS) return null;
-    return owner === null || !processIsAlive(owner.pid) ? identity : null;
+    return owner === null || !pidAlive(owner.pid) ? identity : null;
   } catch {
     return null;
   }

package/hooks/hooks.json

@@ -5,31 +5,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-bootstrap.mjs\" \"${CLAUDE_PLUGIN_ROOT}/hooks/session-start.ts\""
-          },
-          {
-            "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-bootstrap.mjs\" \"${CLAUDE_PLUGIN_ROOT}/hooks/sessionstart-brief.ts\""
-          },
-          {
-            "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-bootstrap.mjs\" \"${CLAUDE_PLUGIN_ROOT}/hooks/sessionstart-search.ts\""
-          },
-          {
-            "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-bootstrap.mjs\" \"${CLAUDE_PLUGIN_ROOT}/hooks/sessionstart-lean-tools.ts\""
-          },
-          {
-            "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-bootstrap.mjs\" \"${CLAUDE_PLUGIN_ROOT}/hooks/sessionstart-genome-author.ts\""
-          },
-          {
-            "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-bootstrap.mjs\" \"${CLAUDE_PLUGIN_ROOT}/hooks/sessionstart-cost-refactor.ts\""
-          },
-          {
-            "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-bootstrap.mjs\" \"${CLAUDE_PLUGIN_ROOT}/hooks/sessionstart-efficient.ts\""
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-bootstrap.mjs\" --group \"${CLAUDE_PLUGIN_ROOT}/hooks/session-start.ts\" \"${CLAUDE_PLUGIN_ROOT}/hooks/sessionstart-brief.ts\" \"${CLAUDE_PLUGIN_ROOT}/hooks/sessionstart-search.ts\" \"${CLAUDE_PLUGIN_ROOT}/hooks/sessionstart-lean-tools.ts\" \"${CLAUDE_PLUGIN_ROOT}/hooks/sessionstart-genome-author.ts\" \"${CLAUDE_PLUGIN_ROOT}/hooks/sessionstart-cost-refactor.ts\" \"${CLAUDE_PLUGIN_ROOT}/hooks/sessionstart-efficient.ts\""
           }
         ]
       }
@@ -168,90 +144,11 @@
     ],
     "PostToolUse": [
       {
-        "matcher": "mcp__plugin_ashlr_ashlr__ashlr__edit|mcp__plugin_ashlr_ashlr__ashlr__multi_edit|mcp__plugin_ashlr_ashlr__ashlr__edit_structural|mcp__plugin_ashlr_ashlr__ashlr__notebook_edit|mcp__plugin_ashlr_ashlr__ashlr__write",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-bootstrap.mjs\" \"${CLAUDE_PLUGIN_ROOT}/hooks/post-tool-use-embedding.ts\""
-          }
-        ]
-      },
-      {
-        "matcher": "Edit|MultiEdit|Write|Bash|NotebookEdit|mcp__plugin_ashlr_ashlr__ashlr__edit|mcp__plugin_ashlr_ashlr__ashlr__multi_edit|mcp__plugin_ashlr_ashlr__ashlr__edit_structural|mcp__plugin_ashlr_ashlr__ashlr__notebook_edit|mcp__plugin_ashlr_ashlr__ashlr__write",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-bootstrap.mjs\" \"${CLAUDE_PLUGIN_ROOT}/hooks/audit-upload.ts\""
-          }
-        ]
-      },
-      {
-        "matcher": "Edit|MultiEdit|mcp__plugin_ashlr_ashlr__ashlr__edit|mcp__plugin_ashlr_ashlr__ashlr__multi_edit|mcp__plugin_ashlr_ashlr__ashlr__edit_structural",
+        "matcher": "mcp__plugin_ashlr_ashlr__ashlr__edit|mcp__plugin_ashlr_ashlr__ashlr__multi_edit|mcp__plugin_ashlr_ashlr__ashlr__edit_structural|mcp__plugin_ashlr_ashlr__ashlr__notebook_edit|mcp__plugin_ashlr_ashlr__ashlr__write|Edit|MultiEdit|Write|Bash|NotebookEdit|mcp__plugin_ashlr_ashlr__ashlr__rename_file|Read|Grep|mcp__plugin_ashlr_ashlr__ashlr__read|mcp__plugin_ashlr_ashlr__ashlr__grep",
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-bootstrap.mjs\" \"${CLAUDE_PLUGIN_ROOT}/hooks/edit-batching-nudge.ts\""
-          },
-          {
-            "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-bootstrap.mjs\" \"${CLAUDE_PLUGIN_ROOT}/hooks/genome-scribe-hook.ts\""
-          }
-        ]
-      },
-      {
-        "matcher": "Edit|Write|MultiEdit|NotebookEdit|mcp__plugin_ashlr_ashlr__ashlr__edit|mcp__plugin_ashlr_ashlr__ashlr__write|mcp__plugin_ashlr_ashlr__ashlr__multi_edit|mcp__plugin_ashlr_ashlr__ashlr__notebook_edit|mcp__plugin_ashlr_ashlr__ashlr__edit_structural|mcp__plugin_ashlr_ashlr__ashlr__rename_file",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-bootstrap.mjs\" \"${CLAUDE_PLUGIN_ROOT}/hooks/posttooluse-genome-refresh.ts\""
-          }
-        ]
-      },
-      {
-        "matcher": "Read|Grep|Edit|Write|MultiEdit|mcp__plugin_ashlr_ashlr__ashlr__read|mcp__plugin_ashlr_ashlr__ashlr__grep|mcp__plugin_ashlr_ashlr__ashlr__edit|mcp__plugin_ashlr_ashlr__ashlr__multi_edit|mcp__plugin_ashlr_ashlr__ashlr__edit_structural|mcp__plugin_ashlr_ashlr__ashlr__notebook_edit|mcp__plugin_ashlr_ashlr__ashlr__write",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-bootstrap.mjs\" \"${CLAUDE_PLUGIN_ROOT}/hooks/orient-nudge-hook.ts\""
-          }
-        ]
-      },
-      {
-        "matcher": "Read|Grep|Edit|Write|MultiEdit",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-bootstrap.mjs\" \"${CLAUDE_PLUGIN_ROOT}/hooks/posttooluse-native-nudge.ts\""
-          }
-        ]
-      },
-      {
-        "matcher": "Read|Grep|Edit|Write|Bash|MultiEdit|NotebookEdit|mcp__plugin_ashlr_ashlr__ashlr__read|mcp__plugin_ashlr_ashlr__ashlr__grep|mcp__plugin_ashlr_ashlr__ashlr__edit|mcp__plugin_ashlr_ashlr__ashlr__multi_edit|mcp__plugin_ashlr_ashlr__ashlr__edit_structural|mcp__plugin_ashlr_ashlr__ashlr__notebook_edit|mcp__plugin_ashlr_ashlr__ashlr__write",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-bootstrap.mjs\" \"${CLAUDE_PLUGIN_ROOT}/hooks/post-tool-use-genome.ts\""
-          },
-          {
-            "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-bootstrap.mjs\" \"${CLAUDE_PLUGIN_ROOT}/hooks/session-log-append.ts\""
-          },
-          {
-            "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-bootstrap.mjs\" \"${CLAUDE_PLUGIN_ROOT}/hooks/pulse-emit.ts\""
-          }
-        ]
-      },
-      {
-        "matcher": "Read|Grep|mcp__plugin_ashlr_ashlr__ashlr__read|mcp__plugin_ashlr_ashlr__ashlr__grep",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-bootstrap.mjs\" \"${CLAUDE_PLUGIN_ROOT}/hooks/posttooluse-stale-result.ts\""
-          },
-          {
-            "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-bootstrap.mjs\" \"${CLAUDE_PLUGIN_ROOT}/hooks/posttooluse-dedupe-output.ts\""
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-bootstrap.mjs\" --group --match \"mcp__plugin_ashlr_ashlr__ashlr__edit|mcp__plugin_ashlr_ashlr__ashlr__multi_edit|mcp__plugin_ashlr_ashlr__ashlr__edit_structural|mcp__plugin_ashlr_ashlr__ashlr__notebook_edit|mcp__plugin_ashlr_ashlr__ashlr__write\" \"${CLAUDE_PLUGIN_ROOT}/hooks/post-tool-use-embedding.ts\" --match \"Edit|MultiEdit|Write|Bash|NotebookEdit|mcp__plugin_ashlr_ashlr__ashlr__edit|mcp__plugin_ashlr_ashlr__ashlr__multi_edit|mcp__plugin_ashlr_ashlr__ashlr__edit_structural|mcp__plugin_ashlr_ashlr__ashlr__notebook_edit|mcp__plugin_ashlr_ashlr__ashlr__write\" \"${CLAUDE_PLUGIN_ROOT}/hooks/audit-upload.ts\" --match \"Edit|MultiEdit|mcp__plugin_ashlr_ashlr__ashlr__edit|mcp__plugin_ashlr_ashlr__ashlr__multi_edit|mcp__plugin_ashlr_ashlr__ashlr__edit_structural\" \"${CLAUDE_PLUGIN_ROOT}/hooks/edit-batching-nudge.ts\" --match \"Edit|MultiEdit|mcp__plugin_ashlr_ashlr__ashlr__edit|mcp__plugin_ashlr_ashlr__ashlr__multi_edit|mcp__plugin_ashlr_ashlr__ashlr__edit_structural\" \"${CLAUDE_PLUGIN_ROOT}/hooks/genome-scribe-hook.ts\" --match \"Edit|Write|MultiEdit|NotebookEdit|mcp__plugin_ashlr_ashlr__ashlr__edit|mcp__plugin_ashlr_ashlr__ashlr__write|mcp__plugin_ashlr_ashlr__ashlr__multi_edit|mcp__plugin_ashlr_ashlr__ashlr__notebook_edit|mcp__plugin_ashlr_ashlr__ashlr__edit_structural|mcp__plugin_ashlr_ashlr__ashlr__rename_file\" \"${CLAUDE_PLUGIN_ROOT}/hooks/posttooluse-genome-refresh.ts\" --match \"Read|Grep|Edit|Write|MultiEdit|mcp__plugin_ashlr_ashlr__ashlr__read|mcp__plugin_ashlr_ashlr__ashlr__grep|mcp__plugin_ashlr_ashlr__ashlr__edit|mcp__plugin_ashlr_ashlr__ashlr__multi_edit|mcp__plugin_ashlr_ashlr__ashlr__edit_structural|mcp__plugin_ashlr_ashlr__ashlr__notebook_edit|mcp__plugin_ashlr_ashlr__ashlr__write\" \"${CLAUDE_PLUGIN_ROOT}/hooks/orient-nudge-hook.ts\" --match \"Read|Grep|Edit|Write|MultiEdit\" \"${CLAUDE_PLUGIN_ROOT}/hooks/posttooluse-native-nudge.ts\" --match \"Read|Grep|Edit|Write|Bash|MultiEdit|NotebookEdit|mcp__plugin_ashlr_ashlr__ashlr__read|mcp__plugin_ashlr_ashlr__ashlr__grep|mcp__plugin_ashlr_ashlr__ashlr__edit|mcp__plugin_ashlr_ashlr__ashlr__multi_edit|mcp__plugin_ashlr_ashlr__ashlr__edit_structural|mcp__plugin_ashlr_ashlr__ashlr__notebook_edit|mcp__plugin_ashlr_ashlr__ashlr__write\" \"${CLAUDE_PLUGIN_ROOT}/hooks/post-tool-use-genome.ts\" --match \"Read|Grep|Edit|Write|Bash|MultiEdit|NotebookEdit|mcp__plugin_ashlr_ashlr__ashlr__read|mcp__plugin_ashlr_ashlr__ashlr__grep|mcp__plugin_ashlr_ashlr__ashlr__edit|mcp__plugin_ashlr_ashlr__ashlr__multi_edit|mcp__plugin_ashlr_ashlr__ashlr__edit_structural|mcp__plugin_ashlr_ashlr__ashlr__notebook_edit|mcp__plugin_ashlr_ashlr__ashlr__write\" \"${CLAUDE_PLUGIN_ROOT}/hooks/session-log-append.ts\" --match \"Read|Grep|Edit|Write|Bash|MultiEdit|NotebookEdit|mcp__plugin_ashlr_ashlr__ashlr__read|mcp__plugin_ashlr_ashlr__ashlr__grep|mcp__plugin_ashlr_ashlr__ashlr__edit|mcp__plugin_ashlr_ashlr__ashlr__multi_edit|mcp__plugin_ashlr_ashlr__ashlr__edit_structural|mcp__plugin_ashlr_ashlr__ashlr__notebook_edit|mcp__plugin_ashlr_ashlr__ashlr__write\" \"${CLAUDE_PLUGIN_ROOT}/hooks/pulse-emit.ts\" --match \"Read|Grep|mcp__plugin_ashlr_ashlr__ashlr__read|mcp__plugin_ashlr_ashlr__ashlr__grep\" \"${CLAUDE_PLUGIN_ROOT}/hooks/posttooluse-stale-result.ts\" --match \"Read|Grep|mcp__plugin_ashlr_ashlr__ashlr__read|mcp__plugin_ashlr_ashlr__ashlr__grep\" \"${CLAUDE_PLUGIN_ROOT}/hooks/posttooluse-dedupe-output.ts\""
           }
         ]
       }

package/hooks/posttooluse-stale-result.ts

@@ -31,6 +31,7 @@ import {
   staleByteTotal,
   STALE_BYTES_NUDGE_THRESHOLD,
 } from "../servers/_history-tracker";
+import { observeToolCall } from "../servers/_miss-tracker";
 import { logPreCompactionNudgeEvent } from "../servers/_telemetry";
 // logMultiTurnStaleEvent removed in v1.30 (1.5) — multi_turn_stale_estimate was never populated.
 
@@ -178,6 +179,8 @@ export function decide(
 
   // Record this result in the history JSONL.
   const content = extractContent(payload);
+  // Miss tracking (self-tuning P1): turn index of this call = entries so far.
+  observeToolCall(toolName, payload.tool_input, readHistory(sessionId, homeDir).length, sessionId, homeDir);
   recordResult(toolName, content, sessionId, homeDir, now);
 
   // -------------------------------------------------------------------------

package/hooks/pretooluse-common.ts

@@ -416,7 +416,7 @@ export function buildToolRedirectBlock(opts: {
   savingsPct: number;
   bypassNote?: string;
 }): RedirectBlockOutput {
-  const bypass = opts.bypassNote ?? "set ASHLR_HOOK_MODE=nudge in ~/.ashlr/config.json";
+  const bypass = opts.bypassNote ?? 'set ASHLR_HOOK_MODE=nudge, or "hookMode": "nudge" in ~/.ashlr/config.json';
   const reason =
     `[ashlr bypass: ${bypass}] ~${opts.savingsPct}% token savings. Call this instead:\n\n` +
     `  tool_use: ${opts.mcpToolName}\n` +

package/hooks/pretooluse-notebookedit.ts

@@ -112,7 +112,7 @@ if (!notebookPath || !isInsideCwd(notebookPath)) {
 
 const mcp = "mcp__plugin_ashlr_ashlr__ashlr__notebook_edit";
 const reason =
-  `[ashlr] To bypass: set ASHLR_HOOK_MODE=nudge in ~/.ashlr/config.json. ` +
+  `[ashlr] To bypass: set ASHLR_HOOK_MODE=nudge, or "hookMode": "nudge" in ~/.ashlr/config.json. ` +
   `Current rule: blocking built-in NotebookEdit on ${notebookPath || "<notebook>"} — ` +
   `call ${mcp} instead, which applies the cell edit and returns only the edited cell ` +
   `plus one cell above and below (full notebook never echoed). ` +

package/hooks/pretooluse-write.ts

@@ -118,7 +118,7 @@ if (!isInsideCwd(payload!.file_path)) {
 
 const mcp = "mcp__plugin_ashlr_ashlr__ashlr__write";
 const reason =
-  `[ashlr] To bypass: set ASHLR_HOOK_MODE=nudge in ~/.ashlr/config.json. ` +
+  `[ashlr] To bypass: set ASHLR_HOOK_MODE=nudge, or "hookMode": "nudge" in ~/.ashlr/config.json. ` +
   `Current rule: blocking built-in Write on ${payload!.file_path} (${size} bytes) — ` +
   `call ${mcp} instead, which delegates to ashlr__edit (diff format) for existing ` +
   `files and returns only a compact diff summary, avoiding the full content echo ` +

package/hooks/session-start.ts

@@ -22,6 +22,7 @@
  *     (an empty additionalContext) rather than hang the session.
  */
 
+import { keychainLoad, migrateEnvFileToken } from "../servers/_pro-token-keychain.ts";
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, unlinkSync, writeFileSync } from "fs";
 import { homedir } from "os";
 import { basename, dirname, join } from "path";
@@ -763,6 +764,22 @@ function sourceAshlrEnv(): void {
 }
 
 
+/**
+ * Move a plaintext ASHLR_PRO_TOKEN line from ~/.ashlr/env into the OS
+ * keychain (kept in the file if the keychain is unavailable), then load the
+ * token from the keychain when the environment does not already set it.
+ */
+function loadProTokenFromKeychain(): void {
+  try {
+    migrateEnvFileToken(join(homedir(), ".ashlr", "env"));
+    if (process.env["ASHLR_PRO_TOKEN"]) return;
+    const token = keychainLoad();
+    if (token) process.env["ASHLR_PRO_TOKEN"] = token;
+  } catch {
+    /* keychain is optional, never break the hook */
+  }
+}
+
 /**
  * Detect the active ashlr tier for Q2 cloud delta sync. Mirrors
  * scripts/check-tier.ts so we can call syncCloudDeltas without spawning a
@@ -789,10 +806,30 @@ async function detectTierForSync(): Promise<Tier> {
   }
 }
 
+/**
+ * Race `work` against a `ms` ceiling and clear the timer once either side
+ * settles. A bare `setTimeout` in a Promise.race keeps the hook process alive
+ * until it fires, which held every SessionStart open for the full 2s.
+ */
+async function raceWithTimeout<T, F>(work: Promise<T>, ms: number, fallback: F): Promise<T | F> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      work,
+      new Promise<F>((resolve) => {
+        timer = setTimeout(() => resolve(fallback), ms);
+      }),
+    ]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 async function main(): Promise<void> {
   // Source ~/.ashlr/env so ASHLR_PRO_TOKEN from the upgrade flow is available
   // without requiring a shell restart.
   sourceAshlrEnv();
+  loadProTokenFromKeychain();
 
   // First-run: bootstrap dependencies if missing. Silent no-op otherwise.
   ensureDepsInstalled();
@@ -846,24 +883,15 @@ async function main(): Promise<void> {
 
   let result: BuildResult;
   try {
-    result = await Promise.race([
-      Promise.resolve(buildResponse()),
-      new Promise<BuildResult>((resolve) =>
-        setTimeout(
-          () =>
-            resolve({
-              output: {
-                hookSpecificOutput: {
-                  hookEventName: "SessionStart",
-                  additionalContext: "[ashlr baseline · timed out]",
-                },
-              },
-              notice: null,
-            }),
-          SCAN_BUDGET_MS,
-        )
-      ),
-    ]);
+    result = await raceWithTimeout(Promise.resolve(buildResponse()), SCAN_BUDGET_MS, {
+      output: {
+        hookSpecificOutput: {
+          hookEventName: "SessionStart",
+          additionalContext: "[ashlr baseline · timed out]",
+        },
+      },
+      notice: null,
+    });
   } catch {
     result = {
       output: { hookSpecificOutput: { hookEventName: "SessionStart" } },
@@ -934,10 +962,7 @@ async function main(): Promise<void> {
     // race only protects against the fire-and-forget reference outliving the
     // hook (e.g. a pending fetch that the AbortController didn't actually
     // abort because the runtime was wedged).
-    void Promise.race([
-      checkForUpdate({ currentVersion }),
-      new Promise<void>((resolve) => setTimeout(resolve, 2000)),
-    ]).catch((e) => {
+    void raceWithTimeout(checkForUpdate({ currentVersion }), 2000, undefined).catch((e) => {
       process.stderr.write(
         "[ashlr-session-start] update check failed: " +
           (e instanceof Error ? e.message : String(e)) +
@@ -969,10 +994,7 @@ async function main(): Promise<void> {
   // fetch can never blow the SessionStart budget. Failures are swallowed.
   try {
     const tier = await detectTierForSync();
-    await Promise.race([
-      syncCloudDeltas({ tier }),
-      new Promise<void>((resolve) => setTimeout(resolve, 2000)),
-    ]);
+    await raceWithTimeout(syncCloudDeltas({ tier }), 2000, undefined);
   } catch (e) {
     process.stderr.write(
       "[ashlr-session-start] cloud delta sync failed: " +

package/package.json

@@ -1,12 +1,17 @@
 {
   "name": "ashlr-plugin",
-  "version": "1.36.4",
+  "version": "1.37.1",
+  "mcpName": "io.github.ashlrai/ashlr-plugin",
   "description": "Multi-host AI coding efficiency layer for Codex and Claude Code, powered by @ashlr/core-efficiency.",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ashlrai/ashlr-plugin.git"
+  },
   "type": "module",
   "bin": {
-    "ashlr-plugin": "./scripts/cli.ts",
-    "ashlr-mcp": "./scripts/ashlr-mcp.ts"
+    "ashlr-plugin": "./scripts/ashlr-plugin.mjs",
+    "ashlr-mcp": "./scripts/ashlr-mcp.mjs"
   },
   "files": [
     ".agents/plugins/marketplace.json",
@@ -39,7 +44,7 @@
     "version:check": "bun run scripts/check-version-sync.ts"
   },
   "dependencies": {
-    "@ashlr/core-efficiency": "github:ashlrai/ashlr-core-efficiency#275610156ee314c3335025f0ba0c2379089e068c",
+    "@ashlr/core-efficiency": "0.3.0",
     "@modelcontextprotocol/sdk": "^1.0.0",
     "minimatch": "^10.2.5",
     "postgres": "^3.4.9",

package/ports/cursor/mcp.json

@@ -4,7 +4,7 @@
       "command": "bun",
       "args": ["run", "<ASHLR_PLUGIN_ROOT>/scripts/ashlr-mcp.ts"],
       "env": {
-        "ASHLR_MCP_HOST": "generic"
+        "ASHLR_MCP_HOST": "cursor"
       }
     }
   }