engramx 2.0.1 → 2.1.0

package/CHANGELOG.md

@@ -4,6 +4,294 @@ All notable changes to engram are documented here. Format based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versioning follows
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [2.1.0] — 2026-04-21 — "Reliability + Zero-Friction Install"
+
+First release in the v2.1 / v2.2 / v3.0 elevation trilogy. Design spec
+at `docs/superpowers/specs/2026-04-20-engram-elevation-trilogy-design.md`.
+
+Headline: `engram setup` is the new one-command first-run flow. Users
+go from `npm install -g engramx` to a working Sentinel hook + indexed
+graph in under 30 seconds. `engram doctor` reports component health
+with remediation hints. `engram update` ships future hotfixes to every
+install without surprise — passive notify, zero telemetry, one-command
+upgrade. Plus fixes for issue #11 (AST/LSP path bug in flattened
+bundles) and issue #14's Bash-ops half (auto-reindex on `rm`/`mv`/
+`git rm` via an opt-in PostToolUse gate).
+
+Contributor credit this release: [@gabiudrescu](https://github.com/gabiudrescu)
+for PR #13 (reindex CLI + `install-hook --auto-reindex`), PR #12
+(watcher prune on delete/rename), and the original v2.0.2 security
+disclosure. [@ttessarolo](https://github.com/ttessarolo) for precise
+forensics + suggested fix on issue #11.
+
+### Added — v2.1 "Reliability + Zero-Friction Install" track
+
+- **`engram update`** — one-command self-upgrade.
+  Passive notify on every `engram *` invocation when a newer version is
+  available (cached, at most one line on stderr, throttled to a 7-day
+  registry check). Manual trigger detects the package manager that owns
+  the engram install (npm / pnpm / yarn / bun via install-path markers)
+  and shells out to its global-upgrade command. `--check` for dry-probe,
+  `--force` to bypass the 7-day throttle, `--dry-run` to print the
+  upgrade command without executing it, `--manager <mgr>` override.
+  Zero telemetry: the only network call is an anonymous GET to
+  `registry.npmjs.org/engramx/latest`. `ENGRAM_NO_UPDATE_CHECK=1` and
+  `$CI` disable the entire subsystem. Addresses the "1,300 weekly
+  downloads, 10/day organic, near-zero hotfix reach" problem.
+
+- **`engram doctor`** — component health report with remediation hints.
+  Wraps existing probes (HTTP, LSP, AST, IDE adapters) plus four new
+  checks: engram version freshness, `.engram/graph.db` presence,
+  Sentinel hook installation, IDE adapter count. Each check emits
+  severity (ok / warn / fail) + detail + optional remediation. Exit
+  code reflects overall severity (0 ok, 1 warn, 2 fail) so `doctor`
+  is CI-friendly. `--verbose` shows remediation hints; `--json` /
+  `--export` emits redacted JSON for bug-report attachment
+  (`projectRoot` intentionally omitted — can contain usernames).
+
+- **`engram setup`** — zero-friction first-run wizard. One command for
+  "go from cloned repo to working engram in under 30 seconds."
+  Runs `init` (if `.engram/graph.db` missing) → `install-hook` (with
+  prompted scope, `local` default) → detects IDE adapters (Cursor,
+  Windsurf, Continue.dev, Aider) and suggests the matching `gen-*`
+  command for each → finishes with a `doctor` summary. Each step is
+  idempotent. `--yes` runs with defaults; `--dry-run` prints intent
+  without acting; `--scope` controls the install-hook scope. Drops
+  install-to-first-value from 4 commands to 1.
+
+- **`engram init --with-hook`** — shorthand for `init` followed by
+  `install-hook` (local scope, idempotent). The #1 thing every user
+  does after `init` was `install-hook`; now it's one step.
+
+- **First-run hint.** On any `engram` subcommand invoked in a repo
+  lacking `.engram/graph.db`, print one line on stderr:
+  `💡 First time in this repo? Run 'engram setup' for a zero-friction install.`
+  Throttled via `~/.engram/first-run-shown` (fires once per machine,
+  not per repo). Silenced in `$CI`, under `ENGRAM_NO_UPDATE_CHECK=1`,
+  and under the JSON-stdout commands (`intercept`, `cursor-intercept`,
+  `hud-label`, `setup`, `init`, `update`, `doctor`) so neither
+  pollutes the hook protocol.
+
+- **Bash PostToolUse parser for auto-reindex** — closes half of
+  [#14](https://github.com/NickCirv/engram/issues/14).
+  `src/intercept/handlers/bash-postool.ts` parses file-mutating Bash
+  commands (`rm`, `mv`, `cp`, `git rm`, `git mv`, single-redirect
+  `<cmd> > <dst>`) into `FileOp { action, path }` records. Strict
+  parser: globs, pipes, subshells, command-substitution, directory
+  ops, and `touch` all pass through untouched. Wired into the
+  PostToolUse observer path in `handlers/post-tool.ts` — on Bash
+  PostToolUse events, each op is handed to `syncFile()` fire-and-forget.
+  Gated by `ENGRAM_AUTO_REINDEX=1` opt-in until
+  [#13](https://github.com/NickCirv/engram/pull/13)'s install-hook
+  `--auto-reindex` flag lands; that flag will toggle the env gate
+  implicitly.
+
+### Fixed — v2.1 reliability
+
+- **AST grammar detection in flattened bundles**
+  ([#11](https://github.com/NickCirv/engram/issues/11) partial).
+  When `tsup`/`esbuild` flattens chunks to `engramx/dist/chunk-*.js`,
+  `import.meta.url` resolves to `engramx/dist` and the previous
+  candidates (`../grammars` and `../../dist/grammars`) both missed the
+  actual grammar dir. Added `join(here, "grammars")` as the first
+  candidate; dev-time layout (`src/intercept/`) still works via the
+  third candidate. Thanks [@ttessarolo](https://github.com/ttessarolo).
+
+- **LSP socket candidate coverage**
+  ([#11](https://github.com/NickCirv/engram/issues/11) partial).
+  `checkLsp` was looking for two socket names while
+  `lsp-connection.ts::candidateSockets()` probes six. Synced the list
+  so HUD availability matches actual provider availability. Kept
+  `.engram/lsp-available` as an explicit user opt-in marker for
+  back-compat.
+
+### Fixed
+
+- **Locale-independent number formatting across the codebase.** All 10
+  `Number.prototype.toLocaleString()` callsites in `src/cli.ts`,
+  `src/serve.ts`, `src/dashboard.ts`, and `src/intercept/stats.ts` have
+  been migrated to a shared `formatThousands()` helper in
+  `src/graph/render-utils.ts`. Two wins:
+
+  1. **Deterministic performance.** First-call ICU init on Windows Node
+     has been observed to take multiple seconds in GitHub Actions VMs,
+     flaking tests at the 5000ms default timeout (seen on
+     `tests/intercept/stats.test.ts > formatStatsSummary` post-merge on
+     `9f99f5b`). The regex-based helper runs in microseconds with no
+     ICU dependency.
+  2. **Locale independence.** `toLocaleString()` emits `"1,234"` on
+     en-US but `"1.234"` on de-DE and `"1 234"` on fr-FR, giving users
+     running engram in non-US shells inconsistent output. All CLI +
+     MCP server + dashboard numbers now render with commas regardless
+     of system locale.
+
+  Added `tests/render-utils.test.ts > formatThousands` — 6 tests
+  covering single-digit, multi-group, negative, and locale-stable cases.
+  Also added `vitest.config.ts` with CI-only `retry: 1` +
+  `testTimeout: 15000ms` as defense-in-depth against other cold-worker
+  flakes.
+
+- **`engram watch` now prunes graph nodes when watched files are deleted
+  or renamed** ([#9](https://github.com/NickCirv/engram/issues/9),
+  [#12](https://github.com/NickCirv/engram/pull/12)). Previously the
+  watcher only subscribed to `change` events, silently ignoring the
+  `rename` events that `fs.watch` fires for create/unlink across all
+  platforms. Deletions left stale nodes in the graph until the next
+  `engram init`; renames produced duplicate nodes under the old and new
+  `sourceFile` paths. Thanks [@gabiudrescu](https://github.com/gabiudrescu).
+
+### Added
+
+- **`syncFile(absPath, root)`** exported from `src/watcher.ts` — the shared
+  "exists → reindex; gone (and was indexed) → prune" primitive reused by
+  the upcoming `engram reindex` CLI subcommand ([#8](https://github.com/NickCirv/engram/issues/8)).
+  Returns a discriminated `SyncResult` (`indexed` | `pruned` | `skipped`).
+- **`GraphStore.countBySourceFile(relPath)`** — noise-reduction gate so
+  `onDelete` only fires for files the graph actually indexed.
+- **`onDelete` callback on `WatchOptions`** — fires with `(filePath, prunedCount)`
+  when the watcher prunes a deleted file's nodes.
+- **`× <path> pruned (N nodes)`** log line in `engram watch`, distinct from
+  the existing green `↻` reindex line.
+- **`gen-cursor --watch`, `gen-aider --watch`, `gen-windsurfrules --watch`**
+  now regenerate their output files on source-file delete (not just on
+  reindex), so generated artifacts no longer keep stale references to
+  deleted sources.
+- **`engram reindex <file>` CLI subcommand**
+  ([#8](https://github.com/NickCirv/engram/issues/8)) — re-indexes a
+  single file into the knowledge graph. The missing primitive for per-
+  edit freshness: Claude Code PostToolUse hooks, editor plugins, and CI
+  can now keep the graph in sync without running a long-lived watcher.
+  Reuses `syncFile()` so semantics match `engram watch`: exists →
+  reindex; missing-but-previously-indexed → prune; unsupported ext or
+  ignored directory → silent exit 0 (safe to fire on every edit). On
+  success prints a single line `engram: reindexed <file> (<N> nodes)`
+  (or `pruned`) using locale-stable `formatThousands`. `--verbose`
+  surfaces stack traces; default error output is a single stderr line.
+  Missing graph exits 1 with `engram: no graph found at <root>. Run
+  'engram init' first.`, matching `engram watch`.
+- **`formatReindexLine(result, displayPath)`** exported from
+  `src/watcher.ts` — pure formatter shared by the new subcommand. Returns
+  `null` for skipped results so callers stay silent.
+- **`engram reindex-hook` subcommand + `engram install-hook --auto-reindex`**
+  ([#8](https://github.com/NickCirv/engram/issues/8), opt-in auto-wire).
+  `reindex-hook` reads Claude Code's PostToolUse payload from stdin and
+  re-indexes `tool_input.file_path` via the shared `syncFile()` primitive.
+  Contract: ALWAYS exits 0 — malformed JSON, missing fields, non-project
+  `cwd`, and all internal errors resolve to a silent no-op so the hook
+  can never fail Claude Code's tool cycle. `install-hook --auto-reindex`
+  appends a second PostToolUse entry with matcher `Edit|Write|MultiEdit`
+  calling `engram reindex-hook`; off by default so existing users aren't
+  surprised. The new entry is recognized by `isEngramHookEntry()` so
+  `engram uninstall-hook` strips it alongside the primary intercept
+  entries. Idempotent — reinstalling with `--auto-reindex` is a no-op
+  when the entry already exists.
+- **`runReindexHook(payload)`** exported from `src/watcher.ts` — the
+  pure async handler behind the `reindex-hook` subcommand. Validates
+  payload shape, resolves project root from `cwd`, delegates to
+  `syncFile`. Swallows every error.
+- **`buildReindexHookEntry()` + `ENGRAM_REINDEX_HOOK_MATCHER`
+  (`"Edit|Write|MultiEdit"`) + `DEFAULT_ENGRAM_REINDEX_HOOK_COMMAND`
+  (`"engram reindex-hook"`)** exported from `src/intercept/installer.ts`
+  — the data primitives for the optional entry. Added
+  `InstallOptions.autoReindex` and `InstallResult.autoReindexAdded` to
+  thread the opt-in through the existing installer surface.
+
+### Notes
+
+- Directory deletion (`rm -rf src/foo`) is intentionally not handled by the
+  watcher — `fs.watch` fires a single rename event on the directory path
+  with no per-file information. A full `engram init` handles that case
+  today; per-file directory-prefix pruning is tracked for v2.2.
+
+## [2.0.2] — 2026-04-18 — Security hotfix: HTTP server auth & CORS
+
+**This is a security release. Upgrade immediately if you run `engram server`
+or `engram ui`.** Credit: [@gabiudrescu](https://github.com/gabiudrescu) for
+responsible disclosure ([#7](https://github.com/NickCirv/engram/issues/7)).
+
+### Security — fixed
+
+- **Graph exfiltration + persistent prompt injection via cross-origin browser
+  tabs.** The HTTP server previously shipped with `Access-Control-Allow-Origin: *`
+  on every response and defaulted to no authentication. A malicious page the
+  developer visited could `fetch('http://127.0.0.1:7337/query')` to steal the
+  local graph, then `POST /learn` (with `Content-Type: text/plain`, a
+  CORS-safelisted content type) to persist `bug:` / `fix:` patterns that the
+  v2 Sentinel handlers later re-injected into the user's coding agent on
+  SessionStart and on every Edit/Write of the named file. Severity: High —
+  confidentiality + persistent indirect prompt injection.
+
+  **Fix (four stacked defenses):**
+  1. **Fail-closed auth.** Every route except `/health` and `/favicon.ico`
+     now requires `Authorization: Bearer <token>` or an HttpOnly
+     `engram_token` cookie. A random 64-character token is auto-generated
+     on first server start and persisted to `~/.engram/http-server.token`
+     with mode `0600`. `ENGRAM_API_TOKEN` env var still overrides.
+  2. **No wildcard CORS.** `Access-Control-Allow-Origin: *` has been removed
+     from every response. By default no CORS headers are emitted — the
+     dashboard is same-origin. Additional origins opt in via
+     `ENGRAM_ALLOWED_ORIGINS=a.com,b.com`.
+  3. **Host + Origin validation** (DNS-rebinding defense). Requests with a
+     `Host` header other than `127.0.0.1|localhost|::1` on the bound port
+     return 400. Requests with an `Origin` not in the same-origin or env
+     allowlist return 403.
+  4. **`Content-Type: application/json` enforced on mutations.** POST / PUT /
+     DELETE without `application/json` return 415. This blocks the
+     `text/plain` CSRF vector from the PoC and forces CORS preflight for
+     any cross-origin writer.
+
+- **Timing side-channel on token comparison.** The previous
+  `header === \`Bearer ${token}\`` comparison was not constant-time.
+  Replaced with a length-first, constant-time `safeEqual()`.
+
+### Added
+
+- `src/server/auth.ts` — token management (get-or-create, safeEqual, cookie
+  parsing, Host/Origin validators).
+- `tests/server/security.test.ts` — PoC-style tests covering fail-closed
+  auth (including empty Bearer / empty cookie guards), env-downgrade
+  rejection (token is snapshot at start), cookie auth, wildcard-CORS
+  absence, same-origin echo, foreign-origin 403, Host header validation
+  (including no-port rejection + case-insensitive hostname), `text/plain`
+  rejection on `/learn`, the `/ui?token=` cross-site oracle defence via
+  `Sec-Fetch-Site` gating, and the end-to-end exploit chain from #7.
+- `SECURITY.md` at repo root with disclosure policy and scope.
+- `GET /ui?token=<t>` bootstrap path for the browser dashboard. The CLI
+  passes the token once; the server exchanges it for an HttpOnly cookie via
+  a 302 redirect and strips the token from the URL. Dashboard JS never sees
+  the raw token.
+
+### Changed
+
+- `createHttpServer(projectRoot, port)` now resolves to `Promise<TokenInfo>`
+  (previously `Promise<void>`). The returned object exposes the token source
+  (env / file / generated) and the token file path. The CLI uses this to
+  print a one-time banner pointing users at `~/.engram/http-server.token`
+  when a fresh token is minted.
+- `checkAuth` rewritten as fail-closed, accepts Bearer header OR
+  `engram_token` cookie, uses constant-time comparison.
+- Server-Sent Events endpoint (`/api/sse`) no longer emits wildcard CORS and
+  inherits the same origin-allowlist behavior as every other route.
+
+### Breaking
+
+- **External callers (curl, scripts, CI probes) must now send the token.**
+  Fix the one-liner on each caller:
+  ```bash
+  curl -H "Authorization: Bearer $(cat ~/.engram/http-server.token)" \
+       http://127.0.0.1:7337/stats
+  ```
+- Requests with `Host: something-else.com` are rejected 400 even if they
+  resolve to 127.0.0.1 locally. DNS rebinding defense — intended behavior.
+- Cross-origin requests (`Origin: https://example.com`) are rejected 403
+  unless the origin is in `ENGRAM_ALLOWED_ORIGINS`. No legitimate caller
+  should be affected.
+- `/ui` navigation from the browser now requires `?token=<t>` on first visit
+  (set automatically when you run `engram ui`) or a pre-existing
+  `engram_token` cookie.
+
 ## [2.0.1] — 2026-04-17 — Windows CI + favicon route
 
 Patch release fixing two issues caught immediately after v2.0.0 shipped.

package/README.md

@@ -2,6 +2,35 @@
   <img src="assets/banner.png" alt="engram — AI coding memory" width="100%">
 </p>
 
+<!-- ============================================================
+     24-second product showcase (Hyperframes-rendered MP4 + WebM).
+     Source: docs/demos/showcase.html · scenes drive both the
+     live HTML player and this MP4. Edit scene-table.md to change.
+     If the MP4 isn't rendered yet, GitHub gracefully shows the
+     poster image and links to the live HTML player.
+     ============================================================ -->
+<p align="center">
+  <video src="https://raw.githubusercontent.com/NickCirv/engram/main/docs/demos/showcase.mp4"
+         controls
+         muted
+         playsinline
+         poster="docs/demos/poster.svg"
+         width="100%">
+    <a href="docs/demos/showcase.html">
+      <img src="docs/demos/poster.svg" alt="engram — 24-second showcase (click to open the live HTML player)" width="100%">
+    </a>
+  </video>
+</p>
+
+<p align="center">
+  <sub>
+    <a href="docs/install.html"><strong>Install Page</strong></a> ·
+    <a href="docs/demos/showcase.html"><strong>Live Demo</strong></a> ·
+    <a href="docs/demos/scene-table.md"><strong>Scene Table</strong></a> ·
+    rendered with <a href="https://github.com/heygen-com/hyperframes">Hyperframes</a>
+  </sub>
+</p>
+
 <p align="center">
   <a href="#install"><strong>Install</strong></a> ·
   <a href="#quickstart"><strong>Quickstart</strong></a> ·
@@ -175,10 +204,23 @@ npm install -g engramx
 
 Requires Node.js 20+. Zero native dependencies. No build tools. Local SQLite via sql.js WASM — no Rust, no Python, no system libs.
 
+> **Prefer a designed walkthrough?** Open [**docs/install.html**](docs/install.html) — three-step install, benefits matrix, IDE coverage, FAQ. Local file, opens in any browser. Brand-matched terminal-mono aesthetic.
+
 ---
 
 ## Quickstart
 
+**One command, zero friction:**
+
+```bash
+cd ~/my-project
+engram setup                     # init + install-hook + adapter detect + doctor
+```
+
+`engram setup` runs the whole first-run flow interactively (or pass `-y` for defaults, `--dry-run` to preview). It is idempotent — safe to re-run, and skips any step already done.
+
+<sub>Prefer the individual commands?</sub>
+
 ```bash
 cd ~/my-project
 engram init                      # scan codebase → .engram/graph.db (~40ms, 0 tokens)
@@ -186,6 +228,16 @@ engram install-hook              # wire the Sentinel into Claude Code
 engram ui                        # open the web dashboard in your browser
 ```
 
+**Diagnostics + self-update:**
+
+```bash
+engram doctor                    # component health + remediation hints (0=ok, 1=warn, 2=fail)
+engram update                    # check + upgrade via detected pkg manager (no telemetry)
+engram update --check            # check only, dry-probe the registry
+```
+
+Set `ENGRAM_NO_UPDATE_CHECK=1` to disable the passive "newer version available" hint on every CLI invocation. `$CI` does the same automatically.
+
 Open a Claude Code session. When the agent reads a well-covered file you will see a system-reminder with the structural summary instead of file contents. After the session:
 
 ```bash
@@ -275,6 +327,7 @@ engram install-hook                  # default: .claude/settings.local.json (git
 engram install-hook --scope project  # .claude/settings.json (committed)
 engram install-hook --scope user     # ~/.claude/settings.json (global)
 engram install-hook --dry-run        # preview changes without writing
+engram install-hook --auto-reindex   # also keep the graph fresh after every Edit/Write/MultiEdit (#8)
 ```
 
 **Kill switch (if anything goes wrong):**
@@ -336,6 +389,8 @@ engram hook-enable               # remove kill switch
 
 ```bash
 engram watch [path]              # live file watcher — incremental re-index on save
+engram reindex <file>            # re-index one file (editor/hook/CI primitive, issue #8)
+engram reindex-hook              # PostToolUse hook entry point (reads JSON from stdin, always exits 0)
 engram dashboard [path]          # live terminal dashboard
 engram hud-label [path]          # JSON label for Claude HUD --extra-cmd integration
 engram hooks install             # install post-commit + post-checkout git hooks

package/dist/{aider-context-BC5R2ZTA.js → aider-context-J557IHIP.js}

@@ -7,7 +7,7 @@ function buildSection(heading, lines) {
   return [`## ${heading}`, "", ...lines, ""].join("\n");
 }
 async function generateAiderContext(projectRoot) {
-  const { getStore } = await import("./core-6IY5L6II.js");
+  const { getStore } = await import("./core-TSXA5XZH.js");
   const store = await getStore(projectRoot);
   try {
     const allNodes = store.getAllNodes();

package/dist/auth-KB2ZRMS3.js

@@ -0,0 +1,14 @@
+import {
+  getOrCreateToken,
+  isHostValid,
+  isOriginAllowed,
+  parseCookies,
+  safeEqual
+} from "./chunk-N6PPKOPK.js";
+export {
+  getOrCreateToken,
+  isHostValid,
+  isOriginAllowed,
+  parseCookies,
+  safeEqual
+};

package/dist/check-2Z3MPZEJ.js

@@ -0,0 +1,12 @@
+import {
+  cachePath,
+  checkForUpdate,
+  isNewer,
+  optedOut
+} from "./chunk-RM2TBOVW.js";
+export {
+  cachePath,
+  checkForUpdate,
+  isNewer,
+  optedOut
+};

package/dist/{chunk-C6GBUOAL.js → chunk-4XA6ENNL.js}

@@ -310,7 +310,7 @@ function writeToFile(filePath, summary) {
   writeFileSync2(filePath, newContent);
 }
 async function autogen(projectRoot, target, task) {
-  const { getStore } = await import("./core-6IY5L6II.js");
+  const { getStore } = await import("./core-TSXA5XZH.js");
   const store = await getStore(projectRoot);
   try {
     let view = VIEWS.general;

package/dist/{chunk-533LR4I7.js → chunk-G4U3QOOW.js}

@@ -1,93 +1,3 @@
-// src/intercept/stats.ts
-var ESTIMATED_TOKENS_PER_READ_DENY = 1200;
-function summarizeHookLog(entries) {
-  const byEvent = {};
-  const byTool = {};
-  const byDecision = {};
-  let readDenyCount = 0;
-  let firstEntryTs = null;
-  let lastEntryTs = null;
-  for (const entry of entries) {
-    const event = entry.event ?? "unknown";
-    byEvent[event] = (byEvent[event] ?? 0) + 1;
-    const tool = entry.tool ?? "unknown";
-    byTool[tool] = (byTool[tool] ?? 0) + 1;
-    if (entry.decision) {
-      byDecision[entry.decision] = (byDecision[entry.decision] ?? 0) + 1;
-    }
-    if (event === "PreToolUse" && tool === "Read" && entry.decision === "deny") {
-      readDenyCount += 1;
-    }
-    const ts = entry.ts;
-    if (typeof ts === "string") {
-      if (firstEntryTs === null || ts < firstEntryTs) firstEntryTs = ts;
-      if (lastEntryTs === null || ts > lastEntryTs) lastEntryTs = ts;
-    }
-  }
-  return {
-    totalInvocations: entries.length,
-    byEvent: Object.freeze(byEvent),
-    byTool: Object.freeze(byTool),
-    byDecision: Object.freeze(byDecision),
-    readDenyCount,
-    estimatedTokensSaved: readDenyCount * ESTIMATED_TOKENS_PER_READ_DENY,
-    firstEntry: firstEntryTs,
-    lastEntry: lastEntryTs
-  };
-}
-function formatStatsSummary(summary) {
-  if (summary.totalInvocations === 0) {
-    return "engram hook stats: no log entries yet.\n\nRun engram install-hook in a project, then use Claude Code to see interceptions.";
-  }
-  const lines = [];
-  lines.push(`engram hook stats (${summary.totalInvocations} invocations)`);
-  lines.push("\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
-  if (summary.firstEntry && summary.lastEntry) {
-    lines.push(`Time range: ${summary.firstEntry} \u2192 ${summary.lastEntry}`);
-    lines.push("");
-  }
-  lines.push("By event:");
-  const eventEntries = Object.entries(summary.byEvent).sort(
-    (a, b) => b[1] - a[1]
-  );
-  for (const [event, count] of eventEntries) {
-    const pct = (count / summary.totalInvocations * 100).toFixed(1);
-    lines.push(`  ${event.padEnd(18)} ${String(count).padStart(5)} (${pct}%)`);
-  }
-  lines.push("");
-  lines.push("By tool:");
-  const toolEntries = Object.entries(summary.byTool).filter(([k]) => k !== "unknown").sort((a, b) => b[1] - a[1]);
-  for (const [tool, count] of toolEntries) {
-    lines.push(`  ${tool.padEnd(18)} ${String(count).padStart(5)}`);
-  }
-  if (toolEntries.length === 0) {
-    lines.push("  (no tool-tagged entries)");
-  }
-  lines.push("");
-  const decisionEntries = Object.entries(summary.byDecision);
-  if (decisionEntries.length > 0) {
-    lines.push("PreToolUse decisions:");
-    for (const [decision, count] of decisionEntries.sort(
-      (a, b) => b[1] - a[1]
-    )) {
-      lines.push(`  ${decision.padEnd(18)} ${String(count).padStart(5)}`);
-    }
-    lines.push("");
-  }
-  if (summary.readDenyCount > 0) {
-    lines.push(
-      `Estimated tokens saved: ~${summary.estimatedTokensSaved.toLocaleString()}`
-    );
-    lines.push(
-      `  (${summary.readDenyCount} Read denies \xD7 ${ESTIMATED_TOKENS_PER_READ_DENY} tok/deny avg)`
-    );
-  } else {
-    lines.push("Estimated tokens saved: 0");
-    lines.push("  (no PreToolUse:Read denies recorded yet)");
-  }
-  return lines.join("\n");
-}
-
 // src/intercept/component-status.ts
 import { existsSync, readFileSync, writeFileSync } from "fs";
 import { join, dirname } from "path";
@@ -112,10 +22,16 @@ function checkHttp(projectRoot) {
 }
 function checkLsp(projectRoot) {
   if (existsSync(join(projectRoot, ".engram", "lsp-available"))) return true;
+  const uid = typeof process.getuid === "function" ? process.getuid() : 0;
   const tmp = tmpdir();
   const candidates = [
-    join(tmp, "tsserver.sock"),
-    join(tmp, "typescript-language-server.sock")
+    join(tmp, `tsserver-${uid}.sock`),
+    join(tmp, "lsp-server.sock"),
+    join(tmp, "typescript-language-server.sock"),
+    join(tmp, `pyright-${uid}.sock`),
+    join(tmp, "rust-analyzer.sock"),
+    // Legacy name kept for back-compat with older tsserver installs.
+    join(tmp, "tsserver.sock")
   ];
   return candidates.some((c) => existsSync(c));
 }
@@ -123,10 +39,12 @@ function checkAst(projectRoot) {
   try {
     const here = dirname(fileURLToPath(import.meta.url));
     const candidates = [
+      join(here, "grammars"),
+      // flattened bundle
       join(here, "..", "grammars"),
-      // from dist/intercept/
+      // nested bundle
       join(here, "..", "..", "dist", "grammars")
-      // from src/intercept/ dev
+      // dev-time
     ];
     for (const dir of candidates) {
       if (existsSync(dir)) return true;
@@ -212,9 +130,7 @@ function formatHudStatus(report) {
 }
 
 export {
-  ESTIMATED_TOKENS_PER_READ_DENY,
-  summarizeHookLog,
-  formatStatsSummary,
+  refreshComponentStatus,
   getComponentStatus,
   formatHudStatus
 };

package/dist/chunk-N6PPKOPK.js

@@ -0,0 +1,105 @@
+// src/server/auth.ts
+import { randomBytes } from "crypto";
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync
+} from "fs";
+import { homedir } from "os";
+import { join } from "path";
+var TOKEN_MIN_LEN = 32;
+var TOKEN_BYTES = 32;
+function tokenDir() {
+  return join(homedir(), ".engram");
+}
+function tokenPath() {
+  return join(tokenDir(), "http-server.token");
+}
+function getOrCreateToken() {
+  const envToken = process.env.ENGRAM_API_TOKEN;
+  if (envToken && envToken.length >= TOKEN_MIN_LEN) {
+    return { token: envToken, source: "env", path: null };
+  }
+  const path = tokenPath();
+  if (existsSync(path)) {
+    try {
+      const cached = readFileSync(path, "utf8").trim();
+      if (cached.length >= TOKEN_MIN_LEN) {
+        return { token: cached, source: "file", path };
+      }
+    } catch {
+    }
+  }
+  const fresh = randomBytes(TOKEN_BYTES).toString("hex");
+  const dir = tokenDir();
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(path, fresh + "\n", { mode: 384 });
+  try {
+    chmodSync(path, 384);
+  } catch {
+  }
+  return { token: fresh, source: "generated", path };
+}
+function safeEqual(a, b) {
+  if (a.length === 0 || b.length === 0) return false;
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) {
+    diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return diff === 0;
+}
+function parseCookies(header) {
+  const out = {};
+  if (!header || typeof header !== "string") return out;
+  for (const pair of header.split(/;\s*/)) {
+    const eq = pair.indexOf("=");
+    if (eq < 0) continue;
+    const key = pair.slice(0, eq).trim();
+    const value = pair.slice(eq + 1).trim();
+    if (key) out[key] = value;
+  }
+  return out;
+}
+function isHostValid(hostHeader, port) {
+  if (!hostHeader) return false;
+  let hostname;
+  let portStr;
+  if (hostHeader.startsWith("[")) {
+    const close = hostHeader.indexOf("]");
+    if (close < 0) return false;
+    hostname = hostHeader.slice(1, close);
+    portStr = hostHeader.slice(close + 2);
+  } else {
+    const colon = hostHeader.lastIndexOf(":");
+    if (colon < 0) {
+      hostname = hostHeader;
+      portStr = "";
+    } else {
+      hostname = hostHeader.slice(0, colon);
+      portStr = hostHeader.slice(colon + 1);
+    }
+  }
+  const h = hostname.toLowerCase();
+  if (h !== "127.0.0.1" && h !== "localhost" && h !== "::1") return false;
+  if (portStr !== String(port)) return false;
+  return true;
+}
+function isOriginAllowed(origin, port) {
+  if (origin === `http://127.0.0.1:${port}`) return true;
+  if (origin === `http://localhost:${port}`) return true;
+  const env = process.env.ENGRAM_ALLOWED_ORIGINS;
+  if (!env) return false;
+  const list = env.split(",").map((s) => s.trim()).filter(Boolean);
+  return list.includes(origin);
+}
+
+export {
+  getOrCreateToken,
+  safeEqual,
+  parseCookies,
+  isHostValid,
+  isOriginAllowed
+};