@indigoai-us/hq-cloud 5.40.0 → 5.42.0

package/src/cli/sync.ts

@@ -8,6 +8,7 @@
 import * as fs from "fs";
 import * as path from "path";
 import type { VaultServiceConfig, SyncJournal } from "../types.js";
+import type { SyncMode } from "../vault-client.js";
 import { resolveEntityContext, isExpiringSoon, refreshEntityContext } from "../context.js";
 import { downloadFile, listRemoteFiles, headRemoteFile } from "../s3.js";
 import type { RemoteFile } from "../s3.js";
@@ -20,7 +21,19 @@ import {
   removeEntry,
   getEntry,
   normalizeEtag,
+  migrateToV2,
+  gcTombstones,
+  lastPullRecord,
+  appendPullRecord,
+  generatePullId,
 } from "../journal.js";
+import {
+  buildScopeShrinkPlan,
+  applyScopeShrink,
+  ScopeShrinkBlockedError,
+  ScopeShrinkLargePruneError,
+} from "../scope-shrink.js";
+import { coalescePrefixes, isCoveredByAny } from "../prefix-coalesce.js";
 import { createIgnoreFilter } from "../ignore.js";
 import { isEphemeralPath } from "./share.js";
 import { resolveConflict } from "./conflict.js";
@@ -255,6 +268,40 @@ export interface SyncOptions {
    * TS runner and Rust first-push share idempotency state.
    */
   journalSlug?: string;
+  /**
+   * Effective sync mode for this leg (US-005 wiring). Defaults to `"all"`
+   * when absent, preserving the legacy full-bucket pull. The runner resolves
+   * this from the membership's sync-config (`getMembershipSyncConfig`).
+   *
+   * SECURITY NOTE: this is a footprint/UX filter, NOT an authorization
+   * boundary. The security boundary is the server (STS credential scope +
+   * ACL). An owner's STS is wide (role-bypass), so this client-side scope is
+   * what makes selective download durable for owners — but it never grants
+   * access beyond what STS already permits.
+   */
+  syncMode?: SyncMode;
+  /**
+   * Coalesced, COMPANY-RELATIVE prefixes the current pull is scoped to when
+   * `syncMode` is `"shared"` or `"custom"` (same namespace as `RemoteFile.key`
+   * and the per-slug journal keys — e.g. `"knowledge/"`, `"projects/x/"`).
+   * Ignored when `syncMode` is `"all"`. The runner derives this from the
+   * caller's explicit grants (`shared`) or `customPaths` (`custom`) and is
+   * responsible for normalizing into the company-relative namespace.
+   *
+   * A `shared` leg with an empty/undefined `prefixSet` means "nothing is
+   * shared with me" → download nothing. The runner MUST fall back to `"all"`
+   * (not empty `"shared"`) on any grant-resolution error, so a transient
+   * failure can never silently prune the local tree.
+   */
+  prefixSet?: string[];
+  /**
+   * When the effective scope shrinks relative to the last pull and the shrink
+   * would orphan locally-modified ("dirty") files, `sync()` aborts with a
+   * `ScopeShrinkBlockedError` by default. Set `true` to proceed anyway:
+   * dirty files are LEFT ON DISK and only their journal entries are
+   * tombstoned. Mirrors `hq sync narrow --force`.
+   */
+  forceScopeShrink?: boolean;
 }
 
 export interface SyncResult {
@@ -297,6 +344,42 @@ export interface SyncResult {
    * disappeared from the remote.
    */
   filesTombstoned: number;
+  /**
+   * Count of remote keys NOT downloaded this run because they fall outside
+   * the effective `syncMode` scope (US-005). Always 0 in `all` mode. Distinct
+   * from `filesSkipped` (which measures "unchanged on this run") so consumers
+   * can render a "N outside your sync scope" line. The matching local cleanup
+   * of previously-downloaded-now-out-of-scope files is reported via
+   * `scopeOrphansRemoved`.
+   */
+  filesOutOfScope: number;
+  /**
+   * Clean local orphans deleted this run because a scope shrink moved them
+   * outside the effective scope (US-005). 0 when scope did not shrink.
+   */
+  scopeOrphansRemoved: number;
+  /**
+   * Dirty (locally-modified) orphans that a scope shrink would have pruned.
+   * When `forceScopeShrink` is false these are surfaced via a thrown
+   * `ScopeShrinkBlockedError` and the leg never reaches this result; when
+   * true they are left on disk and tombstoned, and counted here.
+   */
+  scopeOrphansBlocked: number;
+}
+
+/**
+ * Resolve the auto-prune safety cap (US-005 bulk-delete guard). An automatic
+ * scope shrink that would delete more than this many CLEAN local files in one
+ * pull is refused with `ScopeShrinkLargePruneError`. Default 100; `0` (or a
+ * non-positive / unparseable value) disables the cap (unlimited). Override via
+ * `HQ_SYNC_MAX_AUTO_PRUNE`.
+ */
+export function resolveAutoPruneCap(): number {
+  const raw = process.env.HQ_SYNC_MAX_AUTO_PRUNE;
+  if (raw === undefined || raw === "") return 100;
+  const parsed = Number.parseInt(raw, 10);
+  // NaN or negative → treat as "unlimited" (0) rather than silently capping.
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : 0;
 }
 
 /**
@@ -330,13 +413,32 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
     : path.join(hqRoot, "companies", ctx.slug);
   const shouldSync = createIgnoreFilter(hqRoot);
   const journalSlug = options.journalSlug ?? ctx.slug;
-  const journal = readJournal(journalSlug);
+  const startedAt = new Date().toISOString();
+  // Migrate v1 → v2 in place so the scope-shrink / pull-record machinery has
+  // its fields, and GC any tombstones past the 30-day retention window before
+  // we re-evaluate orphans (so a long-pruned path can re-download cleanly).
+  const journal = migrateToV2(readJournal(journalSlug));
+  gcTombstones(journal, Date.now());
+
+  // ── Effective download scope (US-005) ─────────────────────────────────────
+  // `all`  → prefixSet `[""]`, which `isCoveredByAny` treats as "covers
+  //          everything" — so the download filter and the scope-shrink
+  //          comparison both become no-ops, preserving legacy full-bucket
+  //          behavior bit-for-bit.
+  // `shared`/`custom` → the coalesced, company-relative prefix set the runner
+  //          resolved. An empty set means "nothing in scope" → download
+  //          nothing (the runner falls back to `all` on resolution errors, so
+  //          empty here is an intentional "nothing shared", never a failure).
+  const syncMode: SyncMode = options.syncMode ?? "all";
+  const currentPrefixSet =
+    syncMode === "all" ? [""] : coalescePrefixes(options.prefixSet ?? []);
 
   let filesDownloaded = 0;
   let bytesDownloaded = 0;
   let filesSkipped = 0;
   let conflicts = 0;
   let filesTombstoned = 0;
+  let filesOutOfScope = 0;
   const conflictPaths: string[] = [];
 
   // List all remote files (IAM session policy filters at the AWS layer)
@@ -353,6 +455,7 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
     options.personalMode === true,
     options.includeLocalCompanies === true,
     options.teamSyncedSlugs ?? null,
+    currentPrefixSet,
   );
 
   emit({
@@ -367,6 +470,83 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
     filesToDelete: 0,
   });
 
+  // ── Scope-shrink cleanup (US-005) ─────────────────────────────────────────
+  // If the effective scope narrowed since the last pull, files that were
+  // pulled under the old scope but fall outside the new one are orphans. We
+  // delete only CLEAN orphans (provably unchanged since last sync); dirty
+  // (locally-modified) orphans are sacred. By default a dirty orphan aborts
+  // the leg with a structured error the CLI renders; `forceScopeShrink` keeps
+  // dirty files on disk and only tombstones their journal entries.
+  //
+  // `companyRoot` is passed as the module's `hqRoot` so its `path.join(root,
+  // key)` resolves company-relative journal keys correctly (the scope-shrink
+  // module is namespace-agnostic — root + keys + prefixSet must simply agree).
+  //
+  // Note: this is the durable selective-download fix for OWNERS. An owner's
+  // STS is wide (role-bypass), so the remote LIST returns everything and the
+  // AWS layer never narrows the pull. This client-side shrink is what makes
+  // `hq sync mode shared` actually stick across re-syncs for an owner.
+  const lastRecord = lastPullRecord(journal, ctx.uid);
+  // A missing record, or a v1-migrated record with an empty prefixSet, means
+  // "no recorded scope" → treat the last scope as full-bucket `all` (`[""]`),
+  // per the PullRecord.prefixSet contract in types.ts.
+  const lastPrefixSet =
+    lastRecord && lastRecord.prefixSet.length > 0
+      ? lastRecord.prefixSet
+      : [""];
+  const shrinkPlan = buildScopeShrinkPlan({
+    journal,
+    hqRoot: companyRoot,
+    lastPrefixSet,
+    currentPrefixSet,
+  });
+  if (shrinkPlan.dirty.length > 0 && options.forceScopeShrink !== true) {
+    throw new ScopeShrinkBlockedError(
+      ctx.uid,
+      lastRecord?.syncMode ?? "unknown",
+      syncMode,
+      shrinkPlan.dirty,
+      shrinkPlan.clean,
+    );
+  }
+  // Bulk-delete guard: refuse to auto-prune more than the safety cap of CLEAN
+  // files in a single background sync. A deliberate large narrow goes through
+  // `hq sync narrow --apply` (its own confirmation), and `--force-scope-shrink`
+  // (or raising HQ_SYNC_MAX_AUTO_PRUNE) overrides. Cap of 0 = unlimited (opt
+  // out). The engine deletes nothing when it throws here.
+  const autoPruneCap = resolveAutoPruneCap();
+  if (
+    options.forceScopeShrink !== true &&
+    autoPruneCap > 0 &&
+    shrinkPlan.clean.length > autoPruneCap
+  ) {
+    throw new ScopeShrinkLargePruneError(
+      ctx.uid,
+      syncMode,
+      shrinkPlan.clean.length,
+      autoPruneCap,
+    );
+  }
+  const shrinkResult = applyScopeShrink({
+    journal,
+    plan: shrinkPlan,
+    hqRoot: companyRoot,
+    forceScopeShrink: options.forceScopeShrink === true,
+    reason: "scope_shrink",
+  });
+  // Surface each removed clean orphan as a `deleted` progress event so the
+  // menubar stream renders the prune the same way it renders a cross-machine
+  // tombstone (the Rust parser already handles `deleted: true`).
+  for (const orphan of shrinkPlan.clean) {
+    emit({
+      type: "progress",
+      path: orphan.path,
+      bytes: 0,
+      deleted: true,
+      message: "scope-narrowed (removed local copy outside sync scope)",
+    });
+  }
+
   // Stage 2: execute the plan. Per-item branching mirrors the pre-refactor
   // inline loop; the only structural change is that classification has
   // already happened (so `localHash` is reused instead of re-hashing).
@@ -419,6 +599,13 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
       // run", not a catch-all for everything we didn't download.
       continue;
     }
+    if (item.action === "skip-out-of-scope") {
+      // Outside the effective `syncMode` scope (US-005). Counted on its own
+      // axis so `filesSkipped` keeps meaning "unchanged on this run" — these
+      // are "deliberately not downloaded because of your sync scope".
+      filesOutOfScope++;
+      continue;
+    }
 
     if (item.action === "download") {
       downloadItems.push(item);
@@ -515,6 +702,12 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
           // 0 so the field shape stays stable for consumers that
           // destructure it.
           filesTombstoned: 0,
+          // Scope-shrink ran before execution, so its counts are real even on
+          // a conflict abort. `filesOutOfScope` reflects how far the serial
+          // pass got before the abort; that's acceptable for an abort result.
+          filesOutOfScope,
+          scopeOrphansRemoved: shrinkResult.cleanRemoved,
+          scopeOrphansBlocked: shrinkResult.dirtyTombstoned,
         };
         break;
       }
@@ -841,6 +1034,22 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
     });
   }
 
+  // Record this pull's boundary (US-005) so the NEXT pull can diff its scope
+  // against ours and detect a shrink. Append before the journal write so it
+  // persists. `prefixSet` is stored in the same company-relative namespace as
+  // the journal keys; `all` mode records `[""]` (covers everything).
+  appendPullRecord(journal, {
+    pullId: generatePullId(),
+    companyUid: ctx.uid,
+    startedAt,
+    completedAt: new Date().toISOString(),
+    syncMode,
+    prefixSet: currentPrefixSet,
+    scopeChangeDetected: shrinkPlan.scopeChangeDetected,
+    orphansRemoved: shrinkResult.cleanRemoved,
+    orphansBlocked: shrinkResult.dirtyTombstoned,
+  });
+
   // Stamp lastSync on every successful run so the menubar's "Last sync · X ago"
   // ticks even when nothing transferred. updateEntry only fires on actual
   // downloads; without this, a no-op sync leaves lastSync at the time of the
@@ -859,6 +1068,9 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
     newFilesCount: plan.newFilesCount,
     filesExcludedByPolicy: plan.filesExcludedByPolicy,
     filesTombstoned,
+    filesOutOfScope,
+    scopeOrphansRemoved: shrinkResult.cleanRemoved,
+    scopeOrphansBlocked: shrinkResult.dirtyTombstoned,
   };
 }
 
@@ -911,6 +1123,10 @@ type PullPlanItem =
   // refused to upload these since 5.33.0; the pull walker now refuses to
   // download them so legacy litter in cloud staging drains naturally.
   | { action: "skip-excluded-policy"; remoteFile: RemoteFile; localPath: string }
+  // Remote keys outside the effective `syncMode` scope (US-005). Present in
+  // the remote LIST (and accessible per STS) but deliberately not downloaded
+  // because the membership's sync scope doesn't cover them.
+  | { action: "skip-out-of-scope"; remoteFile: RemoteFile; localPath: string }
   | {
       action: "conflict";
       remoteFile: RemoteFile;
@@ -945,6 +1161,8 @@ interface PullPlan {
   newFilesCount: number;
   /** Count of remote keys refused by ephemeral-mirror policy. */
   filesExcludedByPolicy: number;
+  /** Count of remote keys skipped because they fall outside the sync scope. */
+  filesOutOfScope: number;
   /**
    * Journal-known keys missing from the remote LIST. The executor will
    * apply each as a local delete (file or symlink) + journal removal,
@@ -973,6 +1191,10 @@ function computePullPlan(
   personalMode: boolean,
   includeLocalCompanies: boolean,
   teamSyncedSlugs: ReadonlySet<string> | null,
+  // Coalesced, company-relative prefixes the pull is scoped to (US-005).
+  // `[""]` (the `all`-mode value) covers everything via `isCoveredByAny`, so
+  // the scope filter below becomes a no-op and legacy behavior is preserved.
+  prefixSet: string[],
 ): PullPlan {
   const items: PullPlanItem[] = [];
 
@@ -1017,6 +1239,17 @@ function computePullPlan(
       }
     }
 
+    // Scope filter (US-005). Keys outside the effective `syncMode` prefix set
+    // are not downloaded. `prefixSet` is `[""]` in `all` mode, which
+    // `isCoveredByAny` treats as covering everything — so this is a no-op for
+    // `all` and preserves the legacy full-bucket pull bit-for-bit. The
+    // previously-downloaded counterparts of these keys (if scope just shrank)
+    // are pruned separately by the scope-shrink pass in `sync()`.
+    if (!isCoveredByAny(remoteFile.key, prefixSet)) {
+      items.push({ action: "skip-out-of-scope", remoteFile, localPath });
+      continue;
+    }
+
     // LIST gives us no kind signal for the remote object — we don't
     // know whether this key is a regular file or a symlink record
     // until we either HEAD it (expensive — N extra calls per pull) or
@@ -1175,6 +1408,7 @@ function computePullPlan(
   let filesToSkip = 0;
   let filesToConflict = 0;
   let filesExcludedByPolicy = 0;
+  let filesOutOfScope = 0;
   const newFiles: Array<{ path: string; bytes: number }> = [];
   for (const item of items) {
     if (item.action === "download") {
@@ -1191,6 +1425,10 @@ function computePullPlan(
       // distinct class surfaced via filesExcludedByPolicy so consumers
       // can render a "N refused by policy" line independently of the
       // generic "N unchanged" tally.
+    } else if (item.action === "skip-out-of-scope") {
+      // Out-of-scope items get their own axis too, mirroring excluded-policy:
+      // they're "deliberately not downloaded (sync scope)", not "unchanged".
+      filesOutOfScope++;
     } else {
       filesToSkip++;
     }
@@ -1294,6 +1532,7 @@ function computePullPlan(
     newFiles,
     newFilesCount: newFiles.length,
     filesExcludedByPolicy,
+    filesOutOfScope,
     tombstones,
   };
 }

package/src/index.ts

@@ -46,6 +46,7 @@ export {
 export {
   coalescePrefixes,
   isCoveredByAny,
+  grantPathToPrefix,
 } from "./prefix-coalesce.js";
 
 // Scope-shrink detection + application (US-005)

package/src/prefix-coalesce.test.ts

@@ -1,5 +1,9 @@
 import { describe, it, expect } from "vitest";
-import { coalescePrefixes, isCoveredByAny } from "./prefix-coalesce.js";
+import {
+  coalescePrefixes,
+  isCoveredByAny,
+  grantPathToPrefix,
+} from "./prefix-coalesce.js";
 
 describe("coalescePrefixes", () => {
   it("returns empty for empty input", () => {
@@ -93,3 +97,74 @@ describe("isCoveredByAny", () => {
     expect(isCoveredByAny("A/b/c.md", ["a/"])).toBe(false);
   });
 });
+
+describe("grantPathToPrefix", () => {
+  const slug = "indigo";
+
+  it("strips a companies/<slug>/ anchor", () => {
+    expect(grantPathToPrefix("companies/indigo/knowledge/README.md", slug)).toBe(
+      "knowledge/README.md",
+    );
+  });
+
+  it("strips a bare <slug>/ anchor", () => {
+    expect(grantPathToPrefix("indigo/data/vyg/old-meetings/*", slug)).toBe(
+      "data/vyg/old-meetings/",
+    );
+  });
+
+  it("folds a trailing /* glob into a directory prefix", () => {
+    expect(grantPathToPrefix("data/vyg/*", slug)).toBe("data/vyg/");
+    expect(grantPathToPrefix("companies/indigo/design-pack/*", slug)).toBe(
+      "design-pack/",
+    );
+  });
+
+  it("folds a trailing bare * into its parent prefix", () => {
+    expect(grantPathToPrefix("reports*", slug)).toBe("reports");
+  });
+
+  it("leaves a company-relative directory prefix unchanged", () => {
+    expect(grantPathToPrefix("knowledge/security/", slug)).toBe(
+      "knowledge/security/",
+    );
+  });
+
+  it("leaves a company-relative exact key unchanged", () => {
+    expect(grantPathToPrefix("company.yaml", slug)).toBe("company.yaml");
+  });
+
+  it("maps a bare '*' (and empty) to '' = everything", () => {
+    expect(grantPathToPrefix("*", slug)).toBe("");
+    expect(grantPathToPrefix("", slug)).toBe("");
+  });
+
+  it("tolerates leading slashes", () => {
+    expect(grantPathToPrefix("/companies/indigo/x/*", slug)).toBe("x/");
+  });
+
+  it("does not strip a different company's anchor (defensive)", () => {
+    // A grant anchored at another slug is left intact (won't match this
+    // company's keys, which is the safe outcome).
+    expect(grantPathToPrefix("companies/other/x/*", slug)).toBe(
+      "companies/other/x/",
+    );
+  });
+
+  it("round-trips through coalescePrefixes + isCoveredByAny against real keys", () => {
+    const grants = [
+      "companies/indigo/design-pack/*",
+      "companies/indigo/knowledge/README.md",
+      "data/vyg/*",
+      "company.yaml",
+    ];
+    const prefixes = coalescePrefixes(grants.map((g) => grantPathToPrefix(g, slug)));
+    expect(isCoveredByAny("design-pack/logo.svg", prefixes)).toBe(true);
+    expect(isCoveredByAny("knowledge/README.md", prefixes)).toBe(true);
+    expect(isCoveredByAny("data/vyg/2026/q1.md", prefixes)).toBe(true);
+    expect(isCoveredByAny("company.yaml", prefixes)).toBe(true);
+    // Out of scope:
+    expect(isCoveredByAny("secrets/db.json", prefixes)).toBe(false);
+    expect(isCoveredByAny("knowledge/OTHER.md", prefixes)).toBe(false);
+  });
+});

package/src/prefix-coalesce.ts

@@ -70,3 +70,48 @@ export function isCoveredByAny(
   }
   return false;
 }
+
+/**
+ * Normalize a raw ACL grant `path` into a COMPANY-RELATIVE prefix suitable
+ * for `coalescePrefixes` + `isCoveredByAny` (which do literal `startsWith`
+ * matching against company-relative `RemoteFile.key`s).
+ *
+ * Real-world grant paths are inconsistent — observed forms in production:
+ *   - `*`                                  → everything (company-wide glob)
+ *   - `companies/<slug>/design-pack/*`     → full-anchored + trailing glob
+ *   - `companies/<slug>/knowledge/README.md` → full-anchored exact file
+ *   - `<slug>/data/vyg/old-meetings/*`     → slug-anchored + trailing glob
+ *   - `data/vyg/*`                         → company-relative + trailing glob
+ *   - `company.yaml`                       → company-relative exact file
+ *
+ * The engine's keys are ALWAYS company-relative (`design-pack/x`,
+ * `company.yaml`). So we:
+ *   1. strip a leading `companies/<slug>/` or `<slug>/` anchor, and
+ *   2. fold the ACL glob suffix into a `startsWith`-friendly prefix:
+ *        - `*`        (bare)      → `""`  (covers everything)
+ *        - `foo/bar/*` or `foo/bar*` → `foo/bar/` / `foo/bar`
+ *        - `foo/bar/`  (dir)      → unchanged
+ *        - `foo/bar.md` (exact)   → unchanged (an exact key is its own prefix)
+ *
+ * Without this, `coalescePrefixes(grants.map(g => g.path))` produced prefixes
+ * with trailing `*` (which never `startsWith`-match a real key) and
+ * full/slug-anchored prefixes (which never match company-relative keys) — so
+ * `syncMode: shared` would download nothing and prune everything the caller
+ * actually has access to. See the live grant dump in the hq-pro vault.
+ */
+export function grantPathToPrefix(grantPath: string, slug: string): string {
+  let p = (grantPath ?? "").replace(/^\/+/, "");
+  // 1. Strip the company anchor, if present.
+  const companyAnchor = `companies/${slug}/`;
+  const slugAnchor = `${slug}/`;
+  if (p.startsWith(companyAnchor)) {
+    p = p.slice(companyAnchor.length);
+  } else if (p.startsWith(slugAnchor)) {
+    p = p.slice(slugAnchor.length);
+  }
+  // 2. Fold the ACL glob suffix into a startsWith prefix.
+  if (p === "*" || p === "") return ""; // company-wide / empty → everything
+  if (p.endsWith("/*")) return p.slice(0, -1); // "a/b/*" → "a/b/"
+  if (p.endsWith("*")) return p.slice(0, -1); // "a/b*"  → "a/b"
+  return p; // dir prefix ("a/b/") or exact key ("a/b.md") — already a prefix
+}

package/src/qmd-reindex.test.ts

@@ -0,0 +1,143 @@
+/**
+ * Unit tests for reindexAfterSync.
+ *
+ * The function shells out to the global `qmd` binary, so every test injects a
+ * fake `exec` that records the calls and returns canned results — no real qmd
+ * is invoked. We assert on the *sequence of qmd commands* the function would
+ * run, which is the contract that keeps a teammate's index fresh after sync.
+ */
+
+import { describe, it, expect } from "vitest";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { reindexAfterSync, type QmdExec } from "./qmd-reindex.js";
+
+/** Build a fake exec that returns status 0 for everything and logs calls. */
+function fakeExec(opts?: { listStdout?: string; failOn?: string }): {
+  exec: QmdExec;
+  calls: string[][];
+} {
+  const calls: string[][] = [];
+  const exec: QmdExec = (args) => {
+    calls.push(args);
+    if (opts?.failOn && args[0] === opts.failOn) return { status: 1, stdout: "" };
+    if (args[0] === "collection" && args[1] === "list") {
+      return { status: 0, stdout: opts?.listStdout ?? "" };
+    }
+    return { status: 0, stdout: "" };
+  };
+  return { exec, calls };
+}
+
+describe("reindexAfterSync", () => {
+  it("no-ops when the path is not an HQ root", () => {
+    const { exec, calls } = fakeExec();
+    const r = reindexAfterSync("/tmp/not-hq", {
+      exec,
+      existsSync: () => false, // core/core.yaml absent
+    });
+    expect(r.qmdAvailable).toBe(false);
+    expect(calls).toHaveLength(0);
+  });
+
+  it("no-ops when qmd is unavailable (collection list errors)", () => {
+    const { exec, calls } = fakeExec({ failOn: "collection" });
+    const r = reindexAfterSync("/hq", {
+      exec,
+      existsSync: () => true, // core.yaml present
+    });
+    expect(r.qmdAvailable).toBe(false);
+    expect(r.updated).toBe(false);
+    // Only the availability probe ran, then bailed.
+    expect(calls).toEqual([["collection", "list"]]);
+  });
+
+  it("registers a missing company collection then runs an incremental update", () => {
+    const { exec, calls } = fakeExec({ listStdout: "Collections (1):\n\nHQ (qmd://HQ/)\n" });
+    const r = reindexAfterSync("/hq", {
+      exec,
+      existsSync: () => true,
+      readCompanies: () => ["acme"],
+      hasIndexableMarkdown: () => true,
+    });
+    expect(r.qmdAvailable).toBe(true);
+    expect(r.collectionsAdded).toEqual(["acme"]);
+    expect(r.updated).toBe(true);
+    expect(r.embedded).toBe(false);
+
+    // Expected command sequence: probe, add, context, update.
+    expect(calls).toEqual([
+      ["collection", "list"],
+      ["collection", "add", path.join("/hq", "companies", "acme", "knowledge"), "--name", "acme", "--mask", "**/*.md"],
+      ["context", "add", "qmd://acme", "Knowledge base for acme."],
+      ["update"],
+    ]);
+  });
+
+  it("skips collections that already exist", () => {
+    const { exec, calls } = fakeExec({ listStdout: "acme (qmd://acme/)\n" });
+    const r = reindexAfterSync("/hq", {
+      exec,
+      existsSync: () => true,
+      readCompanies: () => ["acme"],
+      hasIndexableMarkdown: () => true,
+    });
+    expect(r.collectionsAdded).toEqual([]);
+    // No `collection add` — straight to update.
+    expect(calls).toEqual([["collection", "list"], ["update"]]);
+  });
+
+  it("skips company dirs with no indexable markdown", () => {
+    const { exec, calls } = fakeExec({ listStdout: "" });
+    const r = reindexAfterSync("/hq", {
+      exec,
+      existsSync: () => true,
+      readCompanies: () => ["empty"],
+      hasIndexableMarkdown: () => false,
+    });
+    expect(r.collectionsAdded).toEqual([]);
+    expect(calls).toEqual([["collection", "list"], ["update"]]);
+  });
+
+  it("runs embed only when embed:true", () => {
+    const { exec, calls } = fakeExec({ listStdout: "" });
+    const r = reindexAfterSync("/hq", {
+      exec,
+      existsSync: () => true,
+      readCompanies: () => [],
+      embed: true,
+    });
+    expect(r.embedded).toBe(true);
+    expect(calls).toEqual([["collection", "list"], ["update"], ["embed"]]);
+  });
+
+  it("never throws even if exec misbehaves", () => {
+    const exec: QmdExec = () => {
+      throw new Error("boom");
+    };
+    expect(() =>
+      reindexAfterSync("/hq", { exec, existsSync: () => true }),
+    ).not.toThrow();
+  });
+
+  it("hasIndexableMarkdown finds a real .md and ignores INDEX.md", () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-qmd-test-"));
+    try {
+      const hq = path.join(dir, "hq");
+      const kdir = path.join(hq, "companies", "acme", "knowledge");
+      fs.mkdirSync(kdir, { recursive: true });
+      fs.mkdirSync(path.join(hq, "core"), { recursive: true });
+      fs.writeFileSync(path.join(hq, "core", "core.yaml"), "hqVersion: 1\n");
+      fs.writeFileSync(path.join(kdir, "INDEX.md"), "# index\n");
+      fs.writeFileSync(path.join(kdir, "note.md"), "# real\n");
+
+      const { exec, calls } = fakeExec({ listStdout: "" });
+      const r = reindexAfterSync(hq, { exec }); // real fs walk for md detection
+      expect(r.collectionsAdded).toEqual(["acme"]);
+      expect(calls.some((c) => c[0] === "collection" && c[1] === "add")).toBe(true);
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});