ashlr-plugin 1.36.4

package/hooks/session-start.ts

@@ -0,0 +1,993 @@
+#!/usr/bin/env bun
+/**
+ * ashlr SessionStart hook (TypeScript).
+ *
+ * Replaces the legacy bash session-start.sh. Two responsibilities:
+ *   1. Run the baseline scanner (cache-hit budget ~2s) and inject the result
+ *      as additionalContext so the agent sees a cheap project orientation.
+ *   2. Print the once-per-day activation notice (preserved from the bash
+ *      script) on stderr so it lands in Claude Code's transcript.
+ *
+ * Hook contract (SessionStart):
+ *   stdout → { hookSpecificOutput: { hookEventName: "SessionStart",
+ *                                    additionalContext?: string } }
+ *
+ * Per Claude Code's hook docs, the `additionalContext` field for SessionStart
+ * is appended to the system prompt for the new session, so the baseline lands
+ * in the agent's visible context window automatically.
+ *
+ * Design rules:
+ *   - Never throw — pass-through on any error.
+ *   - 2-second budget: if scan blows the budget we still emit *something*
+ *     (an empty additionalContext) rather than hang the session.
+ */
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, unlinkSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { basename, dirname, join } from "path";
+import { spawn } from "child_process";
+
+import { formatBaseline, scan } from "../scripts/baseline-scan";
+import { greet as sessionGreet } from "../scripts/session-greet";
+import { initSessionBucket } from "../servers/_stats";
+import { cwdLooksLikePluginRoot } from "../servers/_cwd-clamp";
+import {
+  isFirstRun,
+  writeStamp,
+  stampPath,
+  readOnboardingState,
+  onboardingStatePath,
+  restartRequiredPath,
+} from "../scripts/onboarding-wizard";
+import { checkForUpdate } from "../scripts/auto-update";
+import { runCloudPull } from "../scripts/genome-cloud-pull";
+import { syncCloudDeltas, type Tier } from "../scripts/genome-cloud-sync";
+import { isTelemetryEnabled, maybeTelemetryConsentNotice } from "../servers/_telemetry";
+import { maybeCloudPull } from "../scripts/stats-cloud-pull.ts";
+
+/**
+ * Template for the once-per-day activation notice. Placeholders are filled
+ * in at runtime by `buildActivationNotice()` so the version + skill count
+ * can never drift from the actual installed plugin (v1.17 had this wrong
+ * because the values were hardcoded).
+ */
+export const ACTIVATION_NOTICE_TEMPLATE =
+  "ashlr-plugin v{version} active — Windows/macOS/Linux · {toolCount} skills · /ashlr-start for the onboarding wizard · /ashlr-upgrade to go Pro from the terminal.";
+
+/**
+ * Default plugin root — resolves to this hook's parent directory when
+ * CLAUDE_PLUGIN_ROOT isn't set (e.g. during tests that import buildResponse
+ * directly).
+ */
+function defaultPluginRoot(): string {
+  return process.env.CLAUDE_PLUGIN_ROOT ?? join(import.meta.dir, "..");
+}
+
+/**
+ * Read the plugin's current version from .claude-plugin/plugin.json. Returns
+ * a fallback of "unknown" if anything goes wrong — the banner is decoration,
+ * it must never throw.
+ */
+export function readPluginVersion(pluginRoot: string = defaultPluginRoot()): string {
+  try {
+    const pj = JSON.parse(
+      readFileSync(join(pluginRoot, ".claude-plugin", "plugin.json"), "utf-8"),
+    ) as { version?: unknown };
+    if (typeof pj.version === "string" && pj.version.trim()) return pj.version.trim();
+  } catch {
+    /* ignore */
+  }
+  return "unknown";
+}
+
+/**
+ * Count the number of user-facing skills shipped by the plugin. Each slash
+ * command (e.g. /ashlr-start) is one `.md` file under commands/, so we count
+ * those rather than the MCP tool list (which targets the model, not the user).
+ */
+export function readToolCount(pluginRoot: string = defaultPluginRoot()): number {
+  try {
+    const dir = join(pluginRoot, "commands");
+    if (!existsSync(dir)) return 0;
+    const st = statSync(dir);
+    if (!st.isDirectory()) return 0;
+    return readdirSync(dir).filter((n) => n.endsWith(".md")).length;
+  } catch {
+    return 0;
+  }
+}
+
+/** Render the activation notice with runtime-resolved version + tool count. */
+export function buildActivationNotice(
+  pluginRoot: string = defaultPluginRoot(),
+): string {
+  const version = readPluginVersion(pluginRoot);
+  const toolCount = readToolCount(pluginRoot);
+  return ACTIVATION_NOTICE_TEMPLATE.replace("{version}", version).replace(
+    "{toolCount}",
+    String(toolCount),
+  );
+}
+
+/**
+ * Back-compat shim: downstream tests/scripts import ACTIVATION_NOTICE as a
+ * bare string. We resolve it lazily at module load via the helpers above so
+ * the value is always in sync with plugin.json + the commands/ dir.
+ */
+export const ACTIVATION_NOTICE = buildActivationNotice();
+export const SCAN_BUDGET_MS = 2000;
+
+/**
+ * Ensure the plugin's dependencies are installed.
+ * Claude Code clones the plugin but does not run `bun install`, so on first
+ * session we detect the missing node_modules and bootstrap them silently.
+ * Idempotent: no-op when deps are already present.
+ *
+ * Runs in the background so the SessionStart hook never blocks the agent.
+ */
+const SEMVER_DIR_RE = /^[0-9]+\.[0-9]+\.[0-9]+$/;
+
+/**
+ * Remove sibling versioned cache directories for the ashlr plugin so only the
+ * current active version remains. This prevents ~/.claude/plugins/cache from
+ * growing unboundedly across plugin upgrades.
+ *
+ * Safety guards:
+ *   - Only acts when `${CLAUDE_PLUGIN_ROOT}` is set and its parent basename
+ *     matches strict semver (`X.Y.Z`). If the shape looks unexpected we do
+ *     nothing — never risk wiping user data.
+ *   - Only removes siblings whose basename also matches strict semver; any
+ *     other directory (e.g. `latest`, dotfiles, non-semver tags) is left
+ *     untouched.
+ *   - Wrapped in try/catch — never throws from inside a hook.
+ *
+ * Emits one stderr line when anything was removed.
+ */
+export function cleanupStalePluginVersions(
+  pluginRoot: string | undefined = process.env.CLAUDE_PLUGIN_ROOT,
+  opts: { logger?: (msg: string) => void } = {},
+): { removed: string[]; reason?: string } {
+  const log = opts.logger ?? ((m: string) => process.stderr.write(m));
+  try {
+    if (!pluginRoot) return { removed: [], reason: "no-plugin-root" };
+    // basename/dirname handle trailing separators on both POSIX and Windows,
+    // so the old `.replace(/\/+$/, "")` was a no-op on Windows (only stripped
+    // forward slashes) and redundant on POSIX.
+    const currentVersion = basename(pluginRoot);
+    if (!SEMVER_DIR_RE.test(currentVersion)) {
+      return { removed: [], reason: "unexpected-shape" };
+    }
+    const parent = dirname(pluginRoot);
+    if (!existsSync(parent)) return { removed: [], reason: "no-parent" };
+    // Only sweep inside Claude Code's plugin cache tree. Guards against a
+    // stray CLAUDE_PLUGIN_ROOT pointing at e.g. ~/.nvm/versions/node/1.0.0
+    // which would otherwise make us rm semver-shaped siblings. Normalize
+    // separators so the check works on Windows (\plugins\cache\) too.
+    if (!parent.replace(/\\/g, "/").includes("/plugins/cache/")) {
+      return { removed: [], reason: "parent-not-in-plugin-cache" };
+    }
+
+    const entries = readdirSync(parent, { withFileTypes: true });
+    const removed: string[] = [];
+    for (const ent of entries) {
+      if (!ent.isDirectory()) continue;
+      if (ent.name === currentVersion) continue;
+      if (!SEMVER_DIR_RE.test(ent.name)) continue;
+      const target = join(parent, ent.name);
+      try {
+        rmSync(target, { recursive: true, force: true });
+        removed.push(ent.name);
+      } catch {
+        /* ignore per-directory errors */
+      }
+    }
+    if (removed.length > 0) {
+      log(`[ashlr] cleaned ${removed.length} stale cache version(s): ${removed.join(", ")}\n`);
+    }
+    return { removed };
+  } catch {
+    return { removed: [], reason: "error" };
+  }
+}
+
+export function ensureDepsInstalled(pluginRoot?: string): void {
+  const root = pluginRoot ?? (process.env.CLAUDE_PLUGIN_ROOT || join(import.meta.dir, ".."));
+  // Cheap check (existsSync is sub-ms): if deps are present, no-op.
+  if (existsSync(join(root, "node_modules", "@modelcontextprotocol", "sdk"))) return;
+
+  // Deps missing. We MUST NOT block session-start — a slow/hung `bun install`
+  // would freeze Claude Code on first run. Spawn detached + unref so the
+  // install runs in the background while session-start returns immediately.
+  // This session may have reduced functionality until the install completes;
+  // the next session will see deps present and skip this branch entirely.
+  try {
+    process.stderr.write(
+      "[ashlr] first-run: dependencies missing — installing in the background. " +
+        "This session may have reduced functionality until install completes; " +
+        "subsequent sessions will start instantly.\n",
+    );
+    const child = spawn("bun", ["install"], {
+      cwd: root,
+      stdio: "ignore",
+      env: { ...process.env, CI: "1" },
+      detached: true,
+    });
+    // unref so the parent (this hook) can exit even if the child is still
+    // running. We deliberately do not await or attach 'close' handlers — the
+    // hook's job is to kick the install, not wait for it.
+    child.on("error", (e) => {
+      process.stderr.write(
+        "[ashlr-session-start] background bun install failed to spawn: " +
+          (e instanceof Error ? e.message : String(e)) +
+          ` — run manually: cd "${root}" && bun install\n`,
+      );
+    });
+    child.unref();
+  } catch (e) {
+    process.stderr.write(
+      "[ashlr-session-start] background bun install spawn failed: " +
+        (e instanceof Error ? e.message : String(e)) +
+        ` — run manually: cd "${root}" && bun install\n`,
+    );
+  }
+}
+
+interface HookOutput {
+  hookSpecificOutput: {
+    hookEventName: "SessionStart";
+    additionalContext?: string;
+  };
+}
+
+/**
+ * Path to `~/.ashlr/last-project.json` — a small hint file the MCP servers
+ * read to discover the user's real project directory.
+ *
+ * Why this file exists (v1.19.1 hotfix): Claude Code forwards
+ * `CLAUDE_PROJECT_DIR` to *hooks* but NOT to MCP subprocesses. Without this
+ * hint, the filesystem-touching MCP tools (ashlr__read, ashlr__grep, etc.)
+ * refuse any path outside their launch cwd — which is the plugin install
+ * dir under `.claude/plugins/cache/`, not the user's project. The redirect
+ * hook tells the model to call `ashlr__read` with an absolute project path,
+ * so without the hint the two halves dead-end each other. The session-start
+ * hook (which *does* see `CLAUDE_PROJECT_DIR`) writes this file so the MCP
+ * clamp can include the project dir in its allow-list.
+ */
+/**
+ * v1.19.2: stable session-id fallback when CLAUDE_SESSION_ID isn't visible.
+ * Uses process.ppid + home + a per-session random seed persisted to the
+ * hint file. Since this runs in SessionStart exactly once per session,
+ * the random component changes per session even when ppid recycles — which
+ * is what makes it session-unique across Claude Code restarts.
+ */
+function derivedSessionId(_home: string): string {
+  const seed = `h:${process.ppid ?? "?"}:${Date.now()}:${Math.random().toString(36).slice(2)}`;
+  let h = 0;
+  for (let i = 0; i < seed.length; i++) h = ((h << 5) - h + seed.charCodeAt(i)) | 0;
+  return `h${(h >>> 0).toString(16)}`;
+}
+
+export function projectHintPath(home: string = homedir()): string {
+  return join(home, ".ashlr", "last-project.json");
+}
+
+/**
+ * Window after a wizard-written `~/.ashlr/restart-required` hint within which
+ * we still consider the hint "fresh" enough to compare pids. Anything older
+ * is treated as stale — Claude Code obviously restarted at some point — and
+ * silently cleared. 60s is generous: a real user typing /quit + reopening
+ * normally takes 2–8s; an automation pipeline running the wizard headlessly
+ * gets the same grace period.
+ */
+export const RESTART_HINT_FRESHNESS_MS = 60_000;
+
+export interface MissedRestartResult {
+  /** What we decided: "no-hint" | "stale" | "restarted" | "missed". */
+  outcome: "no-hint" | "stale" | "restarted" | "missed" | "error";
+  /** True iff we deleted the hint file as part of this run. */
+  cleared: boolean;
+  /** Warning text written to stderr — null when no warning was emitted. */
+  warning: string | null;
+}
+
+/**
+ * The exact stderr warning emitted when a user finishes the wizard but
+ * doesn't restart Claude Code. Exported so tests can assert on it without
+ * fragile string-matching across the source.
+ */
+export const MISSED_RESTART_WARNING =
+  "[ashlr] WARNING: Wizard finished but Claude Code wasn't restarted. " +
+  "The next ashlr tool call will fall back to built-in Read/Edit/Grep. " +
+  "Run /quit then reopen Claude Code to register the plugin tools.\n";
+
+/**
+ * Read the wizard's restart-required hint and decide whether we need to
+ * warn the user. Addresses UX-audit cliff #2: the wizard says "restart"
+ * but Claude Code's hook execution model means *this* SessionStart can
+ * tell whether a restart actually happened by comparing the hint's pid
+ * with our own. Same pid + recent timestamp = same shell process = user
+ * skipped the restart and will hit built-in Read/Edit/Grep on next call.
+ *
+ * Decisions:
+ *   - No hint file        → no-op.
+ *   - Hint ≥60s old       → real restart happened at some point; clear silently.
+ *   - Hint <60s + different pid → new shell after restart; clear silently.
+ *   - Hint <60s + SAME pid → warn on stderr, leave hint in place so the
+ *     next *real* restart still detects + clears it.
+ *
+ * Wrapped end-to-end in try/catch — never errors the SessionStart hook.
+ * Filesystem-only, ~1ms — respects the v1.29 2s safety net by a wide margin.
+ */
+export function checkMissedRestart(
+  opts: {
+    home?: string;
+    now?: number;
+    pid?: number;
+    /** Test injection: override stderr writer. */
+    stderr?: (msg: string) => void;
+  } = {},
+): MissedRestartResult {
+  try {
+    const home = opts.home ?? (process.env.ASHLR_HOME_OVERRIDE?.trim() || homedir());
+    const now = opts.now ?? Date.now();
+    const myPid = opts.pid ?? process.pid;
+    const writeStderr = opts.stderr ?? ((m: string) => process.stderr.write(m));
+
+    const hintPath = restartRequiredPath(home);
+    if (!existsSync(hintPath)) return { outcome: "no-hint", cleared: false, warning: null };
+
+    let parsed: { writtenAt?: unknown; pid?: unknown; wizardVersion?: unknown };
+    try {
+      parsed = JSON.parse(readFileSync(hintPath, "utf-8"));
+    } catch {
+      // Corrupt JSON: best-effort cleanup so we don't loop forever.
+      try { unlinkSync(hintPath); } catch { /* ignore */ }
+      return { outcome: "error", cleared: true, warning: null };
+    }
+
+    const writtenAtRaw = typeof parsed.writtenAt === "string" ? parsed.writtenAt : "";
+    const writtenAtMs = writtenAtRaw ? Date.parse(writtenAtRaw) : NaN;
+    const hintPid = typeof parsed.pid === "number" ? parsed.pid : -1;
+
+    if (!Number.isFinite(writtenAtMs)) {
+      // Malformed timestamp — clear and move on.
+      try { unlinkSync(hintPath); } catch { /* ignore */ }
+      return { outcome: "error", cleared: true, warning: null };
+    }
+
+    const ageMs = now - writtenAtMs;
+    const fresh = ageMs < RESTART_HINT_FRESHNESS_MS && ageMs >= 0;
+
+    if (!fresh) {
+      // Hint is stale (or written in the future via clock skew) — Claude Code
+      // clearly restarted at some point. Clear silently.
+      try { unlinkSync(hintPath); } catch { /* ignore */ }
+      return { outcome: "stale", cleared: true, warning: null };
+    }
+
+    if (hintPid !== myPid) {
+      // Fresh hint but different process — Claude Code did restart, just
+      // very recently. Clear silently.
+      try { unlinkSync(hintPath); } catch { /* ignore */ }
+      return { outcome: "restarted", cleared: true, warning: null };
+    }
+
+    // Fresh hint AND same pid: the wizard ran in this exact shell and
+    // Claude Code was NOT restarted. Warn — but leave the hint alone so
+    // the next genuine restart still detects + clears it.
+    writeStderr(MISSED_RESTART_WARNING);
+    return { outcome: "missed", cleared: false, warning: MISSED_RESTART_WARNING };
+  } catch {
+    return { outcome: "error", cleared: false, warning: null };
+  }
+}
+
+/**
+ * Write the last-project hint. Picks up the project dir from
+ * `CLAUDE_PROJECT_DIR` (set by Claude Code in hook environments); no-ops
+ * silently when unset, when the dir doesn't exist, or on any write error —
+ * the hint is decoration, not a contract.
+ *
+ * Shape:
+ *   { "projectDir": "/absolute/path", "updatedAt": "2026-...", "sessionId": "..." }
+ *
+ * The `sessionId` hint lets future MCP tooling detect cross-session staleness
+ * cheaply (hook ran in session X, MCP spawned in session Y → possibly stale).
+ * The MCP clamp today uses a 24h TTL on `updatedAt` and ignores `sessionId`.
+ */
+export function writeProjectHint(
+  opts: {
+    home?: string;
+    projectDir?: string;
+    sessionId?: string;
+    now?: Date;
+  } = {},
+): { ok: boolean; reason?: string; path?: string } {
+  try {
+    const home = opts.home ?? (process.env.ASHLR_HOME_OVERRIDE?.trim() || homedir());
+    // Priority: explicit opt → CLAUDE_PROJECT_DIR env → process.cwd() (final
+    // fallback, guarded so we never write the plugin install dir into the
+    // hint). Claude Code does set the hook subprocess's cwd to the user's
+    // active project, but does not always forward CLAUDE_PROJECT_DIR — so
+    // without the cwd fallback every fresh session leaves the hint stale and
+    // the MCP cwd-clamp refuses every project-path call.
+    const envHint = (process.env.CLAUDE_PROJECT_DIR ?? "").trim();
+    const cwdFallback = (() => {
+      const c = process.cwd();
+      return cwdLooksLikePluginRoot(c) ? "" : c;
+    })();
+    const projectDir = opts.projectDir || envHint || cwdFallback;
+    if (!projectDir) return { ok: false, reason: "no-project-dir" };
+    // Only write when the path actually exists and is a directory — guards
+    // against a stale env or a race where the project was deleted mid-session.
+    try {
+      const st = statSync(projectDir);
+      if (!st.isDirectory()) return { ok: false, reason: "not-a-directory" };
+    } catch {
+      return { ok: false, reason: "stat-failed" };
+    }
+    // v1.19.2: sessionId is ALWAYS written. Priority: explicit opt → env
+    // (CLAUDE_SESSION_ID, ASHLR_SESSION_ID) → stable PPID-hash derived at
+    // session start. The deterministic fallback guarantees MCP + status-line
+    // readers converge on the SAME bucket even when neither sees the env.
+    const explicitSession =
+      opts.sessionId ??
+      process.env.CLAUDE_SESSION_ID ??
+      process.env.ASHLR_SESSION_ID;
+    const sessionId =
+      explicitSession && explicitSession.trim().length > 0
+        ? explicitSession.trim()
+        : derivedSessionId(home);
+    const payload: Record<string, string> = {
+      projectDir,
+      updatedAt: (opts.now ?? new Date()).toISOString(),
+      sessionId,
+    };
+    const path = projectHintPath(home);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(payload, null, 2));
+    return { ok: true, path };
+  } catch (err) {
+    return { ok: false, reason: err instanceof Error ? err.message : "write-failed" };
+  }
+}
+
+export function announceStampPath(home: string = homedir()): string {
+  return join(home, ".ashlr", "last-announce");
+}
+
+/** Returns the activation notice if it hasn't fired today, else null. */
+export function maybeActivationNotice(
+  home: string = homedir(),
+  today: string = new Date().toISOString().slice(0, 10),
+): string | null {
+  const stamp = announceStampPath(home);
+  let last = "";
+  try {
+    if (existsSync(stamp)) last = readFileSync(stamp, "utf-8").trim();
+  } catch {
+    /* ignore */
+  }
+  if (last === today) return null;
+  try {
+    mkdirSync(dirname(stamp), { recursive: true });
+    writeFileSync(stamp, today);
+  } catch {
+    /* ignore */
+  }
+  // Resolve the notice lazily so version + skill count reflect the plugin
+  // currently on disk — never a stale copy captured at module-load time.
+  return buildActivationNotice();
+}
+
+export interface BuildOpts {
+  dir?: string;
+  home?: string;
+  today?: string;
+  budgetMs?: number;
+  /** Override the scanner — used in tests. */
+  scanFn?: typeof scan;
+  formatFn?: typeof formatBaseline;
+}
+
+export interface BuildResult {
+  output: HookOutput;
+  notice: string | null;
+}
+
+/** Path to the first-run stamp file. Re-exported for tests. */
+export { stampPath, isFirstRun, writeStamp } from "../scripts/onboarding-wizard";
+
+// ---------------------------------------------------------------------------
+// Onboarding state machine
+// ---------------------------------------------------------------------------
+
+/**
+ * The three banner states:
+ *   "first"    — no onboarding.json: show consent + /ashlr-start CTA
+ *   "in-progress" — started but not completed: show "finish setup" hint
+ *   "done"     — completed or explicitly skipped: silent
+ */
+export type OnboardingBannerState = "first" | "in-progress" | "done";
+
+export function getOnboardingBannerState(home: string = homedir()): OnboardingBannerState {
+  // If the installed-at stamp doesn't exist it's truly first run.
+  if (isFirstRun(home)) return "first";
+
+  const state = readOnboardingState(home);
+  if (!state) {
+    // Stamp exists but no onboarding.json — treat as first run for the banner
+    // (wizard was never shown). This covers the case where the user was on an
+    // older version that wrote the stamp but not the onboarding.json.
+    return "first";
+  }
+  if (state.completed) return "done";
+  if (state.started) return "in-progress";
+  return "first";
+}
+
+/**
+ * Path to ~/.ashlr/config.json — used to persist permission consent decisions.
+ */
+export function ashlrConfigPath(home: string = homedir()): string {
+  return join(home, ".ashlr", "config.json");
+}
+
+/** Read ~/.ashlr/config.json, returning {} on any error. */
+export function readAshlrConfig(home: string = homedir()): Record<string, unknown> {
+  try {
+    const p = ashlrConfigPath(home);
+    if (!existsSync(p)) return {};
+    const raw = readFileSync(p, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return parsed as Record<string, unknown>;
+    }
+  } catch {
+    /* treat as empty */
+  }
+  return {};
+}
+
+/** Write a partial update into ~/.ashlr/config.json (merge, not replace). */
+export function writeAshlrConfig(
+  patch: Record<string, unknown>,
+  home: string = homedir(),
+): void {
+  try {
+    mkdirSync(join(home, ".ashlr"), { recursive: true });
+    const existing = readAshlrConfig(home);
+    const merged = { ...existing, ...patch };
+    writeFileSync(ashlrConfigPath(home), JSON.stringify(merged, null, 2) + "\n");
+  } catch {
+    /* best-effort */
+  }
+}
+
+/**
+ * Check whether the canonical mcp__plugin_ashlr_* wildcard is already in the
+ * user's ~/.claude/settings.json allow list.
+ */
+export function isAshlrWildcardPresent(home: string = homedir()): boolean {
+  try {
+    const settingsPath = join(home, ".claude", "settings.json");
+    if (!existsSync(settingsPath)) return false;
+    const raw = readFileSync(settingsPath, "utf-8");
+    const parsed = JSON.parse(raw) as { permissions?: { allow?: string[] } };
+    const allow = parsed?.permissions?.allow ?? [];
+    return allow.some(
+      (e) =>
+        e === "mcp__plugin_ashlr_*" ||
+        e === "mcp__ashlr-*" ||
+        /^mcp__plugin_ashlr_/.test(e) ||
+        /^mcp__ashlr(-|__)/.test(e),
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Determine whether we should auto-grant permissions this session.
+ * Returns false when:
+ *   - ASHLR_PERMISSIONS_CONSENT=skip env var is set
+ *   - ~/.ashlr/config.json has permissionsConsent === "declined"
+ *   - The wildcard is already in the allow list
+ */
+export function shouldAutoGrantPermissions(home: string = homedir()): boolean {
+  if (process.env.ASHLR_PERMISSIONS_CONSENT === "skip") return false;
+  const config = readAshlrConfig(home);
+  if (config.permissionsConsent === "declined") return false;
+  if (isAshlrWildcardPresent(home)) return false;
+  return true;
+}
+
+/**
+ * Auto-grant mcp__plugin_ashlr_* permissions by calling installPermissions
+ * programmatically. Records the result in ~/.ashlr/config.json.
+ *
+ * Returns the consent banner text to prepend to additionalContext, or null
+ * if the grant was skipped (already present / env opt-out / declined).
+ */
+export async function maybeAutoGrantPermissions(
+  home: string = homedir(),
+): Promise<string | null> {
+  if (!shouldAutoGrantPermissions(home)) return null;
+
+  try {
+    const settingsPath = join(home, ".claude", "settings.json");
+    const { installPermissions } = await import("../scripts/install-permissions.ts");
+    const result = await installPermissions({
+      settingsPath,
+      nonInteractive: true,
+    });
+
+    // Record that we granted so we don't re-prompt next session.
+    writeAshlrConfig(
+      {
+        permissionsConsent: "granted",
+        grantedAt: new Date().toISOString(),
+      },
+      home,
+    );
+
+    // Only emit the banner when we actually added entries (not already present).
+    if (result.added.length > 0 || result.alreadyPresent.length === 0) {
+      return (
+        "\nashlr: granting auto-allow for ashlr MCP tools so you don't see permission prompts.\n" +
+        "Run /ashlr-start to opt out, or set ASHLR_PERMISSIONS_CONSENT=skip to never auto-grant.\n"
+      );
+    }
+    return null;
+  } catch {
+    /* best-effort — never break the hook */
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Banner state machine
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns the additionalContext string that fires the onboarding wizard on
+ * first run, or null when the stamp already exists.
+ *
+ * Side effect: writes the stamp on first run so subsequent sessions skip it.
+ */
+export function maybeWizardTrigger(home: string = homedir()): string | null {
+  if (!isFirstRun(home)) return null;
+  writeStamp(home);
+  return (
+    "\n[ashlr] This is your first session with the ashlr-plugin. " +
+    "Please run /ashlr-start now to complete the 60-second onboarding wizard. " +
+    "It will check your setup, offer to approve tool permissions, show a live " +
+    "read demo, and optionally initialize a genome for this project.\n"
+  );
+}
+
+/**
+ * Returns an additionalContext banner based on the onboarding state machine:
+ *   first       → /ashlr-start CTA (0 tokens saved yet)
+ *   in-progress → "finish setup" hint with last step
+ *   done        → null (silent)
+ */
+export function buildOnboardingBanner(home: string = homedir()): string | null {
+  const bannerState = getOnboardingBannerState(home);
+  if (bannerState === "done") return null;
+
+  if (bannerState === "first") {
+    return (
+      "\n→ Run /ashlr-start for a 60-second guided setup. " +
+      "ashlr saved your last session 0 tokens (you haven't used it yet — let's fix that).\n"
+    );
+  }
+
+  // in-progress
+  const state = readOnboardingState(home);
+  const lastStep = state?.lastStep ?? 0;
+  return (
+    `\n→ Run /ashlr-start to finish setup (you stopped after step ${lastStep}).\n`
+  );
+}
+
+export function buildResponse(opts: BuildOpts = {}): BuildResult {
+  const home = opts.home ?? homedir();
+  const today = opts.today ?? new Date().toISOString().slice(0, 10);
+  const doScan = opts.scanFn ?? scan;
+  const doFormat = opts.formatFn ?? formatBaseline;
+
+  let baselineBlock = "";
+  try {
+    const b = doScan({ dir: opts.dir });
+    baselineBlock = doFormat(b);
+  } catch {
+    baselineBlock = "[ashlr baseline · unavailable]";
+  }
+
+  const notice = maybeActivationNotice(home, today);
+
+  // Banner state machine: first-run stamp write side-effect lives here.
+  // maybeWizardTrigger writes the stamp; buildOnboardingBanner reads state.
+  // We call maybeWizardTrigger first (for back-compat stamp semantics), then
+  // overlay the richer state-machine banner.
+  maybeWizardTrigger(home); // side-effect: write stamp on first run
+  const onboardingBanner = buildOnboardingBanner(home);
+
+  const additionalContext = onboardingBanner
+    ? baselineBlock + onboardingBanner
+    : baselineBlock;
+
+  return {
+    output: {
+      hookSpecificOutput: {
+        hookEventName: "SessionStart",
+        additionalContext,
+      },
+    },
+    notice,
+  };
+}
+
+/**
+ * Source ~/.ashlr/env if it exists, injecting KEY=VALUE lines into
+ * process.env. This makes ASHLR_PRO_TOKEN (and any other vars written by
+ * upgrade-flow.ts) available to all subsequent hook logic and sub-processes
+ * in this session — without requiring a shell restart.
+ */
+function sourceAshlrEnv(): void {
+  try {
+    const envFile = join(homedir(), ".ashlr", "env");
+    if (!existsSync(envFile)) return;
+    const content = readFileSync(envFile, "utf8");
+    for (const line of content.split("\n")) {
+      const trimmed = line.trim();
+      // Match: export KEY=VALUE  or  KEY=VALUE  (value may be quoted or bare)
+      const m = trimmed.match(/^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
+      if (!m) continue;
+      const key = m[1]!;
+      let val = m[2]!;
+      // Strip surrounding single or double quotes
+      if ((val.startsWith('"') && val.endsWith('"')) ||
+          (val.startsWith("'") && val.endsWith("'"))) {
+        val = val.slice(1, -1);
+      }
+      if (!(key in process.env)) {
+        // Only set if not already present — never override explicit env vars
+        process.env[key] = val;
+      }
+    }
+  } catch {
+    /* env file is decoration — 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
+ * subprocess. Always returns a definite tier — read failures = "free".
+ */
+async function detectTierForSync(): Promise<Tier> {
+  try {
+    const home = process.env.ASHLR_HOME_OVERRIDE?.trim() || homedir();
+    const cachePath = join(home, ".ashlr", "pro-token-cache.json");
+    if (!existsSync(cachePath)) return "free";
+    const c = JSON.parse(readFileSync(cachePath, "utf-8")) as {
+      valid?: boolean;
+      validatedAt?: string;
+      plan?: string;
+    };
+    if (c.valid !== true || !c.validatedAt) return "free";
+    const age = Date.now() - new Date(c.validatedAt).getTime();
+    if (age >= 7 * 24 * 60 * 60 * 1000) return "free";
+    if (c.plan === "team") return "team";
+    if (c.plan === "pro") return "pro";
+    return "free";
+  } catch {
+    return "free";
+  }
+}
+
+async function main(): Promise<void> {
+  // Source ~/.ashlr/env so ASHLR_PRO_TOKEN from the upgrade flow is available
+  // without requiring a shell restart.
+  sourceAshlrEnv();
+
+  // First-run: bootstrap dependencies if missing. Silent no-op otherwise.
+  ensureDepsInstalled();
+
+  // Post-upgrade hygiene: drop sibling cache versions that aren't the active
+  // one. Never throws (see cleanupStalePluginVersions for safety guards).
+  cleanupStalePluginVersions();
+
+  // v1.19.1 hotfix: Claude Code forwards CLAUDE_PROJECT_DIR to hooks but
+  // NOT to MCP subprocesses. Write the project dir to ~/.ashlr/last-project.json
+  // so filesystem-touching MCP tools (ashlr__read, ashlr__grep, etc.) can
+  // extend their cwd-clamp allow-list to the user's real workspace. Without
+  // this, the PreToolUse redirect hook sends the model to ashlr__read with
+  // an absolute project path that the clamp then refuses — a dead-end loop.
+  try { writeProjectHint(); } catch { /* hint is decoration — never break the hook */ }
+
+  // UX-audit cliff #2: warn when wizard finished but Claude Code wasn't
+  // restarted. Filesystem-only + ~1ms; respects the v1.29 2s safety net.
+  try { checkMissedRestart(); } catch { /* check is best-effort */ }
+
+  // Opt-in: when ASHLR_STATS_BACKEND=sqlite, move the legacy ~/.ashlr/stats.json
+  // into ~/.ashlr/stats.db once at session start so MCP workers open an
+  // already-initialized db and don't race on first-time schema creation.
+  // Never throws — stats writes must never block the agent.
+  if (process.env.ASHLR_STATS_BACKEND === "sqlite") {
+    try {
+      const { migrateStatsIfNeeded } = await import("../scripts/migrate-stats-to-sqlite");
+      await migrateStatsIfNeeded();
+    } catch {
+      /* best-effort */
+    }
+  }
+
+  // Drain stdin (Claude Code passes hook input as JSON) but we don't need it.
+  try {
+    // Best-effort, non-blocking-ish: only attempt if stdin is a pipe.
+    if (!process.stdin.isTTY) {
+      // Read but don't wait forever
+      await Promise.race([
+        (async () => {
+          for await (const _ of process.stdin as AsyncIterable<unknown>) {
+            // discard
+          }
+        })(),
+        new Promise((r) => setTimeout(r, 50)),
+      ]);
+    }
+  } catch {
+    /* ignore */
+  }
+
+  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,
+        )
+      ),
+    ]);
+  } catch {
+    result = {
+      output: { hookSpecificOutput: { hookEventName: "SessionStart" } },
+      notice: null,
+    };
+  }
+
+  if (result.notice) {
+    // stderr so it surfaces in the Claude Code transcript without polluting
+    // the JSON hook response on stdout.
+    process.stderr.write(result.notice + "\n");
+  }
+
+  // Auto-grant MCP permissions on first session (or when wildcard is absent).
+  // Runs after buildResponse so the consent banner is appended to the
+  // already-built additionalContext rather than racing the baseline scan.
+  try {
+    const consentBanner = await maybeAutoGrantPermissions();
+    if (consentBanner) {
+      const ctx = result.output.hookSpecificOutput.additionalContext ?? "";
+      result.output.hookSpecificOutput.additionalContext = ctx + consentBanner;
+    }
+  } catch {
+    /* best-effort — permissions grant never breaks the hook */
+  }
+
+  // Initialize the per-session bucket in ~/.ashlr/stats.json. This sets
+  // `startedAt` for the current CLAUDE_SESSION_ID so `/ashlr-savings` can
+  // report "session started Nm ago" accurately. Fire-and-forget — a stats
+  // write never blocks the hook response.
+  try { await initSessionBucket(); } catch { /* stats is decoration */ }
+
+  // Telemetry consent notice — shown once, only when user has opted in.
+  // Goes to stderr so it appears in the transcript but doesn't pollute stdout.
+  try {
+    const h = process.env.ASHLR_HOME_OVERRIDE?.trim() || homedir();
+    const telemetryNotice = maybeTelemetryConsentNotice(h);
+    if (telemetryNotice) process.stderr.write(telemetryNotice);
+  } catch {
+    /* decoration — never break the hook */
+  }
+
+  // Run the session-start greeting (first-run welcome / normal 1-liner /
+  // weekly digest). Writes to stderr; swallows its own errors. We run this
+  // AFTER the legacy notice so the greeting is the last thing the user sees
+  // in the transcript.
+  try {
+    sessionGreet();
+  } catch {
+    /* greeting is decoration — never break the hook */
+  }
+
+  // Fire-and-forget update check. Reads plugin.json for the current version,
+  // fetches the latest GitHub release (2s timeout), and prints a one-line
+  // notice to stderr at most once per day per upstream version.
+  //
+  // Defense-in-depth: checkForUpdate has its own internal 2s fetch timeout,
+  // but we wrap the call in an outer Promise.race so that *any* hang (DNS
+  // resolution, event-loop reference, unhandled await) can never keep the
+  // hook alive past 2 seconds. The promise is intentionally not awaited
+  // beyond this race so it never delays session-start.
+  try {
+    const pluginJsonPath = new URL("../.claude-plugin/plugin.json", import.meta.url).pathname;
+    const pluginJson = JSON.parse(readFileSync(pluginJsonPath, "utf-8")) as { version?: string };
+    const currentVersion = pluginJson.version ?? "";
+    // Race the update check against a hard 2s deadline. We swallow rejections
+    // here because checkForUpdate already does its own internal swallow; this
+    // 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) => {
+      process.stderr.write(
+        "[ashlr-session-start] update check failed: " +
+          (e instanceof Error ? e.message : String(e)) +
+          "\n",
+      );
+    });
+  } catch (e) {
+    process.stderr.write(
+      "[ashlr-session-start] update check setup failed: " +
+        (e instanceof Error ? e.message : String(e)) +
+        "\n",
+    );
+  }
+
+  // Best-effort cloud genome pull. No-ops silently when: kill switch set,
+  // no pro-token, not a git repo, or genome not yet ready. Never blocks.
+  try {
+    await runCloudPull();
+  } catch (e) {
+    process.stderr.write(
+      "[ashlr-session-start] cloud genome pull failed: " +
+        (e instanceof Error ? e.message : String(e)) +
+        "\n",
+    );
+  }
+
+  // Q2 cloud delta sync — Pro/Team only. Tier check happens inside the script
+  // (free → instant return). We race against a 2s hard ceiling so a stalled
+  // 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)),
+    ]);
+  } catch (e) {
+    process.stderr.write(
+      "[ashlr-session-start] cloud delta sync failed: " +
+        (e instanceof Error ? e.message : String(e)) +
+        "\n",
+    );
+  }
+
+  // Pro-gated: pull cross-machine aggregate stats (1h TTL cache). Best-effort
+  // fire-and-forget — the dashboard reads from cache, so this just warms it.
+  try { maybeCloudPull(); } catch { /* stats pull is decoration */ }
+
+  process.stdout.write(JSON.stringify(result.output));
+}
+
+if (import.meta.main) {
+  await main();
+}