@indigoai-us/hq-cloud 5.24.0 → 5.26.0

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.
@@ -84,6 +88,12 @@ import type { ShareOptions, ShareResult } from "../cli/share.js";
 import type { ConflictStrategy } from "../cli/conflict.js";
 import type { UploadAuthor } from "../s3.js";
 import { collectAndSendTelemetry } from "../telemetry.js";
+import {
+  TreeWatcher,
+  WatchPushDriver,
+  systemClock,
+  type Clock,
+} from "../watcher.js";
 
 /**
  * Sync direction for a run.
@@ -122,21 +132,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 +158,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 +236,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 +448,22 @@ interface ParsedArgs {
   watch: boolean;
   /** Auto-sync (Beta): ms between remote-pull passes. Required when watch=true. */
   pollRemoteMs?: number;
+  /**
+   * Event-driven push (Phase 1). When set (and `--watch` is on), the runner
+   * starts a {@link TreeWatcher} alongside the poll loop and pushes a targeted
+   * company/subtree within the debounce window of a local edit — instead of
+   * waiting up to a full `--poll-remote-ms` cycle. Gated OFF by default; the
+   * menubar passes it only for `@getindigo.ai` identities (see PRD decision).
+   * No-op without `--watch` (the one-shot path has nothing to keep alive).
+   */
+  eventPush: boolean;
+  /**
+   * 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 +474,8 @@ function parseArgs(argv: string[]): ParsedArgs | { error: string } {
   let direction: Direction = "pull";
   let watch = false;
   let pollRemoteMs: number | undefined;
+  let skipPersonal = false;
+  let eventPush = false;
 
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
@@ -465,6 +529,18 @@ 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;
+      case "--event-push":
+        // Phase 1 event-driven push enable flag. Requires --watch (validated
+        // below). Gated OFF by default; the menubar only passes it for
+        // @getindigo.ai identities for the first release.
+        eventPush = true;
+        break;
       default:
         return { error: `Unknown argument: ${arg}` };
     }
@@ -479,8 +555,21 @@ function parseArgs(argv: string[]): ParsedArgs | { error: string } {
   if (pollRemoteMs !== undefined && !watch) {
     return { error: "--poll-remote-ms requires --watch" };
   }
+  if (eventPush && !watch) {
+    return { error: "--event-push requires --watch" };
+  }
 
-  return { companies, company, onConflict, hqRoot, direction, watch, pollRemoteMs };
+  return {
+    companies,
+    company,
+    onConflict,
+    hqRoot,
+    direction,
+    watch,
+    pollRemoteMs,
+    skipPersonal,
+    eventPush,
+  };
 }
 
 // ---------------------------------------------------------------------------
@@ -698,7 +787,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 +926,7 @@ export async function runRunner(
         filesDeleted: 0,
         filesTombstoned: 0,
         filesRefusedStale: 0,
+        filesExcludedByPolicy: 0,
         conflictPaths: [],
         aborted: false,
       };
@@ -930,6 +1028,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 +1076,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,
@@ -1088,29 +1204,290 @@ const isDirectInvocation = (() => {
  * exit 0 today and so will retry — acceptable noise for the beta; deal with
  * it via a richer return shape if it shows up in Sentry.
  */
-export async function runRunnerWithLoop(argv: string[]): Promise<number> {
+/**
+ * Test/event-driven seam (US-001).
+ *
+ * `runRunnerWithLoop` performs an unbounded poll loop in production. To make
+ * the loop deterministically testable (US-003 wires the event-driven watcher
+ * into this same loop), the inter-pass sleep is injectable via `deps.sleep`.
+ * The default uses the host timer and preserves exact production behavior.
+ *
+ * A test (or US-003's wiring) injects a fake sleep that resolves immediately
+ * and/or coordinates with the {@link WatchPushDriver} seam in `../watcher.js`,
+ * so the loop can be exercised without a real 10-minute wait.
+ */
+export interface RunnerLoopDeps {
+  /** Sleep `ms` between passes. Default: host setTimeout. */
+  sleep?: (ms: number) => Promise<void>;
+  /**
+   * Run a single sync pass. Defaults to {@link runRunner}. Injected by tests
+   * (and the event-push wiring) so the poll loop and the watcher-triggered
+   * targeted push share one seam and one in-flight guard. The default ignores
+   * `deps` and forwards just the argv to `runRunner`.
+   */
+  runPass?: (passArgv: string[]) => Promise<number>;
+  /**
+   * Clock seam for the event-push watcher's debounce window. Defaults to
+   * {@link systemClock}; tests inject a `FakeClock` to advance the window
+   * deterministically. Only consulted when `--event-push` is on.
+   */
+  clock?: Clock;
+  /**
+   * Factory for the file watcher used in event-push mode. Defaults to a real
+   * {@link TreeWatcher} over `hqRoot`. Tests inject a stub exposing the same
+   * `onChange`/`start`/`stop`/`dispose` surface so no real chokidar runs.
+   */
+  createWatcher?: (opts: {
+    hqRoot: string;
+    debounceMs: number;
+    clock: Clock;
+  }) => WatcherSurface;
+  /**
+   * Register a one-shot shutdown signal handler. Defaults to listening for
+   * SIGTERM/SIGINT on `process`. Tests inject a controllable trigger to assert
+   * clean teardown without sending real signals. The returned fn detaches the
+   * handler (called during teardown so tests don't leak listeners).
+   */
+  onShutdownSignal?: (handler: () => void) => () => void;
+}
+
+/**
+ * The minimal watcher surface the loop drives. {@link TreeWatcher} satisfies
+ * it; tests inject a lighter stub. Kept narrow so the loop never reaches past
+ * the lifecycle + change-subscription contract.
+ *
+ * `onChange`'s listener receives an OPTIONAL changed relative path. The real
+ * {@link TreeWatcher} emits a bare debounced signal (no path) — in that case
+ * the loop routes the targeted push to the personal vault. A path-aware
+ * watcher (or a test stub) can pass the changed `companies/<slug>/...`
+ * relative path so the loop targets just that company.
+ */
+export interface WatcherSurface {
+  onChange(listener: (changedRelPath?: string) => void): () => void;
+  start(): void;
+  stop(): void;
+  dispose(): void;
+}
+
+/**
+ * Route a changed relative path to the push target that owns it.
+ *
+ * - `companies/<slug>/...` → a single-company push for `<slug>` (the targeted
+ *   pass per PRD decision — push only the changed company, not a full
+ *   `--companies` fanout).
+ * - anything else under hqRoot → the personal target (a `--companies` push
+ *   restricted to personal via the personal-vault scope; modeled here as the
+ *   "personal" route the caller maps to the right argv).
+ *
+ * Returns `null` for paths the routing cannot attribute (defensive — the
+ * watcher's filter already drops excluded top-levels, so this is belt-and-
+ * suspenders for synthetic events).
+ */
+export function routeChangeToTarget(
+  relPath: string,
+): { kind: "company"; slug: string } | { kind: "personal" } | null {
+  const norm = relPath.split(path.sep).join("/").replace(/^\.\//, "");
+  if (norm === "" || norm.startsWith("..")) return null;
+  const segments = norm.split("/").filter((s) => s.length > 0);
+  if (segments.length === 0) return null;
+  if (segments[0] === "companies") {
+    // companies/<slug>/... — need at least the slug segment to target.
+    if (segments.length < 2 || segments[1].length === 0) return null;
+    return { kind: "company", slug: segments[1] };
+  }
+  return { kind: "personal" };
+}
+
+/**
+ * Build the argv for a targeted push pass from a routed change. The push runs
+ * `--direction push` for just the routed target so a local edit propagates in
+ * seconds without a full fanout. Company routes use `--company <slug>`;
+ * personal routes use `--companies --direction push` (the personal-vault scope
+ * is resolved inside runRunner's fanout; skipUnchanged no-ops the company
+ * subtrees that didn't change). Inherits `--hq-root` / `--on-conflict` from
+ * the base argv. Pure helper, exported for unit testing the routing→argv map.
+ */
+export function buildTargetedPushArgv(
+  route: { kind: "company"; slug: string } | { kind: "personal" },
+  baseArgv: string[],
+): string[] {
+  const carried = carriedFlags(baseArgv);
+  if (route.kind === "company") {
+    return ["--company", route.slug, "--direction", "push", ...carried];
+  }
+  return ["--companies", "--direction", "push", ...carried];
+}
+
+export async function runRunnerWithLoop(
+  argv: string[],
+  deps: RunnerLoopDeps = {},
+): Promise<number> {
   if (!argv.includes("--watch")) {
     return runRunner(argv);
   }
+  const sleep =
+    deps.sleep ??
+    ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
+  const runPass = deps.runPass ?? ((passArgv: string[]) => runRunner(passArgv));
   const pollIdx = argv.indexOf("--poll-remote-ms");
   const pollMs =
     pollIdx >= 0 && argv[pollIdx + 1] ? Number(argv[pollIdx + 1]) : 600_000;
+  const eventPush = argv.includes("--event-push");
+  const hqIdx = argv.indexOf("--hq-root");
+  const hqRoot =
+    hqIdx >= 0 && argv[hqIdx + 1] ? argv[hqIdx + 1] : DEFAULT_HQ_ROOT;
 
-  // Strip --watch / --poll-remote-ms before delegating: the parser inside
-  // runRunner accepts them, but we don't want runRunner to think it's
-  // re-entering watch mode each iteration.
+  // Strip the loop-only flags before delegating: the parser inside runRunner
+  // accepts --watch/--poll-remote-ms/--event-push, but we don't want a per-
+  // iteration pass to think it's re-entering watch mode.
   const passArgv = argv.filter((a, i) => {
     if (a === "--watch") return false;
     if (a === "--poll-remote-ms") return false;
+    if (a === "--event-push") return false;
     if (i > 0 && argv[i - 1] === "--poll-remote-ms") return false;
     return true;
   });
 
-  while (true) {
-    const code = await runRunner(passArgv);
-    if (code !== 0) return code;
-    await new Promise<void>((resolve) => setTimeout(resolve, pollMs));
+  // ---- shared in-flight guard ------------------------------------------
+  // The poll loop AND watcher-triggered targeted pushes funnel through this
+  // mutex so a watcher push never overlaps an in-flight pass (PRD AC). A
+  // trigger that arrives while a pass runs is collapsed by WatchPushDriver's
+  // own pending-while-pushing logic, then re-armed after the pass settles.
+  let inFlight = false;
+  let stopped = false;
+  const runGuarded = async (
+    pass: () => Promise<number>,
+  ): Promise<number | "skipped"> => {
+    if (inFlight) return "skipped";
+    inFlight = true;
+    try {
+      return await pass();
+    } finally {
+      inFlight = false;
+    }
+  };
+
+  // ---- event-push wiring (Phase 1) -------------------------------------
+  let watcher: WatcherSurface | null = null;
+  let driver: WatchPushDriver | null = null;
+  let detachSignal: (() => void) | null = null;
+  let lastChangedRel: string | null = null;
+
+  if (eventPush) {
+    const clock = deps.clock ?? systemClock;
+    const debounceMs = 2000;
+    const createWatcher =
+      deps.createWatcher ??
+      ((opts) =>
+        new TreeWatcher({
+          hqRoot: opts.hqRoot,
+          debounceMs: opts.debounceMs,
+          clock: opts.clock,
+          personalMode: true,
+        }));
+    watcher = createWatcher({ hqRoot, debounceMs, clock });
+
+    // The driver runs the targeted push when a debounced burst settles. Its
+    // concurrency guard collapses a trigger that lands mid-pass; we ALSO gate
+    // through `runGuarded` so a poll pass in flight is never overlapped.
+    driver = new WatchPushDriver({
+      debounceMs: 0, // TreeWatcher already debounces; the driver just guards.
+      clock,
+      push: async () => {
+        if (stopped) return;
+        const rel = lastChangedRel;
+        const route = rel
+          ? routeChangeToTarget(rel)
+          : { kind: "personal" as const };
+        if (!route) return;
+        const targetedArgv = buildTargetedPushArgv(route, passArgv);
+        await runGuarded(() => runPass(targetedArgv));
+      },
+    });
+
+    // A debounced TreeWatcher 'changed' signal feeds the driver, which fires
+    // the targeted push after its own (zero) window — i.e. immediately, but
+    // still serialized behind any in-flight pass. A path-aware watcher passes
+    // the changed relative path so the push targets just its owning company;
+    // the bare-signal TreeWatcher leaves it null → personal-vault route.
+    watcher.onChange((changedRelPath) => {
+      if (stopped) return;
+      lastChangedRel = changedRelPath ?? null;
+      driver?.notifyChange();
+    });
+    watcher.start();
+  }
+
+  // ---- clean shutdown --------------------------------------------------
+  // SIGTERM (menubar stop_daemon) / SIGINT must tear down BOTH the watcher and
+  // the poll loop with no leaked timers or fds. We flip `stopped`, dispose the
+  // watcher + driver, and let the poll loop observe `stopped` on its next tick.
+  let resolveStopped: (() => void) | null = null;
+  const stoppedSignal = new Promise<void>((resolve) => {
+    resolveStopped = resolve;
+  });
+  const shutdown = (): void => {
+    if (stopped) return;
+    stopped = true;
+    try {
+      driver?.dispose();
+    } catch {
+      /* ignore */
+    }
+    try {
+      watcher?.dispose();
+    } catch {
+      /* ignore */
+    }
+    resolveStopped?.();
+  };
+  const onShutdownSignal =
+    deps.onShutdownSignal ??
+    ((handler: () => void) => {
+      const wrapped = () => handler();
+      process.on("SIGTERM", wrapped);
+      process.on("SIGINT", wrapped);
+      return () => {
+        process.off("SIGTERM", wrapped);
+        process.off("SIGINT", wrapped);
+      };
+    });
+  detachSignal = onShutdownSignal(shutdown);
+
+  try {
+    while (!stopped) {
+      const result = await runGuarded(() => runPass(passArgv));
+      // A poll pass that was skipped because a watcher push held the guard is
+      // benign — the next iteration retries after the poll interval.
+      if (typeof result === "number" && result !== 0) {
+        return result;
+      }
+      // Sleep the poll interval, but wake early on shutdown so SIGTERM stops
+      // the loop promptly instead of waiting out a 10-minute cycle.
+      await Promise.race([sleep(pollMs), stoppedSignal]);
+    }
+    return 0;
+  } finally {
+    shutdown();
+    detachSignal?.();
+  }
+}
+
+/**
+ * Extract the `--hq-root` / `--on-conflict` pair-flags from a base argv so a
+ * re-targeted push pass inherits the same root and conflict policy. Pure
+ * helper used by the event-push targeted-push composer.
+ */
+function carriedFlags(baseArgv: string[]): string[] {
+  const carried: string[] = [];
+  for (let i = 0; i < baseArgv.length; i++) {
+    const a = baseArgv[i];
+    if (a === "--hq-root" || a === "--on-conflict") {
+      carried.push(a);
+      if (baseArgv[i + 1] !== undefined) carried.push(baseArgv[++i]);
+    }
   }
+  return carried;
 }
 
 if (isDirectInvocation) {

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,
   };