@indigoai-us/hq-cloud 5.24.0 → 5.25.0

package/src/bin/sync-runner.test.ts

@@ -11,7 +11,7 @@ import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
-import { runRunner, resolveDeletePolicy } from "./sync-runner.js";
+import { runRunner, resolveDeletePolicy, resolveSkipPersonal } from "./sync-runner.js";
 import type {
   RunnerEvent,
   RunnerDeps,
@@ -80,6 +80,7 @@ function defaultShareResult(overrides: Partial<ShareResult> = {}): ShareResult {
     filesDeleted: 0,
     filesTombstoned: 0,
     filesRefusedStale: 0,
+    filesExcludedByPolicy: 0,
     conflictPaths: [],
     aborted: false,
     ...overrides,
@@ -687,7 +688,9 @@ describe("per-company fanout", () => {
     const complete = deps.stdout
       .events()
       .find((e) => e.type === "complete") as Extract<RunnerEvent, { type: "complete" }>;
-    // Pull-only run: upload counters are 0.
+    // Pull-only run: upload counters are 0. Push-side counters added in
+    // 5.25 (filesTombstoned/filesRefusedStale/filesExcludedByPolicy) are
+    // also 0 because no push leg ran.
     expect(complete).toEqual({
       type: "complete",
       company: "acme",
@@ -699,6 +702,9 @@ describe("per-company fanout", () => {
       aborted: result.aborted,
       filesUploaded: 0,
       bytesUploaded: 0,
+      filesTombstoned: 0,
+      filesRefusedStale: 0,
+      filesExcludedByPolicy: 0,
       newFiles: result.newFiles,
       newFilesCount: result.newFilesCount,
     });
@@ -1709,11 +1715,11 @@ beforeEach(() => {
 // ── resolveDeletePolicy: env-var contract ───────────────────────────────────
 //
 // `HQ_SYNC_DELETE_POLICY` is the documented rollback knob for the
-// currency-gated default landed in 5.24. The helper centralizes the
-// allowlist + default so every callsite (both the personal and company push
-// paths in the runner) gets identical semantics. Tests pin the four expected
-// behaviors so a future regression on the allowlist or default surfaces here
-// instead of in the field.
+// currency-gated default that became default in 5.25 (after a 5.24 soak).
+// The helper centralizes the allowlist + default so every callsite (both
+// the personal and company push paths in the runner) gets identical
+// semantics. Tests pin the four expected behaviors so a future regression
+// on the allowlist or default surfaces here instead of in the field.
 
 describe("resolveDeletePolicy", () => {
   let originalEnv: string | undefined;
@@ -1731,12 +1737,11 @@ describe("resolveDeletePolicy", () => {
     }
   });
 
-  it("defaults to 'owned-only' in 5.24 (staged-default rollout, flip in 5.25)", () => {
-    // 5.24 ships the currency-gated CODE PATH but holds the default flip
-    // for a soak window. When the default flips to 'currency-gated' in
-    // 5.25, this assertion changes — both edits live next to each other so
-    // the rollout sequence is obvious from the diff.
-    expect(resolveDeletePolicy()).toBe("owned-only");
+  it("defaults to 'currency-gated' in 5.25 (post-soak default flip)", () => {
+    // 5.24 shipped the code path with `owned-only` as default; 5.25 flips
+    // the default to `currency-gated` after the soak window. Rollback knob
+    // is `HQ_SYNC_DELETE_POLICY=owned-only` for anyone surprised.
+    expect(resolveDeletePolicy()).toBe("currency-gated");
   });
 
   it.each(["currency-gated", "owned-only", "all"] as const)(
@@ -1749,11 +1754,62 @@ describe("resolveDeletePolicy", () => {
 
   it("falls back to default on unknown env values (no silent corruption)", () => {
     process.env.HQ_SYNC_DELETE_POLICY = "yolo";
-    expect(resolveDeletePolicy()).toBe("owned-only");
+    expect(resolveDeletePolicy()).toBe("currency-gated");
   });
 
   it("treats empty string as unset → default", () => {
     process.env.HQ_SYNC_DELETE_POLICY = "";
-    expect(resolveDeletePolicy()).toBe("owned-only");
+    expect(resolveDeletePolicy()).toBe("currency-gated");
   });
 });
+
+// ── resolveSkipPersonal: flag-OR-env combination ───────────────────────────
+//
+// Two inputs combine: the `--skip-personal` CLI flag and the
+// `HQ_SYNC_SKIP_PERSONAL` env var. Either being truthy skips personal sync.
+// The flag is the explicit-for-this-invocation knob (menubar passes it when
+// the user toggled "Sync personal vault" off); the env is the persistent
+// child-process default. Both surfaces tested so a regression on either
+// short-circuit path surfaces here.
+
+describe("resolveSkipPersonal", () => {
+  let originalEnv: string | undefined;
+
+  beforeEach(() => {
+    originalEnv = process.env.HQ_SYNC_SKIP_PERSONAL;
+    delete process.env.HQ_SYNC_SKIP_PERSONAL;
+  });
+
+  afterEach(() => {
+    if (originalEnv === undefined) {
+      delete process.env.HQ_SYNC_SKIP_PERSONAL;
+    } else {
+      process.env.HQ_SYNC_SKIP_PERSONAL = originalEnv;
+    }
+  });
+
+  it("defaults to false (personal sync enabled, current behavior)", () => {
+    expect(resolveSkipPersonal(false)).toBe(false);
+  });
+
+  it("flag=true short-circuits to true regardless of env", () => {
+    process.env.HQ_SYNC_SKIP_PERSONAL = "no"; // explicit "no" in env
+    expect(resolveSkipPersonal(true)).toBe(true);
+  });
+
+  it.each(["1", "true", "yes", "TRUE", "Yes"])(
+    "env value '%s' (truthy) -> true",
+    (val) => {
+      process.env.HQ_SYNC_SKIP_PERSONAL = val;
+      expect(resolveSkipPersonal(false)).toBe(true);
+    },
+  );
+
+  it.each(["0", "false", "no", "", "unset-equiv"])(
+    "env value '%s' (falsy) -> false",
+    (val) => {
+      process.env.HQ_SYNC_SKIP_PERSONAL = val;
+      expect(resolveSkipPersonal(false)).toBe(false);
+    },
+  );
+});

package/src/bin/sync-runner.ts

@@ -14,6 +14,10 @@
  *   --company <slug-or-uid>   Sync a single company (alternative to --companies)
  *   --on-conflict <strategy>  abort | overwrite | keep (default: abort)
  *   --hq-root <path>          Local HQ directory (default: $HOME/hq)
+ *   --skip-personal           Drop the personal target from the --companies
+ *                             fanout. Combined with HQ_SYNC_SKIP_PERSONAL env
+ *                             (either truthy disables personal sync). No-op
+ *                             outside --companies mode.
  *   --json                    Ignored — ndjson on stdout is the default and
  *                             only output mode. Accepted for symmetry with the
  *                             AppBar's argv in case someone passes it.
@@ -122,21 +126,24 @@ const DEFAULT_HQ_ROOT = path.join(os.homedir(), "hq");
 
 /**
  * Delete-propagation policy honored by the push leg of bidirectional sync.
- * Default `"owned-only"` in 5.24 — the pre-5.24 behavior is preserved so
- * existing users see zero change in delete-propagation semantics. The
- * stricter-and-safer `"currency-gated"` policy ships in 5.24 as opt-in
- * (set `HQ_SYNC_DELETE_POLICY=currency-gated` to enable per-file ETag
- * verification before any local-delete propagates to S3). Default flip
- * to `"currency-gated"` is scheduled for 5.25 after a soak period during
- * which currency-gated behavior is observed on at least one active
- * machine.
+ *
+ * Default `"currency-gated"` in 5.25 — flipped from `"owned-only"` after
+ * one machine (Indigo / corey) ran the 5.24 code path through real syncs
+ * for a week without surfacing surprise behavior. Currency-gated does a
+ * per-file ETag HEAD before propagating any local-delete to S3: if the
+ * remote object's current ETag no longer matches the journal's last-
+ * recorded one, the delete is refused and the next pull leg re-pulls the
+ * file via the standard 3-way merge path. This is strictly safer than
+ * `owned-only` (which propagates any local-delete the journal can prove
+ * came from this device) — the only delete-class that changes behavior
+ * is "deleted locally + modified remotely by another device", which
+ * previously destroyed remote work and now becomes a pull-and-conflict.
  *
  * Env override `HQ_SYNC_DELETE_POLICY=owned-only|all|currency-gated` is
- * also the rollback knob — once 5.25 flips the default, anyone surprised
- * by the new behavior flips the env back to `owned-only` without
- * re-deploying. `all` is the unsafe-mirror mode previously used by the
- * runner pre-5.20 — included only as an emergency reconcile lever, not a
- * recommended default.
+ * also the rollback knob — anyone surprised by 5.25's flip can revert
+ * to `owned-only` without redeploying. `all` is the unsafe-mirror mode
+ * previously used by the runner pre-5.20 — included only as an
+ * emergency reconcile lever, not a recommended default.
  */
 export type DeletePropagationPolicy = "currency-gated" | "owned-only" | "all";
 
@@ -145,7 +152,33 @@ export function resolveDeletePolicy(): DeletePropagationPolicy {
   if (env === "owned-only" || env === "all" || env === "currency-gated") {
     return env;
   }
-  return "owned-only";
+  return "currency-gated";
+}
+
+/**
+ * Resolve whether to skip the personal target in a `--companies` fanout.
+ *
+ * Two inputs combine: the `--skip-personal` CLI flag (parsed into
+ * `ParsedArgs.skipPersonal`) and the `HQ_SYNC_SKIP_PERSONAL` env var. Either
+ * being truthy skips the personal target — flag wins on conflict (CLI
+ * flag is the explicit-for-this-invocation knob, env is the persistent
+ * default usually set by the menubar in the spawned child process).
+ *
+ * Env truthy values: `1`, `true`, `yes` (case-insensitive). Anything else
+ * (including missing) is treated as falsy — same shape as classic
+ * Unix opt-in env conventions; conservative to avoid surprising opt-outs.
+ *
+ * Use case: the menubar app exposes a "Sync personal vault" toggle in
+ * Settings (default ON, matching the auto-provisioning UX). When the user
+ * flips it off, the menubar spawns `hq sync` with this env set so the
+ * fanout drops the personal target before walking the user's entire HQ
+ * tree (a sync that would otherwise scan thousands of files, including
+ * the new personal-vault default exclusions, just to do nothing useful).
+ */
+export function resolveSkipPersonal(flag: boolean): boolean {
+  if (flag) return true;
+  const env = (process.env.HQ_SYNC_SKIP_PERSONAL ?? "").toLowerCase();
+  return env === "1" || env === "true" || env === "yes";
 }
 
 // Personal-vault scope (exclusion list + path computer) lives in
@@ -197,12 +230,19 @@ export type RunnerEvent =
       /**
        * Upload counters. Always emitted (0 when the run was pull-only) so
        * downstream consumers don't need to conditionally read the field.
-       * Tauri's `SyncCompleteEvent` ignores extra fields today; adding them
-       * to the Rust struct is a follow-up when the UI needs to surface push
-       * totals.
        */
       filesUploaded: number;
       bytesUploaded: number;
+      /**
+       * Push-side counters added in 5.25. Always emitted as numbers (0
+       * when no push leg ran). Tauri's `SyncCompleteEvent` carries them
+       * as Option<u32> for back-compat with <5.25 engines that don't
+       * include them; structural-typing-wise, the union just adds
+       * properties on top of `SyncResult`.
+       */
+      filesTombstoned: number;
+      filesRefusedStale: number;
+      filesExcludedByPolicy: number;
     } & SyncResult)
   | {
       type: "all-complete";
@@ -402,6 +442,13 @@ interface ParsedArgs {
   watch: boolean;
   /** Auto-sync (Beta): ms between remote-pull passes. Required when watch=true. */
   pollRemoteMs?: number;
+  /**
+   * Drop the personal target from the fanout. Combined with the
+   * `HQ_SYNC_SKIP_PERSONAL` env var by `resolveSkipPersonal()` — either
+   * truthy disables personal sync for this run. No-op outside `--companies`
+   * mode (single-company runs never visit the personal target).
+   */
+  skipPersonal: boolean;
 }
 
 function parseArgs(argv: string[]): ParsedArgs | { error: string } {
@@ -412,6 +459,7 @@ function parseArgs(argv: string[]): ParsedArgs | { error: string } {
   let direction: Direction = "pull";
   let watch = false;
   let pollRemoteMs: number | undefined;
+  let skipPersonal = false;
 
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
@@ -465,6 +513,12 @@ function parseArgs(argv: string[]): ParsedArgs | { error: string } {
       case "--json":
         // Accepted but ignored — ndjson is the only output mode.
         break;
+      case "--skip-personal":
+        // Drop the personal target from the fanout. No-op outside
+        // --companies mode. Combined with HQ_SYNC_SKIP_PERSONAL env via
+        // resolveSkipPersonal().
+        skipPersonal = true;
+        break;
       default:
         return { error: `Unknown argument: ${arg}` };
     }
@@ -480,7 +534,7 @@ function parseArgs(argv: string[]): ParsedArgs | { error: string } {
     return { error: "--poll-remote-ms requires --watch" };
   }
 
-  return { companies, company, onConflict, hqRoot, direction, watch, pollRemoteMs };
+  return { companies, company, onConflict, hqRoot, direction, watch, pollRemoteMs, skipPersonal };
 }
 
 // ---------------------------------------------------------------------------
@@ -698,7 +752,15 @@ export async function runRunner(
     plan.push({ uid: m.companyUid, slug, ...(name ? { name } : {}) });
   }
 
-  if (parsed.companies) {
+  if (parsed.companies && !resolveSkipPersonal(parsed.skipPersonal)) {
+    // Personal-target fanout slot. Skipped entirely when --skip-personal
+    // (or HQ_SYNC_SKIP_PERSONAL=1) is set — see resolveSkipPersonal doc for
+    // the rationale (menubar opt-out for users who only want company sync).
+    // When skipped, the fanout-plan event below carries only company
+    // memberships and no "personal" slug; downstream consumers (menubar
+    // workspaces row, status surfaces) should already tolerate that
+    // shape since pre-5.25 fanout often had it (a user with no person
+    // entity yet, or before the canonical-person-entity machinery landed).
     const persons = await client.entity.listByType("person");
     const pick = pickCanonicalPersonEntity(persons);
     if (pick?.bucketName) {
@@ -829,6 +891,7 @@ export async function runRunner(
         filesDeleted: 0,
         filesTombstoned: 0,
         filesRefusedStale: 0,
+        filesExcludedByPolicy: 0,
         conflictPaths: [],
         aborted: false,
       };
@@ -930,6 +993,17 @@ export async function runRunner(
         filesUploaded: pushResult.filesUploaded,
         bytesUploaded: pushResult.bytesUploaded,
         filesSkipped: pullResult.filesSkipped + pushResult.filesSkipped,
+        // Push-side counters surfaced on `complete` so the menubar's
+        // `SyncCompleteEvent` (which carries them as Option<u32> for
+        // back-compat with pre-5.25 engines) can render the new totals.
+        // Always emitted as numbers (0 when no push leg ran) so Rust's
+        // serde decodes them as `Some(0)` rather than `None` — distinct
+        // from the legacy-engine `None` and useful when the UI wants to
+        // distinguish "engine ran, nothing tombstoned" from "engine
+        // didn't report".
+        filesTombstoned: pushResult.filesTombstoned,
+        filesRefusedStale: pushResult.filesRefusedStale,
+        filesExcludedByPolicy: pushResult.filesExcludedByPolicy,
         // Sourced from the merged path list so push-side conflicts are
         // counted too — `ShareResult` doesn't expose a numeric counter,
         // and using `pullResult.conflicts` alone silently dropped any
@@ -967,6 +1041,13 @@ export async function runRunner(
         filesUploaded: state.filesUploaded,
         bytesUploaded: state.bytesUploaded,
         filesSkipped: 0,
+        // Mid-flight throw: we have no clean ShareResult to read these
+        // from. Report 0 so the event shape stays stable; the partial
+        // counts above already reflect what actually moved before the
+        // throw.
+        filesTombstoned: 0,
+        filesRefusedStale: 0,
+        filesExcludedByPolicy: 0,
         conflicts: 0,
         conflictPaths: [],
         aborted: true,

package/src/cli/share.test.ts

@@ -595,9 +595,14 @@ describe("share", () => {
       vaultConfig: mockConfig,
       hqRoot: tmpDir,
       onEvent: (e) => {
-        // Only file-level events carry `.path`. The Stage-1 `plan` event is
-        // surfaced separately and tested in its own block.
-        if (e.type === "plan" || e.type === "new-files") return;
+        // Only file-level events carry `.path`. The Stage-1 `plan` event +
+        // the new-files event + the personal-vault-out-of-policy summary
+        // event are surfaced separately and tested in their own blocks.
+        if (
+          e.type === "plan" ||
+          e.type === "new-files" ||
+          e.type === "personal-vault-out-of-policy"
+        ) return;
         events.push({
           type: e.type,
           path: e.path,

package/src/cli/share.ts

@@ -21,6 +21,10 @@ import {
   normalizeEtag,
 } from "../journal.js";
 import { createIgnoreFilter, isWithinSizeLimit } from "../ignore.js";
+import {
+  wrapFilterWithPersonalVaultDefaults,
+  type PersonalVaultExclusion,
+} from "../personal-vault-exclusions.js";
 import { resolveConflict } from "./conflict.js";
 import type { ConflictStrategy } from "./conflict.js";
 import type { SyncProgressEvent } from "./sync.js";
@@ -386,6 +390,15 @@ export interface ShareResult {
    * `currency-gated`.
    */
   filesRefusedStale: number;
+  /**
+   * Number of paths blocked by `PERSONAL_VAULT_DEFAULT_EXCLUSIONS` during this
+   * run (push leg, personalMode=true). Includes both files that would have
+   * uploaded and journal entries that would have been included in the delete
+   * plan; deduplicated across walks. Always 0 outside personalMode. Mirrors
+   * the `count` field of the `personal-vault-out-of-policy` event (which is
+   * emitted exactly once if this is > 0).
+   */
+  filesExcludedByPolicy: number;
   /**
    * Paths (company-relative) that were detected as push conflicts. Mirrors
    * `SyncResult.conflictPaths` so push and pull surface conflicts the same
@@ -463,7 +476,34 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
   const syncRoot = options.personalMode === true
     ? hqRoot
     : path.join(hqRoot, "companies", ctx.slug);
-  const shouldSync = createIgnoreFilter(hqRoot);
+
+  // Personal-vault default exclusions (introduced in 5.25): wrap the base
+  // ignore filter so paths matching `PERSONAL_VAULT_DEFAULT_EXCLUSIONS` are
+  // rejected before they upload OR enter the delete plan. Refuses & warns —
+  // an already-leaked remote object stays put as an orphan; a separate one-
+  // shot purge handles legacy litter.
+  //
+  // Out-of-policy hits are deduplicated in `excludedSet` so the same path
+  // hitting the filter from both the upload walk and the delete-plan walk
+  // counts once. `excludedById` powers the per-rule breakdown on the
+  // `personal-vault-out-of-policy` event so UI can render which class
+  // (secret / machine-local / scratch / …) did the work.
+  //
+  // Company-mode syncs skip this wrap entirely — company vaults have their
+  // own first-push protection (settings/, data/, workers/, .git/) defined
+  // in hq-sync's Rust util/ignore.rs, and a company may legitimately ship
+  // `output/` or `.env*` paths inside its `companies/{slug}/data/` folder.
+  const ignoreFilter = createIgnoreFilter(hqRoot);
+  const excludedSet = new Set<string>();
+  const excludedById: Record<string, number> = {};
+  const onExcluded = (rel: string, match: PersonalVaultExclusion) => {
+    if (excludedSet.has(rel)) return;
+    excludedSet.add(rel);
+    excludedById[match.id] = (excludedById[match.id] ?? 0) + 1;
+  };
+  const shouldSync = options.personalMode === true
+    ? wrapFilterWithPersonalVaultDefaults(ignoreFilter, syncRoot, onExcluded)
+    : ignoreFilter;
   const journalSlug = options.journalSlug ?? ctx.slug;
   const journal = readJournal(journalSlug);
 
@@ -599,6 +639,12 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
             // ShareResult shape stable for consumers that destructure.
             filesTombstoned,
             filesRefusedStale,
+            // Exclusions are computed during the upload walk which has
+            // already completed by the time we hit a per-file conflict-
+            // abort, so the count is meaningful here. No event emit on
+            // abort (matches the existing convention: abort short-circuits
+            // before the end-of-run telemetry emits).
+            filesExcludedByPolicy: excludedSet.size,
             conflictPaths,
             aborted: true,
           };
@@ -727,6 +773,24 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
   journal.lastSync = new Date().toISOString();
   writeJournal(journalSlug, journal);
 
+  // Personal-vault out-of-policy summary. Emit at most once, only when at
+  // least one path was excluded. Sample is capped at 10 to keep the event
+  // small (Set iteration order = insertion order, so samples are the first
+  // ten paths encountered during the walk — deterministic, not random).
+  if (excludedSet.size > 0) {
+    const samplePaths: string[] = [];
+    for (const p of excludedSet) {
+      samplePaths.push(p);
+      if (samplePaths.length >= 10) break;
+    }
+    emit({
+      type: "personal-vault-out-of-policy",
+      count: excludedSet.size,
+      samplePaths,
+      byId: { ...excludedById },
+    });
+  }
+
   return {
     filesUploaded,
     bytesUploaded,
@@ -734,6 +798,7 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
     filesDeleted,
     filesTombstoned,
     filesRefusedStale,
+    filesExcludedByPolicy: excludedSet.size,
     conflictPaths,
     aborted: false,
   };

package/src/cli/sync.ts

@@ -120,6 +120,28 @@ export type SyncProgressEvent =
       journalEtag: string;
       remoteEtag: string;
       reason: "stale-etag" | "legacy-no-etag";
+    }
+  | {
+      /**
+       * Emitted at most ONCE per `share()` call (push leg of a sync run) when
+       * `personalMode === true` and the personal-vault default-exclusion list
+       * blocked one or more files that would otherwise have uploaded. Gives
+       * the UI a single summary signal — "N files quietly excluded by default
+       * policy" — without firing one event per excluded file (which would
+       * dominate the event stream on first-sync of a dirty tree).
+       *
+       * `count` is the total number of paths the exclusion filter rejected
+       * (deduplicated across the walk). `samplePaths` carries up to 10
+       * forward-slash-separated relative paths for diagnostic display. `byId`
+       * is a per-exclusion-rule breakdown so the UI can render which class
+       * of exclusion did the work (secret / machine-local / scratch / …).
+       *
+       * Not emitted when `count === 0` — silent on a clean tree.
+       */
+      type: "personal-vault-out-of-policy";
+      count: number;
+      samplePaths: string[];
+      byId: Record<string, number>;
     };
 
 export interface SyncOptions {

package/src/index.ts

@@ -108,6 +108,16 @@ export {
   computePersonalVaultPaths,
 } from "./personal-vault.js";
 
+// Personal-vault default-exclusions (5.25+) — second-tier deep-walk filter
+// for secrets, machine-local state, scratch dirs, OS/build cruft.
+export {
+  PERSONAL_VAULT_DEFAULT_EXCLUSIONS,
+  isPersonalVaultExcluded,
+  matchPersonalVaultExclusion,
+  wrapFilterWithPersonalVaultDefaults,
+} from "./personal-vault-exclusions.js";
+export type { PersonalVaultExclusion } from "./personal-vault-exclusions.js";
+
 // VaultClient SDK (VLT-7)
 export { VaultClient, pickCanonicalPersonEntity } from "./vault-client.js";
 export {