@hienlh/ppm 0.23.11 → 0.23.12

package/src/services/android/sdk-discovery.ts

@@ -0,0 +1,178 @@
+/**
+ * Where the Android SDK is, and which of its tools this host actually has.
+ *
+ * Resolution order (plan §5): the path the user configured -> the standard Android env vars ->
+ * the per-OS default location -> whatever is on PATH. Everything here is read-only and safe to
+ * call when no SDK exists; the answer then carries the reasons, which is what the setup screen
+ * renders instead of an indefinite spinner.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { homedir, platform } from "node:os";
+import { join, resolve } from "node:path";
+
+export interface SdkTool {
+  /** Absolute path to the binary, or null when this host does not have it. */
+  path: string | null;
+  /** Version string as the tool itself reports it, when it could be run. */
+  version: string | null;
+}
+
+export interface AndroidSdk {
+  root: string | null;
+  /** Which step of the resolution order answered, for the setup screen to explain itself. */
+  source: "configured" | "env" | "default-location" | "path" | "not-found";
+  emulator: SdkTool;
+  adb: SdkTool;
+  avdmanager: SdkTool;
+  sdkmanager: SdkTool;
+  /** AVD home in force for this process, and whether it came from the environment. */
+  avdHome: string;
+  avdHomeFromEnv: boolean;
+}
+
+const exe = (name: string) => (platform() === "win32" ? `${name}.exe` : name);
+const bat = (name: string) => (platform() === "win32" ? `${name}.bat` : name);
+
+/** Per-OS default SDK locations, in the order Android's own tooling looks. */
+function defaultSdkLocations(): string[] {
+  const home = homedir();
+  switch (platform()) {
+    case "darwin":
+      return [join(home, "Library", "Android", "sdk")];
+    case "win32":
+      return [
+        join(process.env.LOCALAPPDATA ?? join(home, "AppData", "Local"), "Android", "Sdk"),
+      ];
+    default:
+      return [join(home, "Android", "Sdk"), join(home, "android-sdk")];
+  }
+}
+
+function looksLikeSdk(dir: string): boolean {
+  // An SDK root always has at least one of these; a bare directory that merely exists does not.
+  return existsSync(join(dir, "emulator")) || existsSync(join(dir, "platform-tools"));
+}
+
+/**
+ * The AVD home this process would use.
+ *
+ * `ANDROID_AVD_HOME` **replaces** the default rather than adding to it — measured: with it set,
+ * `emulator -list-avds` shows only the AVDs under it and the user's own disappear entirely. So
+ * PPM must never set it process-wide; it is read here only to report what is in force.
+ */
+export function resolveAvdHome(): { dir: string; fromEnv: boolean } {
+  const env = process.env.ANDROID_AVD_HOME?.trim();
+  if (env) return { dir: resolve(env), fromEnv: true };
+  return { dir: join(homedir(), ".android", "avd"), fromEnv: false };
+}
+
+/**
+ * The env an SDK **child process** needs to work in a given AVD home.
+ *
+ * `ANDROID_AVD_HOME` **replaces** the default rather than adding to it (measured in Phase 0), so
+ * PPM must never set it process-wide — but a child that is meant to act on a non-default home
+ * has no other way to be told. Measured the hard way: `avdmanager create avd` without this
+ * writes into **`~/.android/avd`**, i.e. straight into the user's own AVDs, whatever home PPM
+ * was asked to use.
+ *
+ * Left unset when the home already *is* the default, so the common case runs with the exact
+ * environment the tools expect.
+ */
+export function avdHomeEnv(avdHome: string): NodeJS.ProcessEnv {
+  const env = { ...process.env };
+  const defaultHome = join(homedir(), ".android", "avd");
+  if (avdHome && resolve(avdHome) !== defaultHome) env.ANDROID_AVD_HOME = resolve(avdHome);
+  return env;
+}
+
+async function toolVersion(path: string, args: string[], pick: (out: string) => string | null): Promise<string | null> {
+  try {
+    const proc = Bun.spawn([path, ...args], { stdout: "pipe", stderr: "pipe", windowsHide: true });
+    const [out, errOut] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+    ]);
+    await proc.exited;
+    return pick(`${out}\n${errOut}`);
+  } catch {
+    // Bun.spawn THROWS synchronously on a missing binary rather than reporting it (see
+    // `host-info/spawn-runner.ts`), and the throw escapes an awaited try placed further out.
+    return null;
+  }
+}
+
+function firstLine(out: string): string | null {
+  const line = out.split("\n").map((l) => l.trim()).find((l) => l.length > 0);
+  return line ?? null;
+}
+
+async function describeTool(
+  candidate: string | null,
+  args: string[],
+  pick: (out: string) => string | null,
+): Promise<SdkTool> {
+  if (!candidate || !existsSync(candidate)) return { path: null, version: null };
+  return { path: candidate, version: await toolVersion(candidate, args, pick) };
+}
+
+/** Resolve the SDK and probe its tools. Never throws: a host with no SDK gets a populated shape. */
+export async function discoverSdk(configuredRoot?: string | null): Promise<AndroidSdk> {
+  let root: string | null = null;
+  let source: AndroidSdk["source"] = "not-found";
+
+  const configured = configuredRoot?.trim();
+  if (configured && looksLikeSdk(configured)) {
+    root = resolve(configured);
+    source = "configured";
+  }
+  if (!root) {
+    for (const key of ["ANDROID_HOME", "ANDROID_SDK_ROOT"]) {
+      const v = process.env[key]?.trim();
+      if (v && looksLikeSdk(v)) { root = resolve(v); source = "env"; break; }
+    }
+  }
+  if (!root) {
+    for (const dir of defaultSdkLocations()) {
+      if (looksLikeSdk(dir)) { root = dir; source = "default-location"; break; }
+    }
+  }
+
+  // PATH is the last resort and only for adb: a loose `adb` on PATH (Linux distros package it
+  // separately from the SDK) is usable even when no SDK root exists.
+  const pathAdb = Bun.which("adb");
+  if (!root && pathAdb) source = "path";
+
+  const emulatorPath = root ? join(root, "emulator", exe("emulator")) : null;
+  const adbPath = root && existsSync(join(root, "platform-tools", exe("adb")))
+    ? join(root, "platform-tools", exe("adb"))
+    : pathAdb;
+  const cmdlineBin = root ? join(root, "cmdline-tools", "latest", "bin") : null;
+
+  const [emulator, adb, avdmanager, sdkmanager] = await Promise.all([
+    describeTool(emulatorPath, ["-version"], (o) =>
+      o.split("\n").find((l) => l.includes("Android emulator version"))?.trim() ?? null),
+    describeTool(adbPath, ["version"], firstLine),
+    describeTool(cmdlineBin ? join(cmdlineBin, bat("avdmanager")) : null, ["list", "target"],
+      () => "present"),
+    describeTool(cmdlineBin ? join(cmdlineBin, bat("sdkmanager")) : null, ["--version"], firstLine),
+  ]);
+
+  const avdHome = resolveAvdHome();
+  return {
+    root, source, emulator, adb, avdmanager, sdkmanager,
+    avdHome: avdHome.dir, avdHomeFromEnv: avdHome.fromEnv,
+  };
+}
+
+/** Whether an AVD's config.ini enables the hardware keyboard. */
+export function avdHasHardwareKeyboard(avdConfigIni: string): boolean {
+  try {
+    for (const line of readFileSync(avdConfigIni, "utf8").split("\n")) {
+      const t = line.trim();
+      if (t.startsWith("hw.keyboard=")) return t.slice("hw.keyboard=".length).trim() === "yes";
+    }
+  } catch {
+    // An unreadable config is reported as "no" so the UI warns rather than promising a keyboard.
+  }
+  return false;
+}

package/src/services/android/system-images.ts

@@ -0,0 +1,124 @@
+/**
+ * Which Android system images this host already has.
+ *
+ * Read from **disk**, not from `sdkmanager --list_installed`. Three reasons, all measured:
+ *
+ *  - `sdkmanager` takes seconds ("Loading local repository…") and prints a progress bar into
+ *    stdout that any parser has to strip; a tab that lists images on open would stall on it.
+ *  - Every installed image ships a `source.properties` carrying exactly what is needed — API
+ *    level, ABI, tag, a display description — so the subprocess buys nothing.
+ *  - A host with the images but no `cmdline-tools` (they are a separate SDK package) can still
+ *    create an AVD, and going through `sdkmanager` would report "no images" there.
+ *
+ * Installing a *new* image is deliberately not here: the plan is explicit that PPM must not
+ * accept an SDK licence or start a multi-gigabyte download on its own.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+export interface SystemImage {
+  /** The sdkmanager package path, e.g. `system-images;android-35;google_apis_playstore;x86_64`. */
+  id: string;
+  apiLevel: number | null;
+  abi: string;
+  /** `google_apis_playstore`, `default`, `android-automotive`… */
+  tag: string;
+  /** What Google calls it, e.g. "Google APIs PlayStore,Tablet". */
+  tagDisplay: string;
+  description: string;
+  /** `image.sysdir.1` wants this exact relative form, trailing slash included. */
+  sysdir: string;
+  /** True when the image carries Play Store — such an AVD cannot be rooted. */
+  playStore: boolean;
+  bytes: number;
+}
+
+function parseProperties(text: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const line of text.split("\n")) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0 || trimmed.startsWith("#")) continue;
+    const eq = trimmed.indexOf("=");
+    if (eq <= 0) continue;
+    out[trimmed.slice(0, eq).trim()] = trimmed.slice(eq + 1).trim();
+  }
+  return out;
+}
+
+/** Recursive size of an image directory, so the UI can say what a delete would free. */
+function directoryBytes(dir: string, depth = 0): number {
+  if (depth > 4) return 0;
+  let total = 0;
+  let entries;
+  try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return 0; }
+  for (const entry of entries) {
+    const full = join(dir, entry.name);
+    try {
+      if (entry.isDirectory()) total += directoryBytes(full, depth + 1);
+      else if (entry.isFile()) total += statSync(full).size;
+    } catch { /* it went away mid-walk */ }
+  }
+  return total;
+}
+
+/**
+ * The tree is `system-images/<api>/<tag>/<abi>/`, and only a directory with a
+ * `source.properties` counts — a half-deleted package leaves the directories behind.
+ */
+export function listSystemImages(sdkRoot: string | null): SystemImage[] {
+  if (!sdkRoot) return [];
+  const root = join(sdkRoot, "system-images");
+  if (!existsSync(root)) return [];
+
+  const images: SystemImage[] = [];
+  for (const api of safeList(root)) {
+    for (const tagDir of safeList(join(root, api))) {
+      for (const abi of safeList(join(root, api, tagDir))) {
+        const dir = join(root, api, tagDir, abi);
+        const propsPath = join(dir, "source.properties");
+        if (!existsSync(propsPath)) continue;
+
+        let props: Record<string, string>;
+        try { props = parseProperties(readFileSync(propsPath, "utf8")); } catch { continue; }
+
+        const apiLevel = Number(props["AndroidVersion.ApiLevel"]);
+        // `SystemImage.TagId` can be a comma list (`google_apis_playstore,tablet`); the first is
+        // the one the package path uses, and the rest are extra traits.
+        const tag = (props["SystemImage.TagId"] ?? tagDir).split(",")[0]!.trim();
+        images.push({
+          id: `system-images;${api};${tagDir};${abi}`,
+          apiLevel: Number.isFinite(apiLevel) ? apiLevel : null,
+          abi: props["SystemImage.Abi"] ?? abi,
+          tag,
+          tagDisplay: props["SystemImage.TagDisplay"] ?? tag,
+          description: props["Pkg.Desc"] ?? "",
+          sysdir: `system-images/${api}/${tagDir}/${abi}/`,
+          playStore: tagDir.includes("playstore") || tag.includes("playstore"),
+          bytes: directoryBytes(dir),
+        });
+      }
+    }
+  }
+  // Newest API first: that is almost always the one being reached for.
+  return images.sort((a, b) => (b.apiLevel ?? 0) - (a.apiLevel ?? 0) || a.id.localeCompare(b.id));
+}
+
+function safeList(dir: string): string[] {
+  try {
+    return readdirSync(dir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Whether an image can run on this host without full-system emulation.
+ *
+ * An arm64 image on an x86_64 host boots, and then takes minutes per screen — which reads as a
+ * broken emulator rather than the wrong ABI, so the picker says so before the AVD exists.
+ */
+export function abiMatchesHost(abi: string, hostArch = process.arch): boolean {
+  if (hostArch === "x64") return abi === "x86_64" || abi === "x86";
+  if (hostArch === "arm64") return abi === "arm64-v8a" || abi === "armeabi-v7a";
+  return true;
+}

package/src/services/chat.service.ts

@@ -10,6 +10,7 @@ import type {
   ChatEvent,
   ChatMessage,
   SendMessageOpts,
+  PrewarmInput,
 } from "../providers/provider.interface.ts";
 import { compareSessionsByActivity } from "../types/chat.ts";
 import { buildDesignInstructions } from "./design/design-instructions.ts";
@@ -21,6 +22,11 @@ import { scheduleTurnSnapshot } from "./design/design-turn-snapshot.ts";
 import { designMcpAccessFor } from "./design/mcp/design-mcp-access.ts";
 import { designMcpTokens } from "./design/mcp/design-mcp-tokens.ts";
 import { isTerminalAgentStatus } from "../shared/background-agent-status.ts";
+import { TraceRun, traceAbort, traceApproval, traceFollowUp } from "./session-trace/trace-recorder.ts";
+import type { TraceOrigin } from "../shared/session-trace.ts";
+
+/** What a caller passes to send: the provider's options plus which door the run came through. */
+export type ChatSendOpts = SendMessageOpts & { origin?: TraceOrigin };
 
 /**
  * Events after which a design session's files may have settled: the end of a turn, and a
@@ -65,6 +71,12 @@ class ChatService {
     return session;
   }
 
+  /** Start the process the next new chat in a project will run on, where the provider can. */
+  async prewarm(providerId: string | undefined, input: PrewarmInput): Promise<void> {
+    const provider = providerId ? providerRegistry.get(providerId) : providerRegistry.getDefault();
+    await provider?.prewarm?.(input);
+  }
+
   async resumeSession(
     providerId: string,
     sessionId: string,
@@ -110,18 +122,48 @@ class ChatService {
     return provider.deleteSession(sessionId);
   }
 
+  /**
+   * The one door every run goes through — WebSocket, scheduler, bots, group chat, Jira, CLI —
+   * which is why it is also where a run is written to the session trace. The trace observes
+   * and never alters: every event is yielded exactly as the provider produced it.
+   */
   async *sendMessage(
     providerId: string,
     sessionId: string,
     message: string,
-    opts?: SendMessageOpts,
+    opts?: ChatSendOpts,
+  ): AsyncIterable<ChatEvent> {
+    const { origin, ...sendOpts } = opts ?? {};
+    const run = new TraceRun({ sessionId, providerId, origin, message, opts: sendOpts });
+    let outcome: "completed" | "consumer_closed" | "failed" = "consumer_closed";
+    try {
+      yield* this.streamRun(run, providerId, sessionId, message, sendOpts);
+      outcome = "completed";
+    } catch (e) {
+      run.fail(e);
+      outcome = "failed";
+      throw e;
+    } finally {
+      run.end(outcome);
+    }
+  }
+
+  private async *streamRun(
+    run: TraceRun,
+    providerId: string,
+    sessionId: string,
+    message: string,
+    opts: SendMessageOpts,
   ): AsyncIterable<ChatEvent> {
     const provider = providerRegistry.get(providerId);
     if (!provider) {
-      yield { type: "error", message: `Provider "${providerId}" not found` };
+      const event: ChatEvent = { type: "error", message: `Provider "${providerId}" not found` };
+      run.observe(event);
+      yield event;
       return;
     }
     const prepared = await this.prepareSendOptions(providerId, sessionId, message, opts);
+    run.contextAdded(prepared.sharedContext, provider.supportsSharedContext ? "provider" : "message");
     this.rememberSharedContext(providerId, sessionId, prepared.sharedContext);
     let finished = false;
     let activeSessionId = sessionId;
@@ -156,6 +198,7 @@ class ChatService {
           // Not awaited: the snapshot is debounced and must never hold up or fail the turn.
           scheduleTurnSnapshot(activeSessionId, this.getSession(activeSessionId)?.projectPath);
         }
+        run.observe(event);
         yield event;
       }
       finished = true;
@@ -241,20 +284,54 @@ class ChatService {
   }
 
   /** Push a live follow-up through the same context policy as sendMessage. */
-  async pushMessage(providerId: string, sessionId: string, message: string, opts?: SendMessageOpts): Promise<void> {
+  async pushMessage(providerId: string, sessionId: string, message: string, opts?: ChatSendOpts): Promise<void> {
     const provider = providerRegistry.get(providerId);
     if (!provider) throw new Error(`Provider "${providerId}" not found`);
     const streaming = provider as typeof provider & {
       pushMessage?: (id: string, content: string, options: SendMessageOpts) => void;
     };
     if (!streaming.pushMessage) return;
-    const prepared = await this.prepareSendOptions(providerId, sessionId, message, opts);
+    const { origin, ...sendOpts } = opts ?? {};
+    const prepared = await this.prepareSendOptions(providerId, sessionId, message, sendOpts);
+    // Written before the push, so the input precedes every event it causes in the trace.
+    traceFollowUp(sessionId, providerId, message, {
+      ...sendOpts,
+      origin,
+      sharedContext: prepared.sharedContext,
+      contextVia: provider.supportsSharedContext ? "provider" : "message",
+    });
     streaming.pushMessage(sessionId,
       provider.supportsSharedContext ? message : withSharedContext(message, prepared.sharedContext),
       { ...prepared, sharedContext: provider.supportsSharedContext ? prepared.sharedContext : undefined });
     this.rememberSharedContext(providerId, sessionId, prepared.sharedContext);
   }
 
+  /**
+   * Stop a session's query. An input to the run like a message is, so it goes through here
+   * rather than straight to the provider — otherwise the trace shows a turn that just stops.
+   */
+  abortQuery(providerId: string, sessionId: string, reason: string, origin?: TraceOrigin): void {
+    const provider = providerRegistry.get(providerId);
+    if (!provider?.abortQuery) return;
+    traceAbort(sessionId, providerId, reason, origin);
+    provider.abortQuery(sessionId, reason);
+  }
+
+  /** Answer an approval request or a question, and record the answer in the trace. */
+  resolveApproval(
+    providerId: string,
+    sessionId: string,
+    requestId: string,
+    approved: boolean,
+    data?: unknown,
+    extra: { reason?: string; origin?: TraceOrigin } = {},
+  ): void {
+    const provider = providerRegistry.get(providerId);
+    if (typeof provider?.resolveApproval !== "function") return;
+    traceApproval(sessionId, providerId, requestId, approved, { data, ...extra });
+    provider.resolveApproval(requestId, approved, data);
+  }
+
   /** Look up a session across all providers (for WS handler) */
   getSession(sessionId: string): Session | null {
     for (const info of providerRegistry.listAll()) {

package/src/services/config.service.ts

@@ -16,7 +16,7 @@ import {
 
 /** Top-level config keys stored in the config table (not projects) */
 const CONFIG_TABLE_KEYS: (keyof PpmConfig)[] = [
-  "device_name", "port", "host", "theme", "auth", "ai", "telegram", "clawbot", "query_audit", "tunnel",
+  "device_name", "port", "host", "theme", "auth", "ai", "telegram", "clawbot", "query_audit", "session_trace", "tunnel",
 ];
 
 /** File filter config keys stored in the config table */

package/src/services/file-filter.service.ts

@@ -71,64 +71,5 @@ function dedup(arr: string[]): string[] {
   return [...new Set(arr)];
 }
 
-/**
- * Check if a relative path matches any of the given glob patterns.
- * Uses simple pattern-to-regex conversion (no external lib needed).
- * Patterns follow VS Code glob semantics: ** crosses dirs, * stays in one segment.
- */
-export function matchesGlob(relPath: string, patterns: string[]): boolean {
-  // Normalize path separators to forward slash
-  const normalized = relPath.split("\\").join("/");
-  return patterns.some((pattern) => matchSingleGlob(normalized, pattern));
-}
-
-function matchSingleGlob(relPath: string, pattern: string): boolean {
-  // Strip leading **/ for simpler matching — handled by regex
-  const re = globPatternToRegex(pattern);
-  return re.test(relPath);
-}
-
-/**
- * Convert a VS Code-style glob pattern to a RegExp.
- * Cached per unique pattern string for performance.
- */
-const regexCache = new Map<string, RegExp>();
-
-function globPatternToRegex(pattern: string): RegExp {
-  const cached = regexCache.get(pattern);
-  if (cached) return cached;
-
-  let p = pattern;
-  // Normalize path separators
-  p = p.split("\\").join("/");
-  // Strip leading ./
-  if (p.startsWith("./")) p = p.slice(2);
-
-  // Leading `**/` should match zero-or-more path segments, INCLUDING root.
-  // So `**/.git` matches both `.git` (at root) and `src/.git` (nested).
-  // Strip `**/` prefix here so it doesn't force a leading path; we handle it via optional group below.
-  const hasStarstarPrefix = p.startsWith("**/");
-  if (hasStarstarPrefix) p = p.slice(3);
-
-  const escaped = p
-    .replace(/[.+^${}()|[\]]/g, "\\$&") // escape regex special chars (not * ?)
-    .replace(/\*\*/g, "\x00")            // temp: ** placeholder
-    .replace(/\*/g, "[^/]*")             // * = within one path segment
-    .replace(/\x00/g, ".*")             // ** = any path
-    .replace(/\?/g, "[^/]");            // ? = single non-slash char
-
-  let re: RegExp;
-  if (hasStarstarPrefix) {
-    // `**/X` → match X at any depth including root: `(^|.*/)X(/|$)`
-    re = new RegExp(`(^|.*/)${escaped}(/|$)`);
-  } else if (p.includes("/")) {
-    // Anchored pattern with explicit path
-    re = new RegExp(`^${escaped}(/|$)`);
-  } else {
-    // Pattern with no slash (e.g. *.log) → match at any depth
-    re = new RegExp(`(^|/)${escaped}(/|$)`);
-  }
-
-  regexCache.set(pattern, re);
-  return re;
-}
+// Matching lives in its own module so the file index worker can use it without the config store.
+export { matchesGlob } from "./file-glob.ts";

package/src/services/file-glob.ts

@@ -0,0 +1,67 @@
+/**
+ * file-glob.ts
+ * VS Code-style glob matching for file excludes. Kept free of any import that reaches the
+ * config store or the database, because the file index worker runs it on its own thread.
+ */
+
+/**
+ * Check if a relative path matches any of the given glob patterns.
+ * Uses simple pattern-to-regex conversion (no external lib needed).
+ * Patterns follow VS Code glob semantics: ** crosses dirs, * stays in one segment.
+ */
+export function matchesGlob(relPath: string, patterns: string[]): boolean {
+  // Normalize path separators to forward slash
+  const normalized = relPath.split("\\").join("/");
+  return patterns.some((pattern) => matchSingleGlob(normalized, pattern));
+}
+
+function matchSingleGlob(relPath: string, pattern: string): boolean {
+  // Strip leading **/ for simpler matching — handled by regex
+  const re = globPatternToRegex(pattern);
+  return re.test(relPath);
+}
+
+/**
+ * Convert a VS Code-style glob pattern to a RegExp.
+ * Cached per unique pattern string for performance.
+ */
+const regexCache = new Map<string, RegExp>();
+
+function globPatternToRegex(pattern: string): RegExp {
+  const cached = regexCache.get(pattern);
+  if (cached) return cached;
+
+  let p = pattern;
+  // Normalize path separators
+  p = p.split("\\").join("/");
+  // Strip leading ./
+  if (p.startsWith("./")) p = p.slice(2);
+
+  // Leading `**/` should match zero-or-more path segments, INCLUDING root.
+  // So `**/.git` matches both `.git` (at root) and `src/.git` (nested).
+  // Strip `**/` prefix here so it doesn't force a leading path; we handle it via optional group below.
+  const hasStarstarPrefix = p.startsWith("**/");
+  if (hasStarstarPrefix) p = p.slice(3);
+
+  const escaped = p
+    .replace(/[.+^${}()|[\]]/g, "\\$&") // escape regex special chars (not * ?)
+    .replace(/\*\*/g, "\x00")            // temp: ** placeholder
+    .replace(/\*/g, "[^/]*")             // * = within one path segment
+    .replace(/\x00/g, ".*")             // ** = any path
+    .replace(/\?/g, "[^/]");            // ? = single non-slash char
+
+  let re: RegExp;
+  if (hasStarstarPrefix) {
+    // `**/X` → match X at any depth including root: `(^|.*/)X(/|$)`
+    re = new RegExp(`(^|.*/)${escaped}(/|$)`);
+  } else if (p.includes("/")) {
+    // Anchored pattern with explicit path
+    re = new RegExp(`^${escaped}(/|$)`);
+  } else {
+    // Pattern with no slash (e.g. *.log) → match at any depth
+    re = new RegExp(`(^|/)${escaped}(/|$)`);
+  }
+
+  regexCache.set(pattern, re);
+  return re;
+}