@indigoai-us/hq-cloud 6.14.43 → 6.14.45

package/src/cli/rescue-core.ts

@@ -435,6 +435,36 @@ export function runRescue(
   }
 }
 
+/**
+ * True when `root` is usable as a rescue target: an absolute path that is not
+ * a bare drive letter. Pure + exported for tests; `platformPath` defaults to
+ * the host `path` module so Windows and POSIX runtimes each apply their own
+ * absoluteness rules (tests pass `path.win32` / `path.posix` explicitly).
+ *
+ * Rejecting bare `C:` matters even though `path.win32.isAbsolute("C:")` is
+ * already false — the explicit pattern documents the exact field failure and
+ * guards against a future helper swap that treats drive-relative paths as
+ * absolute.
+ */
+export function isUsableRescueRoot(root: string, platformPath: path.PlatformPath = path): boolean {
+  if (/^[A-Za-z]:$/.test(root)) return false;
+  return platformPath.isAbsolute(root);
+}
+
+/**
+ * `fs.realpathSync` that converts failure into the rescue's clean error path
+ * (message + ExitError) instead of an uncaught exception. An uncaught throw
+ * here is what turned one bad `--hq-root` into a daily crash-loop on Windows.
+ */
+function realpathOrExit(p: string, err: (s: string) => void): string {
+  try {
+    return fs.realpathSync(p);
+  } catch (e) {
+    err(`error: cannot resolve --hq-root ${p}: ${e instanceof Error ? e.message : String(e)}\n`);
+    throw new ExitError(1);
+  }
+}
+
 function doRescue(
   cfg: Config,
   env: NodeJS.ProcessEnv,
@@ -445,16 +475,33 @@ function doRescue(
   // --- Resolve HQ root ---
   let hqRoot: string;
   if (cfg.hqRootOverride) {
+    // Windows field failure (2026-08-02): the menubar app's daily background
+    // core update crash-looped for days because `--hq-root` arrived as the
+    // bare drive letter `C:`. `isDir("C:")` is true (drive-relative, resolves
+    // against the per-drive cwd) but `fs.realpathSync("C:")` throws EISDIR,
+    // so every retry died with an uncaught exception — console-window
+    // flicker, git.exe 0xc0000142 dialogs, and no core updates ever landing.
+    // Fail closed with a diagnosable message instead: a rescue root must be
+    // an absolute directory path, and the error echoes the exact argv this
+    // process received so the daily log identifies the caller that mangled
+    // the path (the split happens upstream of this process).
+    if (!isUsableRescueRoot(cfg.hqRootOverride)) {
+      err(
+        `error: --hq-root must be an absolute path, got ${JSON.stringify(cfg.hqRootOverride)}.\n` +
+          `       argv: ${JSON.stringify(process.argv.slice(2))}\n`,
+      );
+      throw new ExitError(1);
+    }
     if (!isDir(cfg.hqRootOverride)) {
       // bash `cd` failure under set -e would abort; mirror as a generic error.
       err(`error: --hq-root ${cfg.hqRootOverride} is not a directory.\n`);
       throw new ExitError(1);
     }
-    hqRoot = fs.realpathSync(cfg.hqRootOverride);
+    hqRoot = realpathOrExit(cfg.hqRootOverride, err);
   } else {
     // Legacy default assumed the script lived at personal/skills/<skill>/.
     // The package's programmatic callers always pass --hq-root; fall back to cwd.
-    hqRoot = fs.realpathSync(process.cwd());
+    hqRoot = realpathOrExit(process.cwd(), err);
   }
 
   // HQ-root sanity gate — guards against wiping a non-HQ directory. `companies/`

package/src/cli/rescue-hq-root-guard.test.ts

@@ -23,7 +23,7 @@ import { execFileSync } from "child_process";
 import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
-import { runRescue } from "./rescue-core.js";
+import { isUsableRescueRoot, runRescue } from "./rescue-core.js";
 
 function hasGit(): boolean {
   try {
@@ -190,4 +190,43 @@ exec ${JSON.stringify(realGit)} "$@"
     expect(r.status, out).toBe(3);
     expect(out).toContain("does not look like an HQ root");
   });
+
+  // 2026-08-02 Windows field failure: `--hq-root C:` (a path mangled upstream
+  // of this process) crashed with an uncaught EISDIR from fs.realpathSync on
+  // every daily background attempt. The gate must fail CLOSED — clean exit 1,
+  // no throw — and echo the received argv so the log identifies the caller.
+  it("rejects a bare drive letter --hq-root with a clean exit and argv echo", () => {
+    const r = rescueDry("C:");
+    const out = `${r.stdout}\n${r.stderr}`;
+    expect(r.status, out).toBe(1);
+    expect(out).toContain("--hq-root must be an absolute path");
+    expect(out).toContain('"C:"');
+    expect(out).toContain("argv:");
+  });
+
+  it("rejects a relative --hq-root with a clean exit", () => {
+    const r = rescueDry("some/relative/dir");
+    const out = `${r.stdout}\n${r.stderr}`;
+    expect(r.status, out).toBe(1);
+    expect(out).toContain("--hq-root must be an absolute path");
+  });
+});
+
+describe("isUsableRescueRoot (pure)", () => {
+  it("rejects bare drive letters under both path flavors", () => {
+    expect(isUsableRescueRoot("C:", path.win32)).toBe(false);
+    expect(isUsableRescueRoot("z:", path.win32)).toBe(false);
+    expect(isUsableRescueRoot("C:", path.posix)).toBe(false);
+  });
+
+  it("accepts absolute roots for the matching platform", () => {
+    expect(isUsableRescueRoot("C:\\Users\\caio\\HQ", path.win32)).toBe(true);
+    expect(isUsableRescueRoot("/Users/caio/HQ", path.posix)).toBe(true);
+  });
+
+  it("rejects relative and drive-relative paths", () => {
+    expect(isUsableRescueRoot("Users\\caio\\HQ", path.win32)).toBe(false);
+    expect(isUsableRescueRoot("C:Users\\caio\\HQ", path.win32)).toBe(false);
+    expect(isUsableRescueRoot("some/dir", path.posix)).toBe(false);
+  });
 });

package/src/watch-roots.test.ts

@@ -0,0 +1,278 @@
+/**
+ * Tests for the watch-root planner.
+ *
+ * The invariant under test is the one the whole change exists for: the watcher
+ * must only register OS watches over paths that can actually upload. Before
+ * this planner, macOS/Windows placed ONE recursive `fs.watch` on hqRoot, so the
+ * OS delivered every event in the tree — including `repos/` (~26k dirs on a
+ * real HQ) and `workspace/worktrees/` (~62k dirs) — and each one was filtered
+ * out only AFTER it had already cost a syscall and an allocation.
+ *
+ * The planner walks the exclusion filter up front and returns the minimum set
+ * of watch roots that covers exactly the in-scope tree:
+ *   - `recursive`: the dir's entire subtree is in scope → one recursive watch.
+ *   - `shallow`:   the dir contains an excluded child → watch the dir itself
+ *                  non-recursively and descend into its in-scope children.
+ */
+
+import { mkdtemp, mkdir, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import { describe, expect, it } from "vitest";
+
+import { isCoveredByRecursiveRoot, planWatchRoots } from "./watch-roots.js";
+import type { WatchPathFilter } from "./watcher.js";
+
+const ROOT = path.resolve("/hq");
+
+/** Build the `listChildDirs` seam over a literal `absDir -> childNames` map. */
+function treeLister(tree: Record<string, string[]>) {
+  return (dir: string): string[] =>
+    (tree[dir] ?? []).map((name) => path.join(dir, name));
+}
+
+/**
+ * Build a filter shaped like the real one: `prefixes` are exact vault-relative
+ * prefixes (`repos`, `workspace/worktrees` — position-sensitive), `anySegment`
+ * names are excluded at any depth (`node_modules`, `.git`).
+ */
+function makeFilter(opts: {
+  prefixes?: string[];
+  anySegment?: string[];
+}): WatchPathFilter {
+  const prefixes = opts.prefixes ?? [];
+  const anySegment = new Set(opts.anySegment ?? []);
+  return (absolutePath: string): boolean => {
+    const rel = path.relative(ROOT, absolutePath).split(path.sep).join("/");
+    if (rel === "" || rel.startsWith("..")) return false;
+    if (prefixes.some((p) => rel === p || rel.startsWith(p + "/"))) return false;
+    if (rel.split("/").some((seg) => anySegment.has(seg))) return false;
+    return true;
+  };
+}
+
+/** Every dir the plan asks the OS to watch, recursive roots and shallow alike. */
+function allWatched(plan: { recursive: string[]; shallow: string[] }): string[] {
+  return [...plan.recursive, ...plan.shallow];
+}
+
+describe("planWatchRoots — minimal cover of the in-scope tree", () => {
+  it("collapses a fully in-scope tree to ONE recursive watch at the root", () => {
+    const plan = planWatchRoots(ROOT, makeFilter({}), {
+      listChildDirs: treeLister({
+        [ROOT]: ["companies", "core"],
+        [path.join(ROOT, "companies")]: ["acme"],
+      }),
+    });
+
+    expect(plan.recursive).toEqual([ROOT]);
+    expect(plan.shallow).toEqual([]);
+  });
+
+  it("never registers a watch on an excluded dir, and never covers one from a recursive root", () => {
+    const filter = makeFilter({
+      prefixes: ["repos"],
+      anySegment: ["node_modules"],
+    });
+    const plan = planWatchRoots(ROOT, filter, {
+      listChildDirs: treeLister({
+        [ROOT]: ["companies", "repos", "node_modules"],
+        [path.join(ROOT, "companies")]: ["acme"],
+        [path.join(ROOT, "repos")]: ["hq-cloud"],
+      }),
+    });
+
+    // The root has excluded children, so it cannot be a recursive root.
+    expect(plan.shallow).toContain(ROOT);
+    expect(plan.recursive).not.toContain(ROOT);
+    // `companies/` is clean, so it collapses to one recursive watch.
+    expect(plan.recursive).toContain(path.join(ROOT, "companies"));
+
+    // The point of the whole change: excluded trees are never watched at all.
+    for (const watched of allWatched(plan)) {
+      expect(watched).not.toContain(`${path.sep}repos`);
+      expect(watched).not.toContain("node_modules");
+    }
+  });
+
+  it("descends through a partially-excluded dir to reach its in-scope children", () => {
+    // `workspace/` is in scope but `workspace/worktrees/` (the 62k-dir bucket)
+    // is not — so `workspace` must be shallow and its siblings recursive.
+    const filter = makeFilter({ prefixes: ["workspace/worktrees"] });
+    const plan = planWatchRoots(ROOT, filter, {
+      listChildDirs: treeLister({
+        [ROOT]: ["workspace"],
+        [path.join(ROOT, "workspace")]: ["agency", "threads", "worktrees"],
+        [path.join(ROOT, "workspace", "worktrees")]: ["feature-a"],
+      }),
+    });
+
+    expect(plan.shallow).toEqual(
+      expect.arrayContaining([ROOT, path.join(ROOT, "workspace")]),
+    );
+    expect(plan.recursive).toEqual(
+      expect.arrayContaining([
+        path.join(ROOT, "workspace", "agency"),
+        path.join(ROOT, "workspace", "threads"),
+      ]),
+    );
+    expect(allWatched(plan)).not.toContain(
+      path.join(ROOT, "workspace", "worktrees"),
+    );
+  });
+
+  it("holds the invariant: no excluded path lies under any recursive root", () => {
+    const filter = makeFilter({
+      prefixes: ["repos", "workspace/worktrees"],
+      anySegment: ["node_modules", ".git"],
+    });
+    const tree: Record<string, string[]> = {
+      [ROOT]: [
+        "companies",
+        "core",
+        "workspace",
+        "repos",
+        ".git",
+        "node_modules",
+      ],
+      [path.join(ROOT, "companies")]: ["acme", "indigo"],
+      [path.join(ROOT, "core")]: ["skills"],
+      [path.join(ROOT, "workspace")]: ["agency", "worktrees"],
+      [path.join(ROOT, "workspace", "worktrees")]: ["wt-1"],
+      [path.join(ROOT, "repos")]: ["hq-cloud"],
+    };
+    const plan = planWatchRoots(ROOT, filter, {
+      listChildDirs: treeLister(tree),
+    });
+
+    const excludedDirs = Object.keys(tree)
+      .flatMap((dir) => (tree[dir] ?? []).map((n) => path.join(dir, n)))
+      .filter((p) => !filter(p, true));
+    expect(excludedDirs.length).toBeGreaterThan(0);
+
+    for (const excluded of excludedDirs) {
+      // Not watched directly...
+      expect(allWatched(plan)).not.toContain(excluded);
+      // ...and not swept in as a descendant of some recursive root either.
+      for (const root of plan.recursive) {
+        expect(excluded.startsWith(root + path.sep)).toBe(false);
+      }
+    }
+  });
+
+  it("stops descending at maxDepth and takes a recursive watch there", () => {
+    const filter = makeFilter({ anySegment: ["node_modules"] });
+    const plan = planWatchRoots(ROOT, filter, {
+      maxDepth: 1,
+      listChildDirs: treeLister({
+        [ROOT]: ["a", "node_modules"],
+        [path.join(ROOT, "a")]: ["b", "node_modules"],
+        [path.join(ROOT, "a", "b")]: ["c"],
+      }),
+    });
+
+    // Depth 0 has an excluded child → shallow. Depth 1 is the bound, so `a`
+    // takes a recursive watch even though it still contains node_modules; the
+    // per-event filter drops that residue. This bounds handle count on trees
+    // with deeply scattered exclusions.
+    expect(plan.shallow).toEqual([ROOT]);
+    expect(plan.recursive).toEqual([path.join(ROOT, "a")]);
+  });
+
+  it("skips a directory it cannot read instead of throwing", () => {
+    const plan = planWatchRoots(ROOT, makeFilter({ prefixes: ["repos"] }), {
+      listChildDirs: (dir: string) => {
+        if (dir === path.join(ROOT, "denied")) {
+          throw Object.assign(new Error("EACCES"), { code: "EACCES" });
+        }
+        return dir === ROOT
+          ? [path.join(ROOT, "denied"), path.join(ROOT, "repos")]
+          : [];
+      },
+    });
+
+    // The unreadable dir is still watched (we cannot see inside it to decide
+    // better) and the walk completes rather than crashing start().
+    expect(allWatched(plan)).toContain(path.join(ROOT, "denied"));
+    expect(allWatched(plan)).not.toContain(path.join(ROOT, "repos"));
+  });
+
+  it("reports every in-scope directory through onDirectory, and no excluded one", () => {
+    // TreeWatcher builds its known-kinds index from this callback instead of
+    // walking the same tree a second time, so the callback must cover every
+    // in-scope directory — including ones inside a collapsed recursive root.
+    const filter = makeFilter({ prefixes: ["repos"] });
+    const seen: string[] = [];
+    planWatchRoots(ROOT, filter, {
+      onDirectory: (dir) => seen.push(dir),
+      listChildDirs: treeLister({
+        [ROOT]: ["companies", "repos"],
+        [path.join(ROOT, "companies")]: ["acme"],
+        [path.join(ROOT, "companies", "acme")]: ["knowledge"],
+        [path.join(ROOT, "repos")]: ["hq-cloud"],
+      }),
+    });
+
+    expect(seen).toEqual([
+      path.join(ROOT, "companies"),
+      path.join(ROOT, "companies", "acme"),
+      path.join(ROOT, "companies", "acme", "knowledge"),
+    ]);
+    expect(seen).not.toContain(path.join(ROOT, "repos"));
+    expect(seen).not.toContain(path.join(ROOT, "repos", "hq-cloud"));
+  });
+
+  it("resolves coverage by walking ancestors, not by scanning every root", () => {
+    // This runs on EVERY rename event, in the hot path of a change whose whole
+    // point is cutting per-event cost. A linear scan is O(number of roots) —
+    // 685 on a real HQ tree — where an ancestor walk is O(path depth), ~10.
+    // The behavior must be identical, including the prefix trap below.
+    const roots = new Set([path.join(ROOT, "a", "b"), path.join(ROOT, "c")]);
+
+    expect(isCoveredByRecursiveRoot(path.join(ROOT, "a", "b"), roots)).toBe(true);
+    expect(
+      isCoveredByRecursiveRoot(path.join(ROOT, "a", "b", "deep", "x.md"), roots),
+    ).toBe(true);
+    expect(isCoveredByRecursiveRoot(path.join(ROOT, "a"), roots)).toBe(false);
+    expect(isCoveredByRecursiveRoot(path.join(ROOT, "d"), roots)).toBe(false);
+    // The prefix trap: `/hq/a/bc` shares a string prefix with root `/hq/a/b`
+    // but is NOT under it. A naive startsWith without the separator would say
+    // covered, and the whole subtree would go unwatched.
+    expect(isCoveredByRecursiveRoot(path.join(ROOT, "a", "bc"), roots)).toBe(
+      false,
+    );
+    expect(
+      isCoveredByRecursiveRoot(path.join(ROOT, "a", "bc", "x.md"), roots),
+    ).toBe(false);
+  });
+
+  it("reports nothing as covered when there are no recursive roots", () => {
+    expect(
+      isCoveredByRecursiveRoot(path.join(ROOT, "a", "b"), new Set<string>()),
+    ).toBe(false);
+  });
+
+  it("plans over a real directory tree using the default reader", async () => {
+    const root = await mkdtemp(path.join(tmpdir(), "hqcloud-planroots-"));
+    try {
+      await mkdir(path.join(root, "companies", "acme"), { recursive: true });
+      await mkdir(path.join(root, "repos", "hq-cloud", "src"), {
+        recursive: true,
+      });
+
+      const filter: WatchPathFilter = (abs) => {
+        const rel = path.relative(root, abs).split(path.sep).join("/");
+        if (rel === "" || rel.startsWith("..")) return false;
+        return rel !== "repos" && !rel.startsWith("repos/");
+      };
+      const plan = planWatchRoots(root, filter);
+
+      expect(plan.shallow).toContain(root);
+      expect(plan.recursive).toContain(path.join(root, "companies"));
+      expect(allWatched(plan)).not.toContain(path.join(root, "repos"));
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+});

package/src/watch-roots.ts

@@ -0,0 +1,162 @@
+/**
+ * Watch-root planner — reduce the in-scope tree to the smallest set of OS
+ * watches that covers exactly the paths that can upload.
+ *
+ * Why this exists: on macOS/Windows the watcher used to place ONE recursive
+ * `fs.watch` on hqRoot. That is cheap in handles but the OS then delivers every
+ * event in the tree, including the buckets sync never uploads — on a real HQ
+ * root that is `repos/` (~26k directories) and `workspace/worktrees/` (~62k),
+ * where agent builds, installs, and checkouts churn constantly. Every one of
+ * those events woke the runner, cost a `path.resolve` (plus a synchronous
+ * `lstat` for renames), and was then dropped by the emit filter. The result was
+ * a node process pinned above 100% CPU doing nothing but allocating and
+ * garbage-collecting discarded paths.
+ *
+ * The planner walks the exclusion filter ONCE at start and returns:
+ *   - `recursive`: directories whose entire subtree is in scope. One recursive
+ *     watch each; the OS never reports an excluded path under them.
+ *   - `shallow`: directories that contain an excluded descendant. Watched
+ *     non-recursively so their own files still fire, with their in-scope
+ *     children planned separately.
+ *
+ * The walk is post-order: whether a directory can collapse to a single
+ * recursive watch depends on its whole subtree, not just its direct children
+ * (`workspace/` looks clean until you reach `workspace/worktrees/`).
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+
+import type { WatchPathFilter } from "./watcher.js";
+
+export interface WatchRootPlan {
+  /** Directories to watch recursively — their whole subtree is in scope. */
+  recursive: string[];
+  /** Directories to watch non-recursively — they contain excluded children. */
+  shallow: string[];
+}
+
+export interface PlanWatchRootsOptions {
+  /**
+   * Optional depth at which the walk stops splitting and takes a recursive
+   * watch even if the subtree still holds exclusions. Unbounded by default:
+   * the walk costs about what {@link TreeWatcher}'s known-kinds seed walk
+   * already cost on every start, and the two are fused via `onDirectory`, so
+   * paying for full pruning is free. A bound trades pruning for walk time on
+   * pathologically deep trees; the per-event filter drops whatever residue it
+   * admits, so this is a performance dial, never a correctness one.
+   */
+  maxDepth?: number;
+  /** Directory reader seam — defaults to a real `readdirSync`. */
+  listChildDirs?: (dir: string) => string[];
+  /**
+   * Invoked once for every in-scope directory the walk visits. Lets a caller
+   * populate its own directory index in the SAME pass instead of walking the
+   * tree a second time.
+   */
+  onDirectory?: (absolutePath: string) => void;
+}
+
+function defaultListChildDirs(dir: string): string[] {
+  return fs
+    .readdirSync(dir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => path.join(dir, entry.name));
+}
+
+interface VisitResult {
+  /** True when every descendant of this directory is in scope. */
+  clean: boolean;
+  plan: WatchRootPlan;
+}
+
+/**
+ * Plan the watch roots for `hqRoot` under `shouldEmit`.
+ *
+ * `shouldEmit(dir, true)` is the same directory predicate the watcher uses at
+ * event time, so the plan and the emit filter can never disagree about what is
+ * in scope.
+ */
+export function planWatchRoots(
+  hqRoot: string,
+  shouldEmit: WatchPathFilter,
+  opts: PlanWatchRootsOptions = {},
+): WatchRootPlan {
+  const maxDepth = opts.maxDepth ?? Number.POSITIVE_INFINITY;
+  const listChildDirs = opts.listChildDirs ?? defaultListChildDirs;
+  const onDirectory = opts.onDirectory;
+  const root = path.resolve(hqRoot);
+
+  const visit = (dir: string, depth: number): VisitResult => {
+    let children: string[];
+    try {
+      children = listChildDirs(dir);
+    } catch {
+      // Unreadable (permissions, or a race with a concurrent delete). We cannot
+      // prove the subtree is clean, but dropping it would silently stop syncing
+      // it — take the recursive watch and let the per-event filter sort it out.
+      return { clean: true, plan: { recursive: [dir], shallow: [] } };
+    }
+
+    const included: string[] = [];
+    let hasExcludedChild = false;
+    for (const child of children) {
+      if (shouldEmit(child, true)) {
+        included.push(child);
+        onDirectory?.(path.resolve(child));
+      } else hasExcludedChild = true;
+    }
+
+    // At the depth bound we stop splitting. `clean` still reports what we can
+    // see one level down so an ancestor does not collapse over a known
+    // exclusion it could have pruned.
+    if (depth >= maxDepth) {
+      return {
+        clean: !hasExcludedChild,
+        plan: { recursive: [dir], shallow: [] },
+      };
+    }
+
+    const childResults = included.map((child) => visit(child, depth + 1));
+    const clean =
+      !hasExcludedChild && childResults.every((result) => result.clean);
+
+    // A clean subtree collapses to a single recursive watch here, discarding
+    // the per-child watches the recursion built below it.
+    if (clean) return { clean: true, plan: { recursive: [dir], shallow: [] } };
+
+    return {
+      clean: false,
+      plan: {
+        recursive: childResults.flatMap((result) => result.plan.recursive),
+        shallow: [dir, ...childResults.flatMap((result) => result.plan.shallow)],
+      },
+    };
+  };
+
+  return visit(root, 0).plan;
+}
+
+/**
+ * True when `absolutePath` already falls under one of `recursiveRoots`.
+ *
+ * Walks the path's own ancestors rather than scanning the root set: this runs
+ * on every rename event, in the hot path of a backend whose entire purpose is
+ * cutting per-event cost, and a real HQ tree plans ~685 roots. Ancestor-walking
+ * is O(path depth) — about ten set lookups — instead of O(roots) string
+ * comparisons. It also cannot fall into the shared-prefix trap, where `/hq/a/bc`
+ * looks like it sits under the root `/hq/a/b`.
+ */
+export function isCoveredByRecursiveRoot(
+  absolutePath: string,
+  recursiveRoots: ReadonlySet<string>,
+): boolean {
+  if (recursiveRoots.size === 0) return false;
+  let current = path.resolve(absolutePath);
+  for (;;) {
+    if (recursiveRoots.has(current)) return true;
+    const parent = path.dirname(current);
+    if (parent === current) return false;
+    current = parent;
+  }
+}