@indigoai-us/hq-cloud 5.2.1 → 5.4.0

package/src/bin/sync-runner.ts

@@ -4,10 +4,10 @@
  * (ADR-0001).
  *
  * The AppBar Sync menubar (Tauri + Rust) spawns this binary as a subprocess
- * and reads ndjson events from stdout. The protocol is intentionally narrow
- * and versioned-by-shape, not by tooling — no chalk, no colors, no human
- * prose. If you want to invoke sync as a human, use `hq sync` in
- * `@indigoai-us/hq-cli`.
+ * and reads ndjson events from BOTH stdout and stderr (see "Channels"
+ * below). The protocol is intentionally narrow and versioned-by-shape, not
+ * by tooling — no chalk, no colors, no human prose. If you want to invoke
+ * sync as a human, use `hq sync` in `@indigoai-us/hq-cli`.
  *
  * Flags:
  *   --companies               Fan out across every membership the caller has
@@ -18,14 +18,23 @@
  *                             only output mode. Accepted for symmetry with the
  *                             AppBar's argv in case someone passes it.
  *
- * Event protocol (one JSON object per line on stdout):
- *   setup-needed   — caller signed in but has no person entity yet
- *   auth-error     — no valid token available (interactive login disabled)
- *   fanout-plan    — list of companies we're about to sync
- *   progress       — per-file download
- *   error          — per-file or per-company error
- *   complete       — per-company summary
- *   all-complete   — aggregate summary after fanout
+ * Channels (one JSON object per line):
+ *   stdout — protocol stream:
+ *     setup-needed   caller signed in but has no person entity yet
+ *     fanout-plan    list of companies we're about to sync
+ *     progress       per-file download
+ *     complete       per-company summary
+ *     all-complete   aggregate summary after fanout
+ *   stderr — diagnostic stream:
+ *     error          per-file or per-company error
+ *     auth-error     no valid token available (interactive login disabled)
+ *
+ * Why the split: error-class events go to stderr so the menubar's Sentry
+ * breadcrumb pipeline picks them up automatically (see hq-sync
+ * src-tauri/src/commands/sync.rs `ProcessEvent::Stderr` handler). The
+ * single Sentry capture at runner-exit then ships one #hq-alerts issue
+ * with the full per-file → company → exit error trail attached, instead
+ * of requiring per-event capture calls in the menubar.
  *
  * Exit code:
  *   0 — event stream describes the outcome (including setup-needed)
@@ -100,10 +109,14 @@ const DEFAULT_HQ_ROOT = path.join(os.homedir(), "hq");
 // ---------------------------------------------------------------------------
 
 /**
- * Every event emitted on stdout. The `company` field is present on every
- * event except `setup-needed` / `auth-error` / `fanout-plan` / `all-complete`
- * (which describe the whole run) — consumers should treat its absence as
- * "meta-event, not tied to a specific company".
+ * Every event the runner emits. Channel routing (stdout vs stderr) is
+ * decided inside `runRunner`'s `emit` helper based on the event's `type`
+ * — see the doc-block on the file header for the split.
+ *
+ * The `company` field is present on every event except `setup-needed` /
+ * `auth-error` / `fanout-plan` / `all-complete` (which describe the whole
+ * run) — consumers should treat its absence as "meta-event, not tied to a
+ * specific company".
  */
 export type RunnerEvent =
   | { type: "setup-needed" }
@@ -114,6 +127,7 @@ export type RunnerEvent =
     }
   | ({ type: "progress"; company: string } & Omit<Extract<SyncProgressEvent, { type: "progress" }>, "type">)
   | ({ type: "error"; company?: string } & Omit<Extract<SyncProgressEvent, { type: "error" }>, "type">)
+  | ({ type: "conflict"; company: string } & Omit<Extract<SyncProgressEvent, { type: "conflict" }>, "type">)
   | ({
       type: "complete";
       company: string;
@@ -135,6 +149,13 @@ export type RunnerEvent =
       /** Always emitted; 0 when no push phase ran. */
       filesUploaded: number;
       bytesUploaded: number;
+      /**
+       * Conflict file paths aggregated across every company in the run.
+       * Always emitted; empty array when no conflicts were detected. Lets
+       * the menubar UI render a flat list without re-walking per-company
+       * `complete` events.
+       */
+      conflictPaths: Array<{ company: string; path: string; direction: "pull" | "push" }>;
       errors: Array<{ company: string; message: string }>;
     };
 
@@ -347,8 +368,35 @@ export async function runRunner(
   const stdout = deps.stdout ?? process.stdout;
   const stderr = deps.stderr ?? process.stderr;
 
+  // ---- emit ---------------------------------------------------------------
+  // Error-class events go to stderr; everything else to stdout.
+  //
+  // Why split: the AppBar Sync menubar (Tauri + Rust) feeds runner stderr
+  // into Sentry as breadcrumbs and captures one Sentry event when the
+  // runner exits non-zero. Routing `error` / `auth-error` events through
+  // stderr makes them part of that breadcrumb trail automatically — the
+  // menubar doesn't need a per-event capture call, and operators get the
+  // full context (per-file errors → company error → exit) in a single
+  // Sentry issue alerted to #hq-alerts.
+  //
+  // Non-error events (progress, complete, fanout-plan, all-complete,
+  // setup-needed) stay on stdout. They're the protocol stream the menubar
+  // parses for UI updates; mixing them with error events on the same
+  // channel was the original design (single ndjson stream, simpler to
+  // tee), but error context belongs in the diagnostic channel.
+  //
+  // Backward compat: older menubar releases (pre-PR-#34) parse only
+  // stdout for ndjson; with this change they will NOT receive error
+  // events. The menubar's `HQ_CLOUD_VERSION` pin gates which runner
+  // they spawn, so old menubars stay on the previous runner version
+  // even after this one is published.
+  const ERROR_TYPES: ReadonlySet<RunnerEvent["type"]> = new Set([
+    "error",
+    "auth-error",
+  ]);
   const emit = (event: RunnerEvent): void => {
-    stdout.write(`${JSON.stringify(event)}\n`);
+    const stream = ERROR_TYPES.has(event.type) ? stderr : stdout;
+    stream.write(`${JSON.stringify(event)}\n`);
   };
 
   // ---- argv -------------------------------------------------------------
@@ -479,6 +527,7 @@ export async function runRunner(
   let totalUploaded = 0;
   let totalUploadedBytes = 0;
   const errors: Array<{ company: string; message: string }> = [];
+  const allConflicts: Array<{ company: string; path: string; direction: "pull" | "push" }> = [];
 
   for (const target of plan) {
     const companyLabel = target.slug;
@@ -493,6 +542,14 @@ export async function runRunner(
           bytes: event.bytes,
           ...(event.message ? { message: event.message } : {}),
         });
+      } else if (event.type === "conflict") {
+        emit({
+          type: "conflict",
+          company: companyLabel,
+          path: event.path,
+          direction: event.direction,
+          resolution: event.resolution,
+        });
       } else {
         emit({
           type: "error",
@@ -508,6 +565,7 @@ export async function runRunner(
         filesUploaded: 0,
         bytesUploaded: 0,
         filesSkipped: 0,
+        conflictPaths: [],
         aborted: false,
       };
       let pullResult: SyncResult = {
@@ -515,6 +573,7 @@ export async function runRunner(
         bytesDownloaded: 0,
         filesSkipped: 0,
         conflicts: 0,
+        conflictPaths: [],
         aborted: false,
       };
 
@@ -549,6 +608,13 @@ export async function runRunner(
         });
       }
 
+      // Concat push + pull conflict paths into a single per-company list.
+      // Both arrays are always present (defaulted to []) so consumers can
+      // treat `conflictPaths` as authoritative without a falsy check.
+      const mergedConflictPaths = [
+        ...pullResult.conflictPaths,
+        ...pushResult.conflictPaths,
+      ];
       emit({
         type: "complete",
         company: companyLabel,
@@ -558,10 +624,17 @@ export async function runRunner(
         bytesUploaded: pushResult.bytesUploaded,
         filesSkipped: pullResult.filesSkipped + pushResult.filesSkipped,
         conflicts: pullResult.conflicts,
+        conflictPaths: mergedConflictPaths,
         // Either phase aborting marks the company aborted — the UI treats
         // `aborted: true` as "sync didn't complete cleanly for this company".
         aborted: pullResult.aborted || pushResult.aborted,
       });
+      for (const p of pullResult.conflictPaths) {
+        allConflicts.push({ company: companyLabel, path: p, direction: "pull" });
+      }
+      for (const p of pushResult.conflictPaths) {
+        allConflicts.push({ company: companyLabel, path: p, direction: "push" });
+      }
       totalDownloaded += pullResult.filesDownloaded;
       totalDownloadedBytes += pullResult.bytesDownloaded;
       totalUploaded += pushResult.filesUploaded;
@@ -586,6 +659,7 @@ export async function runRunner(
     bytesDownloaded: totalDownloadedBytes,
     filesUploaded: totalUploaded,
     bytesUploaded: totalUploadedBytes,
+    conflictPaths: allConflicts,
     errors,
   });
   return 0;

package/src/cli/share.test.ts

@@ -276,6 +276,62 @@ describe("share", () => {
     expect(uploadFile).toHaveBeenCalledWith(expect.anything(), testFile, "changed.md");
   });
 
+  it("populates conflictPaths and emits a conflict event when remote drifted from journal", async () => {
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    fs.mkdirSync(companyRoot, { recursive: true });
+    const testFile = path.join(companyRoot, "drifted.md");
+    fs.writeFileSync(testFile, "local edit");
+
+    // Journal has a stale hash → local diverged. headRemoteFile returning
+    // non-null tells share() the remote also exists; combined with the
+    // hash mismatch this trips the conflict branch.
+    vi.mocked(headRemoteFile).mockResolvedValueOnce({
+      lastModified: new Date(),
+      etag: '"remote-changed"',
+      size: 99,
+    });
+
+    const journalPath = path.join(stateDir, "sync-journal.acme.json");
+    fs.writeFileSync(
+      journalPath,
+      JSON.stringify({
+        version: "1",
+        lastSync: new Date().toISOString(),
+        files: {
+          "drifted.md": {
+            hash: "stale-hash",
+            size: 10,
+            syncedAt: new Date().toISOString(),
+            direction: "up",
+          },
+        },
+      }),
+    );
+
+    const events: unknown[] = [];
+    const result = await share({
+      paths: [testFile],
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      onConflict: "keep",
+      onEvent: (e) => events.push(e),
+    });
+
+    expect(result.conflictPaths).toEqual(["drifted.md"]);
+    const conflicts = events.filter(
+      (e): e is { type: "conflict"; path: string; direction: "push"; resolution: string } =>
+        typeof e === "object" && e !== null && (e as { type?: string }).type === "conflict",
+    );
+    expect(conflicts).toHaveLength(1);
+    expect(conflicts[0]).toMatchObject({
+      type: "conflict",
+      path: "drifted.md",
+      direction: "push",
+      resolution: "keep",
+    });
+  });
+
   it("skipUnchanged=false (default) uploads even when hash matches", async () => {
     const companyRoot = path.join(tmpDir, "companies", "acme");
     fs.mkdirSync(companyRoot, { recursive: true });

package/src/cli/share.ts

@@ -52,6 +52,12 @@ export interface ShareResult {
   filesUploaded: number;
   bytesUploaded: number;
   filesSkipped: number;
+  /**
+   * Paths (company-relative) that were detected as push conflicts. Mirrors
+   * `SyncResult.conflictPaths` so push and pull surface conflicts the same
+   * way to runner/UI consumers.
+   */
+  conflictPaths: string[];
   aborted: boolean;
 }
 
@@ -83,6 +89,7 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
   let filesUploaded = 0;
   let bytesUploaded = 0;
   let filesSkipped = 0;
+  const conflictPaths: string[] = [];
 
   // Collect all files to share
   const filesToShare = collectFiles(paths, hqRoot, syncRoot, shouldSync);
@@ -123,6 +130,8 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
 
       // If remote has changed since our last sync, it's a conflict
       if (journalEntry && journalEntry.hash !== localHash) {
+        conflictPaths.push(relativePath);
+
         // Local has changes — check if remote also changed
         const resolution = await resolveConflict(
           {
@@ -134,8 +143,21 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
           onConflict,
         );
 
+        emit({
+          type: "conflict",
+          path: relativePath,
+          direction: "push",
+          resolution,
+        });
+
         if (resolution === "abort") {
-          return { filesUploaded, bytesUploaded, filesSkipped, aborted: true };
+          return {
+            filesUploaded,
+            bytesUploaded,
+            filesSkipped,
+            conflictPaths,
+            aborted: true,
+          };
         }
         if (resolution === "keep" || resolution === "skip") {
           filesSkipped++;
@@ -179,7 +201,13 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
 
   writeJournal(ctx.slug, journal);
 
-  return { filesUploaded, bytesUploaded, filesSkipped, aborted: false };
+  return {
+    filesUploaded,
+    bytesUploaded,
+    filesSkipped,
+    conflictPaths,
+    aborted: false,
+  };
 }
 
 /**
@@ -193,6 +221,10 @@ function defaultConsoleLogger(event: SyncProgressEvent): void {
     } else {
       console.log(`  ✓ ${event.path}`);
     }
+  } else if (event.type === "conflict") {
+    console.error(
+      `  ⚠ conflict (${event.direction}): ${event.path} — ${event.resolution}`,
+    );
   } else {
     console.error(`  ✗ ${event.path} — ${event.message}`);
   }

package/src/cli/sync.test.ts

@@ -176,10 +176,54 @@ describe("sync", () => {
     });
 
     expect(result.conflicts).toBe(1);
+    expect(result.conflictPaths).toEqual(["docs/handoff.md"]);
     expect(result.filesSkipped).toBeGreaterThanOrEqual(1);
     expect(fs.readFileSync(path.join(companyDocs, "handoff.md"), "utf-8")).toBe("local version");
   });
 
+  it("emits a conflict event with path + resolution on hash mismatch", async () => {
+    const companyDocs = path.join(tmpDir, "companies", "acme", "docs");
+    fs.mkdirSync(companyDocs, { recursive: true });
+    fs.writeFileSync(path.join(companyDocs, "handoff.md"), "local version");
+
+    fs.writeFileSync(
+      journalPath,
+      JSON.stringify({
+        version: "1",
+        lastSync: new Date().toISOString(),
+        files: {
+          "docs/handoff.md": {
+            hash: "stale-hash",
+            size: 20,
+            syncedAt: new Date(Date.now() - 3600000).toISOString(),
+            direction: "down",
+          },
+        },
+      }),
+    );
+
+    const events: unknown[] = [];
+    await sync({
+      company: "acme",
+      onConflict: "keep",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      onEvent: (e) => events.push(e),
+    });
+
+    const conflicts = events.filter(
+      (e): e is { type: "conflict"; path: string; direction: "pull"; resolution: string } =>
+        typeof e === "object" && e !== null && (e as { type?: string }).type === "conflict",
+    );
+    expect(conflicts).toHaveLength(1);
+    expect(conflicts[0]).toMatchObject({
+      type: "conflict",
+      path: "docs/handoff.md",
+      direction: "pull",
+      resolution: "keep",
+    });
+  });
+
   it("aborts on --on-conflict abort", async () => {
     const companyDocs = path.join(tmpDir, "companies", "acme", "docs");
     fs.mkdirSync(companyDocs, { recursive: true });

package/src/cli/sync.ts

@@ -13,7 +13,7 @@ import { downloadFile, listRemoteFiles } from "../s3.js";
 import { readJournal, writeJournal, hashFile, updateEntry, getEntry } from "../journal.js";
 import { createIgnoreFilter } from "../ignore.js";
 import { resolveConflict } from "./conflict.js";
-import type { ConflictStrategy } from "./conflict.js";
+import type { ConflictStrategy, ConflictResolution } from "./conflict.js";
 
 /**
  * Per-file events emitted by `sync()` as it progresses.
@@ -28,7 +28,13 @@ import type { ConflictStrategy } from "./conflict.js";
  */
 export type SyncProgressEvent =
   | { type: "progress"; path: string; bytes: number; message?: string }
-  | { type: "error"; path: string; message: string };
+  | { type: "error"; path: string; message: string }
+  | {
+      type: "conflict";
+      path: string;
+      direction: "pull" | "push";
+      resolution: ConflictResolution;
+    };
 
 export interface SyncOptions {
   /** Company slug or UID (defaults to active company from config) */
@@ -66,6 +72,12 @@ export interface SyncResult {
   bytesDownloaded: number;
   filesSkipped: number;
   conflicts: number;
+  /**
+   * Paths (remote keys) that were detected as conflicts during this run.
+   * Always populated when `conflicts > 0` so callers can surface them in UI
+   * or logs without re-streaming the per-file events.
+   */
+  conflictPaths: string[];
   aborted: boolean;
 }
 
@@ -106,6 +118,7 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
   let bytesDownloaded = 0;
   let filesSkipped = 0;
   let conflicts = 0;
+  const conflictPaths: string[] = [];
 
   // List all remote files (IAM session policy filters at the AWS layer)
   const remoteFiles = await listRemoteFiles(ctx);
@@ -138,6 +151,7 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
       // If local file has changed since last sync, it's a conflict
       if (journalEntry && journalEntry.hash !== localHash) {
         conflicts++;
+        conflictPaths.push(remoteFile.key);
 
         const resolution = await resolveConflict(
           {
@@ -150,9 +164,23 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
           onConflict,
         );
 
+        emit({
+          type: "conflict",
+          path: remoteFile.key,
+          direction: "pull",
+          resolution,
+        });
+
         if (resolution === "abort") {
           writeJournal(journalSlug, journal);
-          return { filesDownloaded, bytesDownloaded, filesSkipped, conflicts, aborted: true };
+          return {
+            filesDownloaded,
+            bytesDownloaded,
+            filesSkipped,
+            conflicts,
+            conflictPaths,
+            aborted: true,
+          };
         }
         if (resolution === "keep" || resolution === "skip") {
           filesSkipped++;
@@ -208,7 +236,14 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
 
   writeJournal(journalSlug, journal);
 
-  return { filesDownloaded, bytesDownloaded, filesSkipped, conflicts, aborted: false };
+  return {
+    filesDownloaded,
+    bytesDownloaded,
+    filesSkipped,
+    conflicts,
+    conflictPaths,
+    aborted: false,
+  };
 }
 
 /**
@@ -251,5 +286,9 @@ function defaultConsoleLogger(event: SyncProgressEvent): void {
     }
   } else if (event.type === "error") {
     console.error(`  ✗ ${event.path} — ${event.message}`);
+  } else if (event.type === "conflict") {
+    console.error(
+      `  ⚠ conflict (${event.direction}): ${event.path} — ${event.resolution}`,
+    );
   }
 }

package/src/ignore.test.ts

@@ -0,0 +1,71 @@
+/**
+ * Unit tests for createIgnoreFilter.
+ *
+ * Covers both modes: legacy permissive (no .hqinclude) and allowlist mode
+ * (.hqinclude present). The allowlist tests guard against accidentally
+ * leaking sensitive subtrees like data/ or workers/ to S3 — a regression
+ * here would silently push private content on the next sync.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { createIgnoreFilter } from "./ignore.js";
+
+describe("createIgnoreFilter", () => {
+  let hqRoot: string;
+
+  beforeEach(() => {
+    hqRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-ignore-test-"));
+  });
+
+  afterEach(() => {
+    fs.rmSync(hqRoot, { recursive: true, force: true });
+  });
+
+  it("permissive mode: regular files sync, defaults are ignored", () => {
+    const shouldSync = createIgnoreFilter(hqRoot);
+    expect(shouldSync(path.join(hqRoot, "companies/indigo/notes.md"))).toBe(true);
+    expect(shouldSync(path.join(hqRoot, "node_modules/foo/x.js"))).toBe(false);
+    expect(shouldSync(path.join(hqRoot, ".env"))).toBe(false);
+  });
+
+  it("permissive mode: .hqignore patterns are honored", () => {
+    fs.writeFileSync(path.join(hqRoot, ".hqignore"), "companies/*/data/\n");
+    const shouldSync = createIgnoreFilter(hqRoot);
+    expect(shouldSync(path.join(hqRoot, "companies/indigo/data/x.csv"))).toBe(false);
+    expect(shouldSync(path.join(hqRoot, "companies/indigo/notes.md"))).toBe(true);
+  });
+
+  it("allowlist mode: presence of .hqinclude switches to opt-in", () => {
+    fs.writeFileSync(
+      path.join(hqRoot, ".hqinclude"),
+      "companies/*/knowledge/\ncompanies/*/projects/\n",
+    );
+    const shouldSync = createIgnoreFilter(hqRoot);
+    // Allowlisted paths sync.
+    expect(shouldSync(path.join(hqRoot, "companies/indigo/knowledge/foo.md"))).toBe(true);
+    expect(shouldSync(path.join(hqRoot, "companies/indigo/projects/p1/prd.json"))).toBe(true);
+    // Anything else stays local — this is the privacy guarantee.
+    expect(shouldSync(path.join(hqRoot, "companies/indigo/data/leads.csv"))).toBe(false);
+    expect(shouldSync(path.join(hqRoot, "companies/indigo/workers/cmo/skill.md"))).toBe(false);
+    expect(shouldSync(path.join(hqRoot, "companies/indigo/settings/aws.json"))).toBe(false);
+    expect(shouldSync(path.join(hqRoot, "personal/journal/2026-04-26.md"))).toBe(false);
+  });
+
+  it("allowlist mode: exclusion layers still subtract on top", () => {
+    // Even when a subtree is allowlisted, default ignores like node_modules/
+    // and .env must still apply. Otherwise an allowlisted subdir would sync
+    // gigabytes of dependency junk or leak secret env files.
+    fs.writeFileSync(path.join(hqRoot, ".hqinclude"), "companies/*/projects/\n");
+    const shouldSync = createIgnoreFilter(hqRoot);
+    expect(
+      shouldSync(path.join(hqRoot, "companies/indigo/projects/p1/prd.json")),
+    ).toBe(true);
+    expect(
+      shouldSync(path.join(hqRoot, "companies/indigo/projects/p1/node_modules/react/index.js")),
+    ).toBe(false);
+    expect(shouldSync(path.join(hqRoot, "companies/indigo/projects/p1/.env"))).toBe(false);
+  });
+});

package/src/ignore.ts

@@ -1,17 +1,23 @@
 /**
  * Ignore-file parser for cloud sync.
  *
- * Three layers, evaluated in order (later patterns override earlier ones):
- *   1. Built-in defaults — things that should *never* sync (VCS, node_modules,
- *      build artifacts, caches, env files). Cover the common stacks so that a
- *      first-time sync over a random project folder doesn't try to push
- *      `target/`, `node_modules/`, or `.next/` to S3.
- *   2. Repo `.gitignore` at hqRoot — reuses the user's existing exclusions so
- *      we don't re-list every build directory ourselves. Root-level only; we
- *      do not recurse like real git.
- *   3. `.hqignore` (preferred) or `.hqsyncignore` (legacy name) at hqRoot —
- *      sync-specific overrides. Use `!pattern` to re-include something an
- *      earlier layer excluded.
+ * Two modes:
+ *   - **Permissive (default)**: everything syncs except what ignore layers
+ *     subtract. Three layers stack (later overrides earlier):
+ *       1. Built-in defaults — VCS, node_modules, build artifacts, caches,
+ *          env files. Covers the common stacks so a first-time sync over a
+ *          random project folder doesn't push `target/` or `.next/` to S3.
+ *       2. Repo `.gitignore` at hqRoot — reuses existing exclusions so we
+ *          don't re-list every build directory. Root-level only.
+ *       3. `.hqignore` (preferred) or `.hqsyncignore` (legacy) — sync-specific
+ *          overrides. Use `!pattern` to re-include something earlier layers
+ *          excluded.
+ *
+ *   - **Allowlist**: triggered when `.hqinclude` exists at hqRoot. Nothing
+ *     syncs unless its path matches at least one pattern in `.hqinclude`. The
+ *     three exclusion layers still subtract on top — so even allowlisted
+ *     subtrees won't push `node_modules/` or `.env`. Privacy-by-default for
+ *     HQ trees that contain mixed personal + shareable data.
  */
 
 import * as fs from "fs";
@@ -102,10 +108,21 @@ export function createIgnoreFilter(hqRoot: string): (filePath: string) => boolea
     readIgnoreFile(path.join(hqRoot, ".hqsyncignore"));
   if (hqignore) ig.add(hqignore);
 
+  // Allowlist mode: when `.hqinclude` exists, sync is opt-in. The matcher
+  // here treats include patterns as ignore patterns and inverts the verdict —
+  // a path is "allowed" iff its relative path matches at least one entry.
+  // Exclusion layers above still subtract, so build artifacts inside an
+  // allowlisted subtree (e.g. node_modules/ inside companies/x/repos/y/) are
+  // still skipped.
+  const hqinclude = readIgnoreFile(path.join(hqRoot, ".hqinclude"));
+  const includeMatcher = hqinclude ? ignore().add(hqinclude) : null;
+
   return (filePath: string): boolean => {
     const relative = path.relative(hqRoot, filePath);
     if (!relative || relative.startsWith("..")) return true; // outside HQ root
-    return !ig.ignores(relative);
+    if (ig.ignores(relative)) return false;
+    if (includeMatcher && !includeMatcher.ignores(relative)) return false;
+    return true;
   };
 }