@indigoai-us/hq-cloud 6.14.49 → 6.15.0

package/.github/workflows/unreleased-commits-nag.yml

@@ -0,0 +1,256 @@
+name: Nag unreleased commits on main
+
+# Two weekly release nags for hq-cloud:
+#
+#   nag      — `main` is carrying work nobody has released (below).
+#   pin-lag  — the latest hq-cloud release is not pinned by hq-cli and
+#              hq-desktop-app `main`. See that job's own header.
+#
+# A commit counts as UNRELEASED when it is reachable from `main` but not from
+# any STABLE tag. Stable means `vMAJOR.MINOR.PATCH` with no prerelease suffix —
+# `-rc.N`, `-beta.N` and `-alpha.N` tags deliberately do NOT silence the nag,
+# because a prerelease is not a release.
+#
+# Release sync-back commits (`chore(release): …`) are ignored. The publish
+# workflow pushes them to `main` *after* cutting the tag, so they are
+# unreachable from that tag by construction and would nag forever otherwise.
+#
+# Releasing this repo is one command — `git push origin v<next>` — so the fix
+# for a nag is always to cut the tag (or to say out loud why you are holding).
+#
+# Requires repo secret SLACK_BOT_TOKEN_RELEASE_MANAGER (the same release-manager
+# bot hq-core's `release-pr-nag.yml` uses). The bot MUST be a member of #hq-dev.
+# Without the secret the job logs a warning and exits 0 rather than failing.
+
+on:
+  schedule:
+    # Mondays 15:00 UTC (~08:00 PT). Staggered against the sibling repos'
+    # nags so all four do not land in #hq-dev in the same second.
+    - cron: '10 15 * * 1'
+  workflow_dispatch:
+    inputs:
+      threshold_hours:
+        description: 'Age of the OLDEST unreleased commit, in hours, before nagging (default 24)'
+        required: false
+        default: '24'
+
+permissions:
+  contents: read
+
+jobs:
+  nag:
+    name: Nag when main has unreleased commits
+    if: github.repository == 'indigoai-us/hq-cloud'
+    runs-on: ubuntu-latest
+    env:
+      SLACK_TOKEN: ${{ secrets.SLACK_BOT_TOKEN_RELEASE_MANAGER }}
+      SLACK_CHANNEL: '#hq-dev'
+      THRESHOLD: ${{ github.event.inputs.threshold_hours || '24' }}
+    steps:
+      - name: Check out full history and tags
+        uses: actions/checkout@v4
+        with:
+          ref: main
+          fetch-depth: 0
+
+      - name: Find unreleased commits on main and nag
+        run: |
+          set -euo pipefail
+
+          if [ -z "${SLACK_TOKEN:-}" ]; then
+            echo "::warning::SLACK_BOT_TOKEN_RELEASE_MANAGER is not set on this repository; cannot post the nag."
+            exit 0
+          fi
+
+          git fetch --force --tags --quiet origin main
+
+          # Newest stable tag reachable from main — display only.
+          LAST_TAG="$(git tag --list 'v*' --merged origin/main --sort=-v:refname \
+            | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | head -1 || true)"
+
+          # Commits on main not reachable from ANY stable tag. `--exclude` applies
+          # to the `--tags` glob that follows it, so `v*-*` drops every prerelease.
+          git log origin/main --format='%H%x09%ct%x09%s' \
+            --not --exclude='v*-*' --tags='v*' > /tmp/unreleased_all.tsv
+
+          # Drop the post-tag release sync-back commits.
+          awk -F'\t' '$3 !~ /^chore\(release\)/' /tmp/unreleased_all.tsv > /tmp/unreleased.tsv
+
+          COUNT="$(wc -l < /tmp/unreleased.tsv | tr -d ' ')"
+          echo "Last stable tag: ${LAST_TAG:-<none>}"
+          echo "Unreleased commits on main: ${COUNT}"
+
+          if [ "$COUNT" -eq 0 ]; then
+            echo "main is fully released. Nothing to nag about."
+            exit 0
+          fi
+
+          OLDEST_TS="$(tail -1 /tmp/unreleased.tsv | cut -f2)"
+          NOW="$(date -u +%s)"
+          AGE_H=$(( (NOW - OLDEST_TS) / 3600 ))
+          echo "Oldest unreleased commit age: ${AGE_H}h (threshold ${THRESHOLD}h)"
+
+          if [ "$AGE_H" -lt "$THRESHOLD" ]; then
+            echo "Under threshold. Skipping."
+            exit 0
+          fi
+
+          REPO_NAME="${GITHUB_REPOSITORY##*/}"
+          DAYS=$(( AGE_H / 24 ))
+          if [ -n "$LAST_TAG" ]; then
+            LINK="https://github.com/${GITHUB_REPOSITORY}/compare/${LAST_TAG}...main"
+            TAG_LABEL="\`${LAST_TAG}\`"
+          else
+            LINK="https://github.com/${GITHUB_REPOSITORY}/commits/main"
+            TAG_LABEL="_never released_"
+          fi
+
+          # Oldest-first sample of what is waiting, capped at 5 lines.
+          SAMPLE="$(tail -5 /tmp/unreleased.tsv | tac | cut -f3 | sed 's/^/• /')"
+          if [ "$COUNT" -gt 5 ]; then
+            SAMPLE="${SAMPLE}"$'\n'"• …and $(( COUNT - 5 )) more"
+          fi
+
+          TEXT=":package: *\`${REPO_NAME}\`: ${COUNT} commit(s) have been sitting unreleased on \`main\` for ~${AGE_H}h (${DAYS}d).* Last stable release: ${TAG_LABEL} — prereleases don't count. Shipping is one command: \`git push origin v<next>\`. <${LINK}|See what's waiting>."$'\n'"${SAMPLE}"
+
+          RESP="$(curl -s -X POST \
+            -H "Authorization: Bearer ${SLACK_TOKEN}" \
+            -H 'Content-type: application/json; charset=utf-8' \
+            --data "$(jq -nc --arg c "$SLACK_CHANNEL" --arg t "$TEXT" '{channel:$c,text:$t,unfurl_links:false}')" \
+            https://slack.com/api/chat.postMessage)"
+          OK="$(echo "$RESP" | jq -r '.ok')"
+          echo "Slack post ok=${OK} err=$(echo "$RESP" | jq -r '.error // "-"')"
+          if [ "$OK" != "true" ]; then
+            echo "::error::Slack rejected the nag: $(echo "$RESP" | jq -r '.error // "unknown"')"
+            exit 1
+          fi
+
+  pin-lag:
+    name: Nag when consumers lag the latest hq-cloud release
+    # hq-cloud ships the sync runner that hq-cli and hq-desktop-app spawn. A
+    # release nobody has pinned is a release nobody is running, so this job
+    # compares the newest STABLE hq-cloud tag against the version each
+    # consumer's `main` actually declares:
+    #
+    #   hq-cli          pnpm-lock.yaml -> resolved @indigoai-us/hq-cloud version
+    #   hq-desktop-app  crates/hq-desktop-core/src/hq_cloud.rs -> HQ_CLOUD_VERSION
+    #
+    # Comparison is EXACT on the version string (the desktop pin's leading `~`
+    # is stripped first). A tilde range like `~6.14.47` does resolve to 6.14.48
+    # at npx spawn time, so this will flag a pin that is already functionally
+    # current — that is deliberate: the written pin is kept literally in step
+    # with the latest release.
+    #
+    # Reading the two sibling repos needs a cross-repo token, so this mints an
+    # installation token from the hq-audit-bot App (same pattern as
+    # hq-core's promote-to-hq-core.yml). The App must be installed on
+    # indigoai-us/hq-cli and indigoai-us/hq-desktop-app with `contents: read`.
+    if: github.repository == 'indigoai-us/hq-cloud'
+    runs-on: ubuntu-latest
+    env:
+      SLACK_TOKEN: ${{ secrets.SLACK_BOT_TOKEN_RELEASE_MANAGER }}
+      SLACK_CHANNEL: '#hq-dev'
+      HQ_AUDIT_BOT_APP_ID: ${{ secrets.HQ_AUDIT_BOT_APP_ID }}
+      HQ_AUDIT_BOT_PRIVATE_KEY: ${{ secrets.HQ_AUDIT_BOT_PRIVATE_KEY }}
+    steps:
+      - name: Check out full history and tags
+        uses: actions/checkout@v4
+        with:
+          ref: main
+          fetch-depth: 0
+
+      - name: Preflight credentials
+        id: pre
+        run: |
+          set -euo pipefail
+          if [ -z "${SLACK_TOKEN:-}" ]; then
+            echo "::warning::SLACK_BOT_TOKEN_RELEASE_MANAGER is not set on this repository; cannot post the nag."
+            echo "ready=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          if [ -z "${HQ_AUDIT_BOT_APP_ID:-}" ] || [ -z "${HQ_AUDIT_BOT_PRIVATE_KEY:-}" ]; then
+            echo "::warning::hq-audit-bot App credentials are not set; cannot read hq-cli / hq-desktop-app main."
+            echo "ready=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          echo "ready=true" >> "$GITHUB_OUTPUT"
+
+      - name: Mint installation token for the consumer repos
+        id: app-token
+        if: steps.pre.outputs.ready == 'true'
+        uses: actions/create-github-app-token@v1
+        with:
+          app-id: ${{ env.HQ_AUDIT_BOT_APP_ID }}
+          private-key: ${{ env.HQ_AUDIT_BOT_PRIVATE_KEY }}
+          owner: indigoai-us
+          repositories: |
+            hq-cli
+            hq-desktop-app
+
+      - name: Compare consumer pins against the latest hq-cloud release
+        if: steps.pre.outputs.ready == 'true'
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+        run: |
+          set -euo pipefail
+
+          git fetch --force --tags --quiet origin main
+
+          LATEST_TAG="$(git tag --list 'v*' --merged origin/main --sort=-v:refname \
+            | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | head -1 || true)"
+          if [ -z "$LATEST_TAG" ]; then
+            echo "No stable hq-cloud release yet; nothing to compare against."
+            exit 0
+          fi
+          LATEST="${LATEST_TAG#v}"
+          echo "Latest stable hq-cloud release: ${LATEST}"
+
+          # --- hq-cli: resolved version in the lockfile's importers section ---
+          gh api "repos/indigoai-us/hq-cli/contents/pnpm-lock.yaml?ref=main" \
+            -H 'Accept: application/vnd.github.raw' > /tmp/hq-cli-lock.yaml
+          CLI_PIN="$(grep -A2 "^      '@indigoai-us/hq-cloud':" /tmp/hq-cli-lock.yaml \
+            | awk '/^        version:/{print $2; exit}' | sed 's/(.*//')"
+          if [ -z "$CLI_PIN" ]; then
+            echo "::error::Could not read the resolved @indigoai-us/hq-cloud version from hq-cli's pnpm-lock.yaml. The lockfile layout changed — fix this parser rather than letting the check pass silently."
+            exit 1
+          fi
+          echo "hq-cli pins: ${CLI_PIN}"
+
+          # --- hq-desktop-app: HQ_CLOUD_VERSION constant, tilde stripped ---
+          gh api "repos/indigoai-us/hq-desktop-app/contents/crates/hq-desktop-core/src/hq_cloud.rs?ref=main" \
+            -H 'Accept: application/vnd.github.raw' > /tmp/hq_cloud.rs
+          DESK_RAW="$(grep -oP 'HQ_CLOUD_VERSION\s*:\s*&str\s*=\s*"\K[^"]+' /tmp/hq_cloud.rs | head -1)"
+          if [ -z "$DESK_RAW" ]; then
+            echo "::error::Could not read HQ_CLOUD_VERSION from hq-desktop-app's crates/hq-desktop-core/src/hq_cloud.rs. The constant moved or was renamed — fix this parser rather than letting the check pass silently."
+            exit 1
+          fi
+          DESK_PIN="${DESK_RAW#\~}"
+          DESK_PIN="${DESK_PIN#^}"
+          echo "hq-desktop-app pins: ${DESK_RAW} (compared as ${DESK_PIN})"
+
+          LAGGARDS=""
+          if [ "$CLI_PIN" != "$LATEST" ]; then
+            LAGGARDS="${LAGGARDS}"$'\n'"• \`hq-cli\` is on \`${CLI_PIN}\` (pnpm-lock.yaml)"
+          fi
+          if [ "$DESK_PIN" != "$LATEST" ]; then
+            LAGGARDS="${LAGGARDS}"$'\n'"• \`hq-desktop-app\` is on \`${DESK_RAW}\` (HQ_CLOUD_VERSION)"
+          fi
+
+          if [ -z "$LAGGARDS" ]; then
+            echo "Both consumers are pinned to ${LATEST}. Nothing to nag about."
+            exit 0
+          fi
+
+          TEXT=":link: *hq-cloud \`${LATEST}\` is released but not pinned everywhere.* A runner nobody pins is a runner nobody runs:${LAGGARDS}"$'\n'"Bump the pin(s) to \`${LATEST}\` and ship. <https://github.com/indigoai-us/hq-cloud/releases/tag/${LATEST_TAG}|Release ${LATEST_TAG}>."
+
+          RESP="$(curl -s -X POST \
+            -H "Authorization: Bearer ${SLACK_TOKEN}" \
+            -H 'Content-type: application/json; charset=utf-8' \
+            --data "$(jq -nc --arg c "$SLACK_CHANNEL" --arg t "$TEXT" '{channel:$c,text:$t,unfurl_links:false}')" \
+            https://slack.com/api/chat.postMessage)"
+          OK="$(echo "$RESP" | jq -r '.ok')"
+          echo "Slack post ok=${OK} err=$(echo "$RESP" | jq -r '.error // "-"')"
+          if [ "$OK" != "true" ]; then
+            echo "::error::Slack rejected the nag: $(echo "$RESP" | jq -r '.error // "unknown"')"
+            exit 1
+          fi

package/dist/bin/sync-runner-watch-loop.d.ts

@@ -10,9 +10,21 @@ import type { Direction, RunnerLoopDeps, RunnerPassOutcome } from "./sync-runner
  * can be unit-tested without a real host or a 10-minute wait.
  */
 export declare function adaptivePollMs(load1: number, cpuCount: number, floorMs?: number, ceilMs?: number): number;
+/**
+ * Advance the cadence from its previous monotonic deadline, rather than from
+ * the end of a pass. A slow pass is allowed one immediate catch-up pass; the
+ * returned deadline is always the first future slot, so missed slots cannot
+ * turn into an unbounded burst.
+ */
+export declare function advanceMonotonicDeadline(previousDueAt: number, now: number, intervalMs: number): {
+    nextDueAt: number;
+    delayMs: number;
+};
 export interface ParsedLoopArgs {
     hqRoot: string;
     lockTimeoutSec?: number;
+    /** Resolved parser flag; environment policy is applied by resolveSkipPersonal. */
+    skipPersonal?: boolean;
     /**
      * The run's resolved sync direction, straight from `parseArgs` (the single
      * source of truth — same default as the parser). The drain reads this to

package/dist/bin/sync-runner-watch-loop.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sync-runner-watch-loop.d.ts","sourceRoot":"","sources":["../../src/bin/sync-runner-watch-loop.ts"],"names":[],"mappings":"AAwBA,OAAO,EAIL,WAAW,EAEZ,MAAM,eAAe,CAAC;AAWvB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAU9D,OAAO,KAAK,EACV,SAAS,EACT,cAAc,EACd,iBAAiB,EAElB,MAAM,kBAAkB,CAAC;AAiB1B;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,MAA+B,EACxC,MAAM,GAAE,MAA8B,GACrC,MAAM,CAKR;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAED,MAAM,WAAW,gBAAgB;IAC/B,mCAAmC,EAAE,CACnC,QAAQ,EAAE,MAAM,EAAE,KACf,OAAO,CAAC,MAAM,GAAG,iBAAiB,CAAC,CAAC;IACzC,oBAAoB,EAAE,MAAM,CAAC;IAC7B,uBAAuB,EAAE,MAAM,CAAC;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,eAAe,CAAC,GAAG,IAAI,CAAC;IAC7E,qBAAqB,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,KAAK,YAAY,GAAG,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC,OAAO,CAAC,CAAC;AAE5D;;;GAGG;AACH,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,YAAY,EACnB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,QAAQ,GAAG,WAAW,GAC3B,KAAK,CAAC,CAAC,MAAM,EAAE,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC,CASvC;AAWD;;;;;;;;;;;;GAYG;AACH,wBAAgB,oCAAoC,CAClD,eAAe,EAAE,MAAM,EACvB,cAAc,EAAE,MAAM,GACrB,OAAO,CAIT;AAuBD,wBAAsB,2BAA2B,CAC/C,IAAI,EAAE,MAAM,EAAE,EACd,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE,cAAc,EACpB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,MAAM,CAAC,CAgBjB;AAED,wBAAsB,YAAY,CAChC,IAAI,EAAE,MAAM,EAAE,EACd,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE,cAAc,EACpB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,MAAM,CAAC,CAw2BjB"}
+{"version":3,"file":"sync-runner-watch-loop.d.ts","sourceRoot":"","sources":["../../src/bin/sync-runner-watch-loop.ts"],"names":[],"mappings":"AAyBA,OAAO,EAIL,WAAW,EAEZ,MAAM,eAAe,CAAC;AAWvB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAW9D,OAAO,KAAK,EACV,SAAS,EACT,cAAc,EACd,iBAAiB,EAElB,MAAM,kBAAkB,CAAC;AAiB1B;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,MAA+B,EACxC,MAAM,GAAE,MAA8B,GACrC,MAAM,CAKR;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,aAAa,EAAE,MAAM,EACrB,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,MAAM,GACjB;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAYxC;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kFAAkF;IAClF,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAED,MAAM,WAAW,gBAAgB;IAC/B,mCAAmC,EAAE,CACnC,QAAQ,EAAE,MAAM,EAAE,KACf,OAAO,CAAC,MAAM,GAAG,iBAAiB,CAAC,CAAC;IACzC,oBAAoB,EAAE,MAAM,CAAC;IAC7B,uBAAuB,EAAE,MAAM,CAAC;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,eAAe,CAAC,GAAG,IAAI,CAAC;IAC7E,qBAAqB,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,KAAK,YAAY,GAAG,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC,OAAO,CAAC,CAAC;AAE5D;;;GAGG;AACH,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,YAAY,EACnB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,QAAQ,GAAG,WAAW,GAC3B,KAAK,CAAC,CAAC,MAAM,EAAE,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC,CASvC;AAWD;;;;;;;;;;;;GAYG;AACH,wBAAgB,oCAAoC,CAClD,eAAe,EAAE,MAAM,EACvB,cAAc,EAAE,MAAM,GACrB,OAAO,CAIT;AAuBD,wBAAsB,2BAA2B,CAC/C,IAAI,EAAE,MAAM,EAAE,EACd,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE,cAAc,EACpB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,MAAM,CAAC,CAgBjB;AAED,wBAAsB,YAAY,CAChC,IAAI,EAAE,MAAM,EAAE,EACd,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE,cAAc,EACpB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,MAAM,CAAC,CA49BjB"}

package/dist/bin/sync-runner-watch-loop.js

@@ -1,6 +1,7 @@
 import * as os from "os";
 import * as path from "path";
 import * as fs from "fs";
+import { performance } from "node:perf_hooks";
 import { inventoryManagedSnapshots } from "../backup-prune.js";
 import { VaultClient } from "../index.js";
 import { pickCanonicalPersonEntity } from "../vault-client.js";
@@ -14,7 +15,7 @@ import { TreeWatcher, systemClock, } from "../watcher.js";
 import { clearLocalDeleteIntent, markLocalDeleteIntent, PERSONAL_VAULT_JOURNAL_SLUG, readJournal, writeJournal, } from "../journal.js";
 import { NoopPushReceiver, } from "../sync/push-receiver.js";
 import { resolveEventSync, startEventSync as defaultStartEventSync, } from "../sync/event-sync.js";
-import { buildScopedDrainPullArgv, buildScopedPushArgv, buildTargetedPullArgv, routeChangeToTarget, routeKey, } from "./sync-runner-watch-routes.js";
+import { buildScopedDrainPullArgv, buildScopedPushArgv, buildTargetedPullArgv, isWatchRouteSelected, routeChangeToTarget, routeKey, } from "./sync-runner-watch-routes.js";
 import { resolveSkipCompanies } from "./sync-runner-planning.js";
 const FULL_RECONCILE_EVERY_TICKS = 10;
 /**
@@ -43,6 +44,24 @@ export function adaptivePollMs(load1, cpuCount, floorMs = ADAPTIVE_POLL_FLOOR_MS
     const ratio = Math.max(0, Math.min(1, saturation));
     return Math.round(floorMs + ratio * (ceilMs - floorMs));
 }
+/**
+ * Advance the cadence from its previous monotonic deadline, rather than from
+ * the end of a pass. A slow pass is allowed one immediate catch-up pass; the
+ * returned deadline is always the first future slot, so missed slots cannot
+ * turn into an unbounded burst.
+ */
+export function advanceMonotonicDeadline(previousDueAt, now, intervalMs) {
+    let nextDueAt = previousDueAt + intervalMs;
+    if (nextDueAt > now) {
+        return { nextDueAt, delayMs: nextDueAt - now };
+    }
+    // The pass crossed at least one deadline. Run exactly one catch-up now,
+    // then retain only the first future cadence slot.
+    do {
+        nextDueAt += intervalMs;
+    } while (nextDueAt <= now);
+    return { nextDueAt, delayMs: 0 };
+}
 /**
  * Select journal entries covered by one watcher delete. Exact file unlinks
  * deliberately avoid enumeration; only directory unlinks expand descendants.
@@ -116,6 +135,7 @@ export async function runOneShotWithOperationLock(argv, parsed, deps, runtime) {
 export async function runWatchLoop(argv, parsed, deps, runtime) {
     const sleep = deps.sleep ??
         ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const monotonicNow = deps.monotonicNow ?? (() => performance.now());
     const runPass = deps.runPass ?? runtime.runPassWithOperationLockAlreadyHeld;
     const pollIdx = argv.indexOf("--poll-remote-ms");
     // An explicit --poll-remote-ms pins a fixed interval (menubar/CLI still set
@@ -126,6 +146,21 @@ export async function runWatchLoop(argv, parsed, deps, runtime) {
     const cpuCount = os.cpus().length;
     const eventPush = argv.includes("--event-push");
     const companiesMode = argv.includes("--companies");
+    const companyMode = argv.includes("--company");
+    const personalMode = argv.includes("--personal");
+    // Keep this at the watcher ingress rather than importing the runner's
+    // resolver: sync-runner imports this loop, and a reverse value import would
+    // create a runtime cycle. These are the parser's documented truthy values.
+    const skipPersonalEnv = (process.env.HQ_SYNC_SKIP_PERSONAL ?? "").toLowerCase();
+    const watchRouteSelection = {
+        companies: companiesMode,
+        company: companyMode,
+        personal: personalMode,
+        skipPersonal: parsed.skipPersonal === true ||
+            skipPersonalEnv === "1" ||
+            skipPersonalEnv === "true" ||
+            skipPersonalEnv === "yes",
+    };
     const hqRoot = parsed.hqRoot;
     // Delayed and daily: this must never be attached to the 15s poll cadence.
     // Stage 0 remains dry-run only; the standalone hq-backup-prune command is
@@ -220,6 +255,45 @@ export async function runWatchLoop(argv, parsed, deps, runtime) {
         }
     };
     let stopped = false;
+    let resolveStopped = null;
+    const stoppedSignal = new Promise((resolve) => {
+        resolveStopped = resolve;
+    });
+    // A signal can arrive while a guarded pass is running, before the next wait
+    // has registered. Keep a monotonic generation so that event is retained and
+    // consumed by the next scheduler wait instead of being lost.
+    let interruptGeneration = 0;
+    let observedInterruptGeneration = 0;
+    let resolveInterruptWait = null;
+    const interruptWait = () => {
+        if (stopped)
+            return;
+        interruptGeneration += 1;
+        const resolve = resolveInterruptWait;
+        resolveInterruptWait = null;
+        resolve?.();
+    };
+    const waitForNextPass = async (delayMs) => {
+        if (interruptGeneration !== observedInterruptGeneration) {
+            observedInterruptGeneration = interruptGeneration;
+            return;
+        }
+        await Promise.race([
+            sleep(delayMs),
+            new Promise((resolve) => {
+                resolveInterruptWait = resolve;
+                // Do not lose an event that arrived between the first generation
+                // check and registration of this wait.
+                if (interruptGeneration !== observedInterruptGeneration) {
+                    resolveInterruptWait = null;
+                    resolve();
+                }
+            }),
+            stoppedSignal,
+        ]);
+        resolveInterruptWait = null;
+        observedInterruptGeneration = interruptGeneration;
+    };
     let activePass = null;
     const pendingPasses = [];
     const resolveStoppedQueue = () => {
@@ -269,11 +343,45 @@ export async function runWatchLoop(argv, parsed, deps, runtime) {
     const pendingWatcherPaths = new Map();
     const pendingWatcherChanges = new Map();
     let pendingWatcherOriginalBatch = null;
+    // Every coalesced watcher batch gets one durable in-process generation.
+    // A wake can cause the scheduler to revisit a drained batch, but an event
+    // announcement is an external side effect and must occur at most once for
+    // that batch after its targeted push succeeds.
+    let nextWatcherBatchGeneration = 0;
+    let pendingWatcherBatchGeneration = null;
+    const lastPublishedWatcherBatchGenerationByRoute = new Map();
     let pendingWatcherBareChange = false;
     let pendingWatcherOverflowed = false;
     let pendingWatcherDroppedPaths = 0;
     let pendingWatcherDroppedBytes = 0;
     const addPendingWatcherChange = (changedRelPath, batch) => {
+        if (batch) {
+            const paths = new Map();
+            const changes = new Map();
+            for (const [absolutePath, relativePath] of batch.paths.entries()) {
+                const route = routeChangeToTarget(relativePath);
+                if (!route || !isWatchRouteSelected(route, watchRouteSelection))
+                    continue;
+                paths.set(absolutePath, relativePath);
+                const change = batch.changes?.get(absolutePath);
+                if (change)
+                    changes.set(absolutePath, change);
+            }
+            if (paths.size === 0)
+                return false;
+            batch = {
+                ...batch,
+                paths,
+                changes,
+            };
+        }
+        else if (changedRelPath) {
+            const route = routeChangeToTarget(changedRelPath);
+            if (!route || !isWatchRouteSelected(route, watchRouteSelection)) {
+                return false;
+            }
+        }
+        pendingWatcherBatchGeneration ??= ++nextWatcherBatchGeneration;
         if (batch) {
             pendingWatcherOriginalBatch =
                 pendingWatcherPaths.size === 0 &&
@@ -293,7 +401,7 @@ export async function runWatchLoop(argv, parsed, deps, runtime) {
                 pendingWatcherDroppedPaths += batch.droppedPaths ?? 0;
                 pendingWatcherDroppedBytes += batch.droppedBytes ?? 0;
             }
-            return;
+            return true;
         }
         if (changedRelPath) {
             pendingWatcherOriginalBatch = null;
@@ -307,10 +415,11 @@ export async function runWatchLoop(argv, parsed, deps, runtime) {
             // a prior batch left for this path so the stale intent cannot leak
             // into the coalesced batch (#227).
             pendingWatcherChanges.delete(absolutePath);
-            return;
+            return true;
         }
         pendingWatcherOriginalBatch = null;
         pendingWatcherBareChange = true;
+        return true;
     };
     const takePendingWatcherChange = () => {
         const batch = pendingWatcherOriginalBatch !== null && !pendingWatcherOverflowed
@@ -331,6 +440,7 @@ export async function runWatchLoop(argv, parsed, deps, runtime) {
                 }
                 : null;
         const bare = pendingWatcherBareChange;
+        const generation = pendingWatcherBatchGeneration;
         pendingWatcherPaths.clear();
         pendingWatcherChanges.clear();
         pendingWatcherOriginalBatch = null;
@@ -338,9 +448,12 @@ export async function runWatchLoop(argv, parsed, deps, runtime) {
         pendingWatcherOverflowed = false;
         pendingWatcherDroppedPaths = 0;
         pendingWatcherDroppedBytes = 0;
-        return { batch, bare };
+        pendingWatcherBatchGeneration = null;
+        return { batch, bare, generation };
     };
-    const restorePendingWatcherPaths = (paths) => {
+    const restorePendingWatcherPaths = (paths, generation) => {
+        pendingWatcherBatchGeneration ??=
+            generation ?? ++nextWatcherBatchGeneration;
         pendingWatcherOriginalBatch = null;
         for (const [absolutePath, relativePath] of paths.entries()) {
             pendingWatcherPaths.set(absolutePath, relativePath);
@@ -382,7 +495,7 @@ export async function runWatchLoop(argv, parsed, deps, runtime) {
     };
     const journalCoordinates = (relativePath) => {
         const route = routeChangeToTarget(relativePath);
-        if (!route)
+        if (!route || !isWatchRouteSelected(route, watchRouteSelection))
             return null;
         if (route.kind === "personal") {
             return { slug: PERSONAL_VAULT_JOURNAL_SLUG, key: relativePath };
@@ -572,9 +685,11 @@ export async function runWatchLoop(argv, parsed, deps, runtime) {
     const publishBatchIfAvailable = (paths) => {
         if (!stopped && eventSync && paths.size > 0) {
             eventSync.publishBatch({ paths: new Map(paths) });
+            return true;
         }
+        return false;
     };
-    const runScopedDrain = async (batch) => {
+    const runScopedDrain = async (batch, watcherBatchGeneration) => {
         if (drainRunsPush && batch && batch.paths.size > 0) {
             const skipCompanies = resolveSkipCompanies();
             const grouped = groupBatchByRoute(batch);
@@ -596,21 +711,28 @@ export async function runWatchLoop(argv, parsed, deps, runtime) {
                             : (result.result?.pushPathResults ?? [])
                                 .filter((pathResult) => pathResult.status === "refused")
                                 .map((pathResult) => pathResult.relativePath));
-                        publishBatchIfAvailable(new Map([...group.paths.entries()].filter(([absolutePath, relativePath]) => {
-                            if (refusedPaths.has(relativePath))
-                                return false;
-                            if (group.changes.get(absolutePath)?.kind !== "unlinkDir") {
-                                return true;
+                        const route = routeKey(group.route);
+                        const generation = watcherBatchGeneration ?? 0;
+                        if (lastPublishedWatcherBatchGenerationByRoute.get(route) !== generation) {
+                            const published = publishBatchIfAvailable(new Map([...group.paths.entries()].filter(([absolutePath, relativePath]) => {
+                                if (refusedPaths.has(relativePath))
+                                    return false;
+                                if (group.changes.get(absolutePath)?.kind !== "unlinkDir") {
+                                    return true;
+                                }
+                                return ![...refusedPaths].some((refusedPath) => refusedPath.startsWith(`${relativePath}/`));
+                            })));
+                            if (published) {
+                                lastPublishedWatcherBatchGenerationByRoute.set(route, generation);
                             }
-                            return ![...refusedPaths].some((refusedPath) => refusedPath.startsWith(`${relativePath}/`));
-                        })));
+                        }
                     }
                     else {
-                        restorePendingWatcherPaths(group.paths);
+                        restorePendingWatcherPaths(group.paths, watcherBatchGeneration);
                     }
                 }
                 catch (err) {
-                    restorePendingWatcherPaths(group.paths);
+                    restorePendingWatcherPaths(group.paths, watcherBatchGeneration);
                     process.stderr.write(`watch scoped push failed, will retry next tick: ${describeError(err)}\n`);
                 }
             }
@@ -654,12 +776,18 @@ export async function runWatchLoop(argv, parsed, deps, runtime) {
         watcher.onChange((changedRelPath, batch) => {
             if (stopped)
                 return;
-            addPendingWatcherChange(changedRelPath, batch);
+            if (addPendingWatcherChange(changedRelPath, batch))
+                interruptWait();
         });
         watcher.start();
         const receiverSyncFn = async (ctx) => {
             if (stopped)
                 return;
+            // A received wake/high-water signal means there is bounded work now.
+            // It wakes the scheduler but is still funneled through runGuarded below,
+            // so it cannot overlap the pass that may currently own the operation
+            // lock.
+            interruptWait();
             const route = routeChangeToTarget(ctx.event.relativePath);
             if (!route)
                 return;
@@ -672,8 +800,7 @@ export async function runWatchLoop(argv, parsed, deps, runtime) {
         const createReceiver = deps.createReceiver ?? (() => new NoopPushReceiver());
         receiver = createReceiver({ syncFn: receiverSyncFn, hqRoot });
         void Promise.resolve(receiver.start()).catch(() => undefined);
-        const email = claims?.email;
-        if (resolveEventSync(email, process.env.HQ_SYNC_EVENT_SYNC)) {
+        if (resolveEventSync(process.env.HQ_SYNC_EVENT_SYNC)) {
             const startES = deps.startEventSync ?? defaultStartEventSync;
             void (async () => {
                 const eventSyncClient = new VaultClient({
@@ -711,10 +838,6 @@ export async function runWatchLoop(argv, parsed, deps, runtime) {
             });
         }
     }
-    let resolveStopped = null;
-    const stoppedSignal = new Promise((resolve) => {
-        resolveStopped = resolve;
-    });
     const shutdown = () => {
         if (stopped)
             return;
@@ -752,6 +875,9 @@ export async function runWatchLoop(argv, parsed, deps, runtime) {
             };
         });
     detachSignal = onShutdownSignal(shutdown);
+    // The initial reconcile is due immediately. Later passes advance from this
+    // deadline, not from pass completion, so cadence stays monotonic.
+    let nextDueAt = monotonicNow();
     let pollTick = 0;
     try {
         while (!stopped) {
@@ -772,7 +898,7 @@ export async function runWatchLoop(argv, parsed, deps, runtime) {
                 pollTick % FULL_RECONCILE_EVERY_TICKS === 0;
             const result = shouldRunFull
                 ? await runGuarded(passArgv)
-                : await runScopedDrain(pending.batch);
+                : await runScopedDrain(pending.batch, pending.generation);
             // This batch's episode has now been prepared and pushed, so a later
             // removal under the same path is judged fresh — a root that never
             // expired would silently refuse ordinary deletes from here on.
@@ -829,7 +955,9 @@ export async function runWatchLoop(argv, parsed, deps, runtime) {
                 }
             }
             const nextPollMs = explicitPollMs ?? adaptivePollMs(sampleLoadAvg(), cpuCount);
-            await Promise.race([sleep(nextPollMs), stoppedSignal]);
+            const schedule = advanceMonotonicDeadline(nextDueAt, monotonicNow(), nextPollMs);
+            nextDueAt = schedule.nextDueAt;
+            await waitForNextPass(schedule.delayMs);
         }
         return 0;
     }