@indigoai-us/hq-cloud 6.16.30 → 6.16.32

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (53) hide show
  1. package/dist/bin/sync-runner-post-sync-flags.d.ts +22 -11
  2. package/dist/bin/sync-runner-post-sync-flags.d.ts.map +1 -1
  3. package/dist/bin/sync-runner-post-sync-flags.js +31 -44
  4. package/dist/bin/sync-runner-post-sync-flags.js.map +1 -1
  5. package/dist/bin/sync-runner-post-sync-flags.test.js +37 -77
  6. package/dist/bin/sync-runner-post-sync-flags.test.js.map +1 -1
  7. package/dist/bin/sync-runner-watch-loop.d.ts.map +1 -1
  8. package/dist/bin/sync-runner-watch-loop.js +92 -2
  9. package/dist/bin/sync-runner-watch-loop.js.map +1 -1
  10. package/dist/bin/sync-runner.d.ts +7 -0
  11. package/dist/bin/sync-runner.d.ts.map +1 -1
  12. package/dist/bin/sync-runner.js +4 -19
  13. package/dist/bin/sync-runner.js.map +1 -1
  14. package/dist/bin/sync-runner.test.js +148 -6
  15. package/dist/bin/sync-runner.test.js.map +1 -1
  16. package/dist/cli/share.test.js +44 -0
  17. package/dist/cli/share.test.js.map +1 -1
  18. package/dist/ignore.d.ts +40 -14
  19. package/dist/ignore.d.ts.map +1 -1
  20. package/dist/ignore.js +119 -60
  21. package/dist/ignore.js.map +1 -1
  22. package/dist/ignore.test.js +205 -29
  23. package/dist/ignore.test.js.map +1 -1
  24. package/dist/journal-store.test.js +48 -1
  25. package/dist/journal-store.test.js.map +1 -1
  26. package/dist/journal.d.ts +10 -1
  27. package/dist/journal.d.ts.map +1 -1
  28. package/dist/journal.js +11 -1
  29. package/dist/journal.js.map +1 -1
  30. package/dist/sync/area-ledger-migration.d.ts +31 -1
  31. package/dist/sync/area-ledger-migration.d.ts.map +1 -1
  32. package/dist/sync/area-ledger-migration.js +47 -10
  33. package/dist/sync/area-ledger-migration.js.map +1 -1
  34. package/dist/sync/area-ledger-migration.test.js +27 -0
  35. package/dist/sync/area-ledger-migration.test.js.map +1 -1
  36. package/dist/sync/area-ledger.d.ts.map +1 -1
  37. package/dist/sync/area-ledger.js +14 -2
  38. package/dist/sync/area-ledger.js.map +1 -1
  39. package/dist/sync/area-ledger.test.js +37 -0
  40. package/dist/sync/area-ledger.test.js.map +1 -1
  41. package/dist/watch-roots.d.ts +11 -0
  42. package/dist/watch-roots.d.ts.map +1 -1
  43. package/dist/watch-roots.js +16 -7
  44. package/dist/watch-roots.js.map +1 -1
  45. package/dist/watch-roots.test.js +97 -0
  46. package/dist/watch-roots.test.js.map +1 -1
  47. package/dist/watcher.d.ts +82 -4
  48. package/dist/watcher.d.ts.map +1 -1
  49. package/dist/watcher.js +286 -48
  50. package/dist/watcher.js.map +1 -1
  51. package/dist/watcher.test.js +702 -1
  52. package/dist/watcher.test.js.map +1 -1
  53. package/package.json +1 -1
@@ -4,7 +4,7 @@ import * as os from "os";
4
4
  import * as path from "path";
5
5
  import { createHash } from "node:crypto";
6
6
  import { watch } from "chokidar";
7
- import { FakeClock, WatchPushDriver, TreeWatcher, ChokidarWatchBudget, createWatchPathFilter, toChokidarIgnored, PushEventEmitter, PUBLISH_OUTCOME_JOURNALD_CEILING_BYTES, PUBLISH_OUTCOME_SUCCESS_SAMPLE_CAP, resolveEventDebounceConfig, summarizePublishBatchOutcome, DEFAULT_EVENT_DEBOUNCE_MS, DEFAULT_EVENT_MAX_WAIT_MS, DEFAULT_EVENT_SMALL_BATCH_DEBOUNCE_MS, DEFAULT_EVENT_SMALL_BATCH_MAX_PATHS, DEFAULT_EVENT_SMALL_BATCH_MAX_BYTES, DEFAULT_PUBLISH_MIN_INTERVAL_MS, EVENT_DEBOUNCE_MS_ENV, EVENT_MAX_WAIT_MS_ENV, EVENT_SMALL_BATCH_DEBOUNCE_MS_ENV, EVENT_SMALL_BATCH_MAX_PATHS_ENV, EVENT_SMALL_BATCH_MAX_BYTES_ENV, DEFAULT_TREE_WATCHER_MAX_WATCHED_PATHS, MAX_TREE_WATCHER_MAX_WATCHED_PATHS, TREE_WATCHER_MAX_WATCHED_PATHS_ENV, resolveMaxWatchedPaths, PUBLISH_MIN_INTERVAL_MS_ENV, resolvePublishMinIntervalMs, DurablePublishedContentHashes, DURABLE_PUBLISHED_HASH_BATCH_FLUSH_MS, replayDurablePublishedContentHashRecordsForTest } from "./watcher.js";
7
+ import { FakeClock, WatchPushDriver, TreeWatcher, ChokidarWatchBudget, createWatchPathFilter, toChokidarIgnored, PushEventEmitter, PUBLISH_OUTCOME_JOURNALD_CEILING_BYTES, PUBLISH_OUTCOME_SUCCESS_SAMPLE_CAP, resolveEventDebounceConfig, summarizePublishBatchOutcome, DEFAULT_EVENT_DEBOUNCE_MS, DEFAULT_EVENT_MAX_WAIT_MS, DEFAULT_EVENT_SMALL_BATCH_DEBOUNCE_MS, DEFAULT_EVENT_SMALL_BATCH_MAX_PATHS, DEFAULT_EVENT_SMALL_BATCH_MAX_BYTES, DEFAULT_PUBLISH_MIN_INTERVAL_MS, EVENT_DEBOUNCE_MS_ENV, EVENT_MAX_WAIT_MS_ENV, EVENT_SMALL_BATCH_DEBOUNCE_MS_ENV, EVENT_SMALL_BATCH_MAX_PATHS_ENV, EVENT_SMALL_BATCH_MAX_BYTES_ENV, DEFAULT_TREE_WATCHER_MAX_WATCHED_PATHS, MAX_TREE_WATCHER_MAX_WATCHED_PATHS, TREE_WATCHER_MAX_WATCHED_PATHS_ENV, resolveMaxWatchedPaths, PUBLISH_MIN_INTERVAL_MS_ENV, resolvePublishMinIntervalMs, DurablePublishedContentHashes, DURABLE_PUBLISHED_HASH_BATCH_FLUSH_MS, replayDurablePublishedContentHashRecordsForTest, startScopedRecursiveWatch, selectTreeWatchBackend } from "./watcher.js";
8
8
  import { StaticFlagProvider } from "./sync/feature-flags.js";
9
9
  import { StateStore, StateStoreLockError } from "./sync/state-store.js";
10
10
  import { RealtimeUnavailableError, } from "./sync/push-transport.js";
@@ -168,6 +168,43 @@ describe("TreeWatcher pending backlog caps", () => {
168
168
  fs.rmSync(dir, { recursive: true, force: true });
169
169
  }
170
170
  });
171
+ it("keeps a warm-up epoch only for a queued deletion capture, and only while it runs", async () => {
172
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-watcher-warmup-epochs-"));
173
+ try {
174
+ for (let i = 0; i < 6; i++)
175
+ fs.writeFileSync(path.join(dir, `unchanged-${i}.md`), "old");
176
+ const settle = Date.now() + 50;
177
+ while (Date.now() < settle) { /* let old ctime settle below the cutoff */ }
178
+ const cutoff = Date.now();
179
+ while (Date.now() < cutoff + 50) { /* filesystems may round ctime down */ }
180
+ for (let i = 0; i < 4; i++)
181
+ fs.writeFileSync(path.join(dir, `fresh-${i}.md`), "new");
182
+ let resolveCapture;
183
+ const watcher = new TreeWatcher({
184
+ hqRoot: dir,
185
+ pathFilter: () => true,
186
+ queueLocalDeleteSnapshots: async () => {
187
+ await new Promise((resolve) => { resolveCapture = resolve; });
188
+ return [];
189
+ },
190
+ });
191
+ const result = watcher.collectWarmupCatchup(cutoff, ["gone-during-warmup.md"]);
192
+ expect([...result.batch.paths.values()].sort()).toEqual([
193
+ "fresh-0.md", "fresh-1.md", "fresh-2.md", "fresh-3.md", "gone-during-warmup.md",
194
+ ]);
195
+ // Four live changes were recorded, but only the deletion has a capture
196
+ // in flight, so only the deletion holds an epoch.
197
+ expect(watcher.censusSizes().deleteSnapshotEpochs).toBe(1);
198
+ await new Promise((resolve) => setImmediate(resolve)); // the queued job starts
199
+ resolveCapture();
200
+ await new Promise((resolve) => setImmediate(resolve));
201
+ expect(watcher.censusSizes().deleteSnapshotEpochs).toBe(0);
202
+ watcher.dispose();
203
+ }
204
+ finally {
205
+ fs.rmSync(dir, { recursive: true, force: true });
206
+ }
207
+ });
171
208
  it("does not report a journal row as deleted when its file exists behind a symlinked directory", () => {
172
209
  // The warm-up walk never descends through a symlinked directory (a Dirent
173
210
  // symlink is not a directory), so rows journaled under such a path were
@@ -2907,6 +2944,379 @@ describe("TreeWatcher deferred delete snapshots", () => {
2907
2944
  watcher.dispose();
2908
2945
  fs.rmSync(hqRoot, { recursive: true, force: true });
2909
2946
  });
2947
+ // `deleteSnapshotEpochs` exists to let a newer revision of a path
2948
+ // invalidate a delete-snapshot capture that is still queued or running. A
2949
+ // long-lived runner touches hundreds of thousands of distinct paths, so a
2950
+ // key may live in that map only while such a capture is in flight; any
2951
+ // other write into it is a leak keyed by path.
2952
+ const settle = () => new Promise((resolve) => setImmediate(resolve));
2953
+ it("retires a superseded capture's epoch when that capture completes", async () => {
2954
+ const hqRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-watch-epoch-retire-"));
2955
+ const clock = new FakeClock();
2956
+ let resolveCapture;
2957
+ let observedCurrent = true;
2958
+ const watcher = new TreeWatcher({
2959
+ hqRoot,
2960
+ clock,
2961
+ debounceMs: 25,
2962
+ pathFilter: () => true,
2963
+ queueLocalDeleteSnapshots: async (_relative, _kind, isCurrent) => {
2964
+ await new Promise((resolve) => { resolveCapture = resolve; });
2965
+ observedCurrent = isCurrent();
2966
+ return [];
2967
+ },
2968
+ });
2969
+ try {
2970
+ const target = path.join(hqRoot, "recreated.md");
2971
+ watcher.handleEvent(target, "unlink");
2972
+ await Promise.resolve();
2973
+ expect(watcher.censusSizes().deleteSnapshotEpochs).toBe(1);
2974
+ // The newer revision invalidates the running capture but must keep the
2975
+ // marker until that capture has actually observed it.
2976
+ watcher.handleEvent(target, "add");
2977
+ expect(watcher.censusSizes().deleteSnapshotEpochs).toBe(1);
2978
+ resolveCapture();
2979
+ await settle();
2980
+ expect(observedCurrent).toBe(false);
2981
+ expect(watcher.censusSizes().deleteSnapshotEpochs).toBe(0);
2982
+ }
2983
+ finally {
2984
+ watcher.dispose();
2985
+ fs.rmSync(hqRoot, { recursive: true, force: true });
2986
+ }
2987
+ });
2988
+ it("never creates an epoch for a live event or for a synchronous capture", () => {
2989
+ const hqRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-watch-epoch-live-"));
2990
+ const clock = new FakeClock();
2991
+ const capture = vi.fn(() => []);
2992
+ const watcher = new TreeWatcher({
2993
+ hqRoot,
2994
+ clock,
2995
+ debounceMs: 25,
2996
+ pathFilter: () => true,
2997
+ captureLocalDeleteSnapshots: capture,
2998
+ });
2999
+ try {
3000
+ watcher.handleEvent(path.join(hqRoot, "added.md"), "add");
3001
+ watcher.handleEvent(path.join(hqRoot, "edited.md"), "change");
3002
+ watcher.handleEvent(path.join(hqRoot, "made"), "addDir");
3003
+ watcher.handleEvent(path.join(hqRoot, "gone.md"), "unlink");
3004
+ watcher.handleEvent(path.join(hqRoot, "gone-dir"), "unlinkDir");
3005
+ clock.advance(25);
3006
+ expect(capture).toHaveBeenCalledTimes(2);
3007
+ // A synchronous capture has already run by the time the event returns:
3008
+ // there is nothing left to invalidate, so there is nothing to remember.
3009
+ expect(watcher.censusSizes().deleteSnapshotEpochs).toBe(0);
3010
+ }
3011
+ finally {
3012
+ watcher.dispose();
3013
+ fs.rmSync(hqRoot, { recursive: true, force: true });
3014
+ }
3015
+ });
3016
+ it("shares one epoch across overlapping captures of a path and retires it with the last", async () => {
3017
+ const hqRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-watch-epoch-overlap-"));
3018
+ const clock = new FakeClock();
3019
+ const resolvers = [];
3020
+ const observed = [];
3021
+ const watcher = new TreeWatcher({
3022
+ hqRoot,
3023
+ clock,
3024
+ debounceMs: 25,
3025
+ pathFilter: () => true,
3026
+ queueLocalDeleteSnapshots: async (_relative, _kind, isCurrent) => {
3027
+ await new Promise((resolve) => { resolvers.push(resolve); });
3028
+ observed.push(isCurrent());
3029
+ return [];
3030
+ },
3031
+ });
3032
+ try {
3033
+ const target = path.join(hqRoot, "twice.md");
3034
+ watcher.handleEvent(target, "unlink");
3035
+ await Promise.resolve();
3036
+ watcher.handleEvent(target, "unlink"); // second delete in the window queues behind the first
3037
+ expect(watcher.censusSizes().deleteSnapshotEpochs).toBe(1);
3038
+ resolvers.shift()();
3039
+ await settle();
3040
+ // The first capture was superseded by the second; the second is still
3041
+ // queued, so the path keeps its marker.
3042
+ expect(observed).toEqual([false]);
3043
+ expect(watcher.censusSizes().deleteSnapshotEpochs).toBe(1);
3044
+ resolvers.shift()();
3045
+ await settle();
3046
+ expect(observed).toEqual([false, true]);
3047
+ expect(watcher.censusSizes().deleteSnapshotEpochs).toBe(0);
3048
+ }
3049
+ finally {
3050
+ watcher.dispose();
3051
+ fs.rmSync(hqRoot, { recursive: true, force: true });
3052
+ }
3053
+ });
3054
+ it("leaves no epoch for a path whose capture the full queue rejected", async () => {
3055
+ const hqRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-watch-epoch-full-"));
3056
+ const clock = new FakeClock();
3057
+ const resolvers = [];
3058
+ const observed = [];
3059
+ const watcher = new TreeWatcher({
3060
+ hqRoot,
3061
+ clock,
3062
+ debounceMs: 25,
3063
+ pathFilter: () => true,
3064
+ maxPendingPaths: 2,
3065
+ queueLocalDeleteSnapshots: async (relative, _kind, isCurrent) => {
3066
+ await new Promise((resolve) => { resolvers.push(resolve); });
3067
+ observed.push(`${relative}:${isCurrent()}`);
3068
+ return [];
3069
+ },
3070
+ });
3071
+ const consoleError = vi.spyOn(console, "error").mockImplementation(() => undefined);
3072
+ try {
3073
+ const a = path.join(hqRoot, "a.md");
3074
+ const b = path.join(hqRoot, "b.md");
3075
+ watcher.handleEvent(a, "unlink");
3076
+ await Promise.resolve();
3077
+ resolvers.shift()();
3078
+ await settle(); // a's capture is done; a is still pending in the window
3079
+ expect(observed).toEqual(["a.md:true"]);
3080
+ expect(watcher.censusSizes().deleteSnapshotEpochs).toBe(0);
3081
+ watcher.handleEvent(b, "unlink");
3082
+ watcher.handleEvent(b, "unlink"); // two captures queued for b: the queue is full
3083
+ // A third delete of `a` finds the queue full. Nothing is in flight for
3084
+ // `a`, so nothing may be recorded for it either.
3085
+ watcher.handleEvent(a, "unlink");
3086
+ expect(watcher.censusSizes().deleteSnapshotEpochs).toBe(1);
3087
+ // A full queue must still supersede a capture that IS in flight for the
3088
+ // path, exactly as it did before, and that path's marker still retires.
3089
+ watcher.handleEvent(b, "unlink");
3090
+ await settle(); // the first queued capture for b starts
3091
+ resolvers.shift()();
3092
+ await settle(); // ...and the second, queued behind it
3093
+ resolvers.shift()();
3094
+ await settle();
3095
+ expect(observed).toEqual(["a.md:true", "b.md:false", "b.md:false"]);
3096
+ expect(watcher.censusSizes().deleteSnapshotEpochs).toBe(0);
3097
+ }
3098
+ finally {
3099
+ consoleError.mockRestore();
3100
+ watcher.dispose();
3101
+ fs.rmSync(hqRoot, { recursive: true, force: true });
3102
+ }
3103
+ });
3104
+ });
3105
+ describe("TreeWatcher untracked delete drop", () => {
3106
+ // Atomic writers (`.name.<pid>.<random>.tmp` renamed into place, editor
3107
+ // swap files) create and remove a path within one debounce window. Such a
3108
+ // path has no journal row, so its unlink has nothing to delete remotely and
3109
+ // no revision to bind: queueing it only cost a delete-snapshot capture, a
3110
+ // pending-map slot, and a targeted push that found nothing on disk. On the
3111
+ // controller these were 370 of 380 agency watcher events per minute.
3112
+ function makeRoot() {
3113
+ return fs.mkdtempSync(path.join(os.tmpdir(), "hq-watch-untracked-"));
3114
+ }
3115
+ it("drops a file unlink that has no journal row before it reaches a batch", () => {
3116
+ const hqRoot = makeRoot();
3117
+ const clock = new FakeClock();
3118
+ const capture = vi.fn(() => []);
3119
+ const watcher = new TreeWatcher({
3120
+ hqRoot,
3121
+ clock,
3122
+ debounceMs: 25,
3123
+ pathFilter: () => true,
3124
+ captureLocalDeleteSnapshots: capture,
3125
+ isUntrackedDelete: (relativePath) => relativePath.endsWith(".tmp"),
3126
+ });
3127
+ const batches = [];
3128
+ watcher.onChange((_first, batch) => batches.push([...(batch?.paths.values() ?? [])]));
3129
+ try {
3130
+ watcher.handleEvent(path.join(hqRoot, "notes", ".draft.md.123.abc.tmp"), "unlink");
3131
+ watcher.handleEvent(path.join(hqRoot, "notes", "kept.md"), "unlink");
3132
+ clock.advance(25);
3133
+ expect(batches).toEqual([["notes/kept.md"]]);
3134
+ // The dropped path never paid for a delete-snapshot capture.
3135
+ expect(capture).toHaveBeenCalledTimes(1);
3136
+ expect(capture).toHaveBeenCalledWith("notes/kept.md", "unlink");
3137
+ expect(watcher.untrackedDeletesDropped()).toBe(1);
3138
+ // Neither path leaves an epoch behind: the kept unlink was captured
3139
+ // synchronously (nothing in flight to invalidate) and the dropped one
3140
+ // never had a capture at all.
3141
+ expect(watcher.censusSizes().deleteSnapshotEpochs).toBe(0);
3142
+ }
3143
+ finally {
3144
+ watcher.dispose();
3145
+ fs.rmSync(hqRoot, { recursive: true, force: true });
3146
+ }
3147
+ });
3148
+ it("leaves no delete-snapshot epoch behind for an atomic write cancelled inside its own window", () => {
3149
+ // Every agency writer saves through `.<name>.<pid>.<random>.tmp` and
3150
+ // renames it into place, so the watcher sees an `add` and then an
3151
+ // `unlink` of a name it will never see again. 370 of those a minute on
3152
+ // the controller: if each one left a key in a per-path map, the map
3153
+ // would grow by half a million randomised paths a day.
3154
+ const hqRoot = makeRoot();
3155
+ const clock = new FakeClock();
3156
+ const queue = vi.fn(async () => []);
3157
+ const watcher = new TreeWatcher({
3158
+ hqRoot,
3159
+ clock,
3160
+ debounceMs: 25,
3161
+ pathFilter: () => true,
3162
+ queueLocalDeleteSnapshots: queue,
3163
+ isUntrackedDelete: (relativePath) => relativePath.endsWith(".tmp"),
3164
+ });
3165
+ const changed = vi.fn();
3166
+ watcher.onChange(changed);
3167
+ try {
3168
+ for (let i = 0; i < 250; i++) {
3169
+ const temp = path.join(hqRoot, "workspace", "agency", `.ledger.json.${i}.${(i * 7919).toString(36)}.tmp`);
3170
+ watcher.handleEvent(temp, "add");
3171
+ watcher.handleEvent(temp, "unlink");
3172
+ }
3173
+ clock.advance(1_000);
3174
+ expect(queue).not.toHaveBeenCalled();
3175
+ expect(changed).not.toHaveBeenCalled();
3176
+ expect(watcher.untrackedDeletesDropped()).toBe(250);
3177
+ expect(watcher.pendingTimerCount()).toBe(0);
3178
+ expect(watcher.censusSizes()).toMatchObject({ deleteSnapshotEpochs: 0, knownKinds: 0 });
3179
+ }
3180
+ finally {
3181
+ watcher.dispose();
3182
+ fs.rmSync(hqRoot, { recursive: true, force: true });
3183
+ }
3184
+ });
3185
+ it("resolves a vanished rename to an unlink, purges the path's earlier queued add, and leaves no timer armed", () => {
3186
+ const hqRoot = makeRoot();
3187
+ const clock = new FakeClock();
3188
+ const seam = vi.fn((relativePath) => relativePath.endsWith(".tmp"));
3189
+ const watcher = new TreeWatcher({
3190
+ hqRoot,
3191
+ clock,
3192
+ debounceMs: 25,
3193
+ pathFilter: () => true,
3194
+ isUntrackedDelete: seam,
3195
+ });
3196
+ const changed = vi.fn();
3197
+ watcher.onChange(changed);
3198
+ try {
3199
+ const temp = path.join(hqRoot, "state.json.tmp");
3200
+ fs.writeFileSync(temp, "{}");
3201
+ watcher.handleEvent(temp, "rename"); // exists → add
3202
+ expect(watcher.pendingTimerCount()).toBe(1);
3203
+ fs.rmSync(temp);
3204
+ watcher.handleEvent(temp, "rename"); // ENOENT → unlink → untracked → dropped
3205
+ // The create and the delete cancelled out inside one window. Nothing is
3206
+ // left to emit, so the window closes without waking the push at all.
3207
+ expect(seam).toHaveBeenCalledWith("state.json.tmp");
3208
+ expect(watcher.pendingTimerCount()).toBe(0);
3209
+ clock.advance(1_000);
3210
+ expect(changed).not.toHaveBeenCalled();
3211
+ expect(watcher.untrackedDeletesDropped()).toBe(1);
3212
+ }
3213
+ finally {
3214
+ watcher.dispose();
3215
+ fs.rmSync(hqRoot, { recursive: true, force: true });
3216
+ }
3217
+ });
3218
+ it("keeps journaled unlinks and never consults the seam for live files or directory deletes", () => {
3219
+ const hqRoot = makeRoot();
3220
+ const clock = new FakeClock();
3221
+ const seam = vi.fn(() => false);
3222
+ const capture = vi.fn(() => []);
3223
+ const watcher = new TreeWatcher({
3224
+ hqRoot,
3225
+ clock,
3226
+ debounceMs: 25,
3227
+ pathFilter: () => true,
3228
+ captureLocalDeleteSnapshots: capture,
3229
+ isUntrackedDelete: seam,
3230
+ });
3231
+ const batches = [];
3232
+ watcher.onChange((_first, batch) => batches.push(batch?.paths ?? new Map()));
3233
+ try {
3234
+ const live = path.join(hqRoot, "live.md");
3235
+ fs.writeFileSync(live, "x");
3236
+ watcher.handleEvent(live, "add");
3237
+ // A directory with no row of its own may still cover journaled
3238
+ // descendants; only the capture's prefix scan can tell, so directory
3239
+ // deletes always go through.
3240
+ watcher.handleEvent(path.join(hqRoot, "gone-dir"), "unlinkDir");
3241
+ watcher.handleEvent(path.join(hqRoot, "journaled.md"), "unlink");
3242
+ clock.advance(25);
3243
+ expect(seam).toHaveBeenCalledTimes(1);
3244
+ expect(seam).toHaveBeenCalledWith("journaled.md");
3245
+ expect([...(batches[0]?.values() ?? [])].sort()).toEqual(["gone-dir", "journaled.md", "live.md"]);
3246
+ expect(capture).toHaveBeenCalledWith("gone-dir", "unlinkDir");
3247
+ expect(capture).toHaveBeenCalledWith("journaled.md", "unlink");
3248
+ expect(watcher.untrackedDeletesDropped()).toBe(0);
3249
+ }
3250
+ finally {
3251
+ watcher.dispose();
3252
+ fs.rmSync(hqRoot, { recursive: true, force: true });
3253
+ }
3254
+ });
3255
+ it("keeps the unlink when the seam throws", () => {
3256
+ const hqRoot = makeRoot();
3257
+ const clock = new FakeClock();
3258
+ const watcher = new TreeWatcher({
3259
+ hqRoot,
3260
+ clock,
3261
+ debounceMs: 25,
3262
+ pathFilter: () => true,
3263
+ isUntrackedDelete: () => {
3264
+ throw new Error("journal unavailable");
3265
+ },
3266
+ });
3267
+ const batches = [];
3268
+ watcher.onChange((_first, batch) => batches.push([...(batch?.paths.values() ?? [])]));
3269
+ const consoleError = vi.spyOn(console, "error").mockImplementation(() => undefined);
3270
+ try {
3271
+ expect(() => watcher.handleEvent(path.join(hqRoot, "maybe.md"), "unlink")).not.toThrow();
3272
+ clock.advance(25);
3273
+ // Dropping is an optimisation; keeping the event is the safe default.
3274
+ expect(batches).toEqual([["maybe.md"]]);
3275
+ expect(watcher.untrackedDeletesDropped()).toBe(0);
3276
+ }
3277
+ finally {
3278
+ consoleError.mockRestore();
3279
+ watcher.dispose();
3280
+ fs.rmSync(hqRoot, { recursive: true, force: true });
3281
+ }
3282
+ });
3283
+ it("a dropped unlink supersedes an in-flight queued capture for the same path", async () => {
3284
+ const hqRoot = makeRoot();
3285
+ const clock = new FakeClock();
3286
+ let untracked = false;
3287
+ let resolveCapture;
3288
+ let observedCurrent;
3289
+ const watcher = new TreeWatcher({
3290
+ hqRoot,
3291
+ clock,
3292
+ debounceMs: 25,
3293
+ pathFilter: () => true,
3294
+ isUntrackedDelete: () => untracked,
3295
+ queueLocalDeleteSnapshots: async (_relative, _kind, isCurrent) => {
3296
+ await new Promise((resolve) => { resolveCapture = resolve; });
3297
+ observedCurrent = isCurrent();
3298
+ return [];
3299
+ },
3300
+ });
3301
+ try {
3302
+ const target = path.join(hqRoot, "flip.md");
3303
+ watcher.handleEvent(target, "unlink"); // journal view cold: kept, capture queued
3304
+ await Promise.resolve();
3305
+ untracked = true;
3306
+ watcher.handleEvent(target, "unlink"); // journal view warm: no row → dropped
3307
+ resolveCapture();
3308
+ await Promise.resolve();
3309
+ // The queued capture must not bind a revision for a path the watcher
3310
+ // has since discarded.
3311
+ expect(observedCurrent).toBe(false);
3312
+ expect(watcher.pendingTimerCount()).toBe(0);
3313
+ expect(watcher.untrackedDeletesDropped()).toBe(1);
3314
+ }
3315
+ finally {
3316
+ watcher.dispose();
3317
+ fs.rmSync(hqRoot, { recursive: true, force: true });
3318
+ }
3319
+ });
2910
3320
  });
2911
3321
  // ---------------------------------------------------------------------------
2912
3322
  // Event-pass debounce configuration (HQ_SYNC_EVENT_DEBOUNCE_MS / _MAX_WAIT_MS)
@@ -3051,4 +3461,295 @@ describe("resolvePublishMinIntervalMs", () => {
3051
3461
  expect(resolvePublishMinIntervalMs({ [PUBLISH_MIN_INTERVAL_MS_ENV]: "1234.9" })).toBe(1234);
3052
3462
  });
3053
3463
  });
3464
+ /**
3465
+ * Linux folder-only backend.
3466
+ *
3467
+ * On Linux there is no recursive `fs.watch`, and chokidar's answer was one
3468
+ * inotify watch per directory PLUS one per file. On a real HQ root that was
3469
+ * ~74k directories and ~878k files — ~950k watches, ~16 KB each — while the
3470
+ * safety cap counted only the directories and so never fired. A directory
3471
+ * watch already reports content changes to the files directly inside it, so
3472
+ * the per-file watches bought nothing. These tests pin the replacement: the
3473
+ * scoped native backend driven with `recursiveWatches: false`, taking exactly
3474
+ * one shallow watch per in-scope directory and none per file.
3475
+ */
3476
+ describe("Linux folder-only native backend (startScopedRecursiveWatch, recursiveWatches: false)", () => {
3477
+ let root;
3478
+ const isLinux = process.platform === "linux";
3479
+ beforeEach(() => {
3480
+ root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), "folder-watch-")));
3481
+ });
3482
+ afterEach(() => {
3483
+ fs.rmSync(root, { recursive: true, force: true });
3484
+ });
3485
+ /** In-scope tree: root, docs, docs/deep, notes — 4 dirs, 8 files, plus an excluded node_modules. */
3486
+ function seedTree() {
3487
+ const dirs = [
3488
+ path.join(root, "docs"),
3489
+ path.join(root, "docs", "deep"),
3490
+ path.join(root, "notes"),
3491
+ ];
3492
+ for (const d of dirs)
3493
+ fs.mkdirSync(d, { recursive: true });
3494
+ const files = [];
3495
+ for (const d of [root, ...dirs]) {
3496
+ for (const n of ["one.md", "two.md"]) {
3497
+ const f = path.join(d, n);
3498
+ fs.writeFileSync(f, "x");
3499
+ files.push(f);
3500
+ }
3501
+ }
3502
+ const nm = path.join(root, "docs", "node_modules", "pkg");
3503
+ fs.mkdirSync(nm, { recursive: true });
3504
+ fs.writeFileSync(path.join(nm, "index.js"), "1");
3505
+ return { inScopeDirs: [root, ...dirs], files };
3506
+ }
3507
+ /** Count this process's live inotify watch descriptors (Linux only). */
3508
+ function inotifyWatchDescriptors() {
3509
+ let total = 0;
3510
+ for (const fd of fs.readdirSync("/proc/self/fdinfo")) {
3511
+ try {
3512
+ const info = fs.readFileSync(path.join("/proc/self/fdinfo", fd), "utf8");
3513
+ total += (info.match(/^inotify wd:/gm) ?? []).length;
3514
+ }
3515
+ catch {
3516
+ /* fd closed between readdir and read */
3517
+ }
3518
+ }
3519
+ return total;
3520
+ }
3521
+ async function waitFor(check, ms = 4000) {
3522
+ const deadline = Date.now() + ms;
3523
+ while (Date.now() < deadline) {
3524
+ if (check())
3525
+ return;
3526
+ await new Promise((r) => setTimeout(r, 25));
3527
+ }
3528
+ expect(check()).toBe(true);
3529
+ }
3530
+ function startFolderOnly(opts = {}) {
3531
+ const shouldEmit = createWatchPathFilter(root, false);
3532
+ return startScopedRecursiveWatch(root, shouldEmit, opts.onEvent ?? (() => { }), opts.onError ?? ((err) => { throw err; }), undefined, {
3533
+ recursiveWatches: false,
3534
+ maxWatchedPaths: opts.maxWatchedPaths,
3535
+ onWatchBudgetExceeded: opts.onWatchBudgetExceeded,
3536
+ listChildDirs: opts.listChildDirs,
3537
+ });
3538
+ }
3539
+ it("takes exactly one watch per in-scope directory and none per file", () => {
3540
+ const { inScopeDirs } = seedTree();
3541
+ const before = isLinux ? inotifyWatchDescriptors() : 0;
3542
+ const backend = startFolderOnly();
3543
+ try {
3544
+ expect(backend.mode).toBe("native");
3545
+ expect(backend.attachFailures).toBe(0);
3546
+ // 4 in-scope directories; 8 in-scope files and an excluded subtree add nothing.
3547
+ expect(backend.watchedPathCount()).toBe(inScopeDirs.length);
3548
+ if (isLinux) {
3549
+ // Measured immediately, before any drain window: a whole-tree
3550
+ // bootstrap watch would show up here as extra descriptors.
3551
+ expect(inotifyWatchDescriptors() - before).toBe(inScopeDirs.length);
3552
+ }
3553
+ }
3554
+ finally {
3555
+ backend.close();
3556
+ }
3557
+ if (isLinux)
3558
+ expect(inotifyWatchDescriptors()).toBe(before);
3559
+ });
3560
+ it("reports a content change to a file inside a watched folder without a file watch", async () => {
3561
+ const { files } = seedTree();
3562
+ const seen = [];
3563
+ const backend = startFolderOnly({ onEvent: (p) => seen.push(p) });
3564
+ try {
3565
+ await new Promise((r) => setTimeout(r, 150));
3566
+ const target = files.find((f) => f.includes(path.join("docs", "deep")));
3567
+ fs.appendFileSync(target, "more");
3568
+ await waitFor(() => seen.includes(target));
3569
+ }
3570
+ finally {
3571
+ backend.close();
3572
+ }
3573
+ });
3574
+ it("attaches a folder created after start, then reports files written inside it", async () => {
3575
+ seedTree();
3576
+ const seen = [];
3577
+ const backend = startFolderOnly({ onEvent: (p) => seen.push(p) });
3578
+ try {
3579
+ await new Promise((r) => setTimeout(r, 150));
3580
+ const before = backend.watchedPathCount();
3581
+ const created = path.join(root, "notes", "later");
3582
+ fs.mkdirSync(created);
3583
+ await waitFor(() => backend.watchedPathCount() === before + 1);
3584
+ const file = path.join(created, "fresh.md");
3585
+ fs.writeFileSync(file, "hello");
3586
+ await waitFor(() => seen.includes(file));
3587
+ }
3588
+ finally {
3589
+ backend.close();
3590
+ }
3591
+ });
3592
+ it("scans a folder that already holds files when it attaches, so nothing arrives silently", async () => {
3593
+ seedTree();
3594
+ const seen = [];
3595
+ const backend = startFolderOnly({ onEvent: (p) => seen.push(p) });
3596
+ try {
3597
+ await new Promise((r) => setTimeout(r, 150));
3598
+ // Build the subtree OUTSIDE the watched root, then move it in with one
3599
+ // rename: the folder watch only ever sees the directory appear, never
3600
+ // the files inside it. Chokidar walked such a directory on addDir;
3601
+ // the folder-only backend must do the same.
3602
+ const staging = fs.mkdtempSync(path.join(os.tmpdir(), "folder-watch-stage-"));
3603
+ fs.mkdirSync(path.join(staging, "inner"));
3604
+ fs.writeFileSync(path.join(staging, "a.md"), "a");
3605
+ fs.writeFileSync(path.join(staging, "inner", "b.md"), "b");
3606
+ const dest = path.join(root, "docs", "moved");
3607
+ fs.renameSync(staging, dest);
3608
+ await waitFor(() => seen.includes(path.join(dest, "a.md")) &&
3609
+ seen.includes(path.join(dest, "inner", "b.md")));
3610
+ expect(backend.watchedPathCount()).toBe(4 + 2);
3611
+ }
3612
+ finally {
3613
+ backend.close();
3614
+ }
3615
+ });
3616
+ it("re-attaches when a watched folder is swapped for a new one at the same path (Linux inode change)", async () => {
3617
+ seedTree();
3618
+ const seen = [];
3619
+ const backend = startFolderOnly({ onEvent: (p) => seen.push(p) });
3620
+ try {
3621
+ await new Promise((r) => setTimeout(r, 150));
3622
+ expect(backend.watchedPathCount()).toBe(4);
3623
+ // Atomic swap: the old `docs` moves out of the tree and a replacement
3624
+ // (built outside, so its creation is never observed) lands at the same
3625
+ // pathname — both renames complete before any watch callback runs. On
3626
+ // Linux the old handle follows the moved-away INODE, so without an
3627
+ // identity check the backend would keep it, consider `docs` covered,
3628
+ // and never hear another event from the replacement subtree.
3629
+ const staging = fs.mkdtempSync(path.join(os.tmpdir(), "folder-watch-swap-"));
3630
+ fs.mkdirSync(path.join(staging, "deep"));
3631
+ fs.writeFileSync(path.join(staging, "a.md"), "a");
3632
+ fs.writeFileSync(path.join(staging, "deep", "b.md"), "b");
3633
+ const parked = fs.mkdtempSync(path.join(os.tmpdir(), "folder-watch-parked-"));
3634
+ const docs = path.join(root, "docs");
3635
+ fs.renameSync(docs, path.join(parked, "docs"));
3636
+ fs.renameSync(staging, docs);
3637
+ // The replacement's existing files are announced, exactly like a
3638
+ // populated folder moved in from outside.
3639
+ await waitFor(() => seen.includes(path.join(docs, "a.md")) &&
3640
+ seen.includes(path.join(docs, "deep", "b.md")));
3641
+ // A later write inside the replacement is reported: the new inode is
3642
+ // watched, and the stale handles (docs + docs/deep) are gone — still
3643
+ // root, docs, docs/deep, notes.
3644
+ const after = path.join(docs, "deep", "after.md");
3645
+ fs.writeFileSync(after, "after");
3646
+ await waitFor(() => seen.includes(after));
3647
+ expect(backend.watchedPathCount()).toBe(4);
3648
+ // The moved-away tree must not keep reporting under its OLD path.
3649
+ seen.length = 0;
3650
+ fs.writeFileSync(path.join(parked, "docs", "stale.md"), "stale");
3651
+ await new Promise((r) => setTimeout(r, 300));
3652
+ expect(seen.filter((p) => p.startsWith(docs + path.sep))).toEqual([]);
3653
+ fs.rmSync(parked, { recursive: true, force: true });
3654
+ }
3655
+ finally {
3656
+ backend.close();
3657
+ }
3658
+ });
3659
+ it("covers a folder created after its parent was listed but before the plan attached (walk/attach race)", async () => {
3660
+ seedTree();
3661
+ const seen = [];
3662
+ const late = path.join(root, "notes", "late");
3663
+ // The plan walk lists `notes`, then — before any watch existed on the
3664
+ // old code path — `notes/late` appears. The snapshot plan never holds
3665
+ // it, and a shallow watch on `notes` attached only after the whole walk
3666
+ // would never have seen it appear. On a real HQ root the walk takes
3667
+ // seconds; agents create directories the whole time.
3668
+ const listChildDirs = (dir) => {
3669
+ const children = fs
3670
+ .readdirSync(dir, { withFileTypes: true })
3671
+ .filter((e) => e.isDirectory())
3672
+ .map((e) => path.join(dir, e.name));
3673
+ if (dir === path.join(root, "notes"))
3674
+ fs.mkdirSync(late);
3675
+ return children;
3676
+ };
3677
+ const backend = startFolderOnly({ onEvent: (p) => seen.push(p), listChildDirs });
3678
+ try {
3679
+ // root, docs, docs/deep, notes — plus `late`, picked up by the live
3680
+ // watch on `notes` rather than by the plan.
3681
+ await waitFor(() => backend.watchedPathCount() === 5);
3682
+ const file = path.join(late, "inside.md");
3683
+ fs.writeFileSync(file, "x");
3684
+ await waitFor(() => seen.includes(file));
3685
+ }
3686
+ finally {
3687
+ backend.close();
3688
+ }
3689
+ });
3690
+ it("releases every watch beneath a deleted folder", async () => {
3691
+ seedTree();
3692
+ const backend = startFolderOnly();
3693
+ try {
3694
+ await new Promise((r) => setTimeout(r, 150));
3695
+ expect(backend.watchedPathCount()).toBe(4);
3696
+ fs.rmSync(path.join(root, "docs"), { recursive: true, force: true });
3697
+ // docs and docs/deep both go; root and notes remain.
3698
+ await waitFor(() => backend.watchedPathCount() === 2);
3699
+ if (isLinux) {
3700
+ await waitFor(() => inotifyWatchDescriptors() <= 2);
3701
+ }
3702
+ }
3703
+ finally {
3704
+ backend.close();
3705
+ }
3706
+ });
3707
+ it("stops attaching at the budget and reports the exhaustion exactly once, counting real watches", () => {
3708
+ seedTree();
3709
+ const exceeded = vi.fn();
3710
+ const backend = startFolderOnly({
3711
+ maxWatchedPaths: 2,
3712
+ onWatchBudgetExceeded: exceeded,
3713
+ });
3714
+ try {
3715
+ expect(backend.watchedPathCount()).toBe(2);
3716
+ expect(exceeded).toHaveBeenCalledTimes(1);
3717
+ expect(exceeded.mock.calls[0][0]).toMatchObject({
3718
+ watchedPaths: 2,
3719
+ maxWatchedPaths: 2,
3720
+ });
3721
+ expect(typeof exceeded.mock.calls[0][0].offendingPath).toBe("string");
3722
+ }
3723
+ finally {
3724
+ backend.close();
3725
+ }
3726
+ });
3727
+ it("selects the folder-only native backend on linux and leaves darwin/win32 on recursive native", () => {
3728
+ expect(selectTreeWatchBackend("linux", false)).toBe("native-shallow");
3729
+ expect(selectTreeWatchBackend("darwin", false)).toBe("native-recursive");
3730
+ expect(selectTreeWatchBackend("win32", false)).toBe("native-recursive");
3731
+ expect(selectTreeWatchBackend("freebsd", false)).toBe("chokidar");
3732
+ expect(selectTreeWatchBackend("linux", true)).toBe("polling");
3733
+ expect(selectTreeWatchBackend("darwin", true)).toBe("polling");
3734
+ });
3735
+ it("TreeWatcher on linux starts natively with one watch per directory (no chokidar, no file watches)", async () => {
3736
+ if (!isLinux)
3737
+ return;
3738
+ const { inScopeDirs } = seedTree();
3739
+ const before = inotifyWatchDescriptors();
3740
+ const w = new TreeWatcher({ hqRoot: root, debounceMs: 50 });
3741
+ const changed = vi.fn();
3742
+ w.onChange(changed);
3743
+ w.start();
3744
+ try {
3745
+ expect(w.watchMode()).toBe("native");
3746
+ expect(inotifyWatchDescriptors() - before).toBe(inScopeDirs.length);
3747
+ fs.writeFileSync(path.join(root, "notes", "new.md"), "hi");
3748
+ await waitFor(() => changed.mock.calls.length > 0);
3749
+ }
3750
+ finally {
3751
+ w.dispose();
3752
+ }
3753
+ });
3754
+ });
3054
3755
  //# sourceMappingURL=watcher.test.js.map