@indigoai-us/hq-cloud 6.14.35 → 6.14.37

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cloud",
-  "version": "6.14.35",
+  "version": "6.14.37",
   "description": "HQ by Indigo cloud sync engine — bidirectional S3 sync for mobile access",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

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

@@ -183,15 +183,20 @@ export async function executeCompanyFanout(options: {
           ...(event.errorCode ? { errorCode: event.errorCode } : {}),
         });
       } else if (event.type === "skip-junk-key-spelling") {
-        // Deliberate skip: forwarded for visibility, NEVER pushed into
-        // errors[] (policy hq-sync-deliberate-skip-not-fatal-error-exit2 —
-        // a benign recurring skip must not gate exit 2 / Sentry alerts).
         options.emit({
           type: "skip-junk-key-spelling",
           company: companyLabel,
           path: event.path,
           journaledKey: event.journaledKey,
         });
+      } else if (event.type === "not-shipped") {
+        options.emit({
+          type: "not-shipped",
+          company: companyLabel,
+          reason: event.reason,
+          count: event.count,
+          samplePaths: event.samplePaths,
+        });
       }
     };
 
@@ -208,6 +213,8 @@ export async function executeCompanyFanout(options: {
         filesExcludedByPolicy: 0,
         filesExcludedByScope: 0,
         filesExcludedByIgnore: 0,
+        unreachablePaths: [],
+        linkedSubtreesNotShipped: [],
         conflictPaths: [],
         aborted: false,
       };
@@ -288,6 +295,15 @@ export async function executeCompanyFanout(options: {
           skipUnchanged: true,
           propagateDeletes: true,
           propagateDeletePolicy: options.resolveDeletePolicy(),
+          // `pushPaths` are INTERNAL walk roots (the company folder / the
+          // personal-vault dirs), never user input, so an unreachable entry
+          // here is a benign race — a directory removed between the scan and
+          // the push — and must not fail an unattended background sync. Record
+          // + report it (`not-shipped` event, `ShareResult.unreachablePaths`)
+          // and carry on. The interactive `hq sync push <path>` keeps the
+          // default "error" policy, which is where a user-typed path that
+          // silently ships nothing is a real bug (feedback_a51cb63d ask #2).
+          unreachablePathPolicy: "warn",
           onEvent: tagAndEmit,
           ...(options.uploadAuthor ? { author: options.uploadAuthor } : {}),
           ...(target.personalMode !== undefined

package/src/bin/sync-runner-watch-loop.ts

@@ -1006,6 +1006,15 @@ export async function runWatchLoop(
     while (!stopped) {
       pollTick++;
       const pending = takePendingWatcherChange();
+      // The quarantine is scoped to the delete episode it refused, and only
+      // the roots already refused when this batch was taken belong to it.
+      // Snapshot them here rather than clearing the whole set after the pass:
+      // the pass is awaited, so a bulk removal observed while it runs adds its
+      // root afterwards and its snapshots ride the NEXT batch. Clearing
+      // unconditionally would drop that root before `prepareWatcherChanges`
+      // ever sees the batch, re-stamping the revoked descendant intents and
+      // handing the engine exactly the bulk delete the quarantine refused.
+      const drainedQuarantineRoots = new Set(quarantinedDeleteRoots);
       const shouldRunFull =
         pollTick === 1 ||
         pending.bare ||
@@ -1014,11 +1023,12 @@ export async function runWatchLoop(
       const result = shouldRunFull
         ? await runGuarded(passArgv)
         : await runScopedDrain(pending.batch);
-      // The quarantine is scoped to the delete episode it refused. The batch
-      // carrying that episode has now been prepared and pushed, so a later
+      // 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.
-      quarantinedDeleteRoots.clear();
+      for (const root of drainedQuarantineRoots) {
+        quarantinedDeleteRoots.delete(root);
+      }
       const exitCode = passExitCode(result);
       if (exitCode === runtime.authRequiredPassExit) {
         // The pass already emitted auth-error. Stop the unattended loop but

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

@@ -157,6 +157,8 @@ function defaultShareResult(overrides: Partial<ShareResult> = {}): ShareResult {
     filesExcludedByPolicy: 0,
     filesExcludedByScope: 0,
     filesExcludedByIgnore: 0,
+    unreachablePaths: [],
+    linkedSubtreesNotShipped: [],
     conflictPaths: [],
     aborted: false,
     ...overrides,
@@ -7548,7 +7550,11 @@ describe("US-002 — manifest reconciliation wiring", () => {
 describe("watcher delete intents without pre-seeded authorization", () => {
   function startDeleteHarness(
     keys: string[],
-    options: { gateInitialPull?: boolean } = {},
+    options: {
+      gateInitialPull?: boolean;
+      onPass?: (argv: string[]) => Promise<void> | void;
+      direction?: "both" | "push";
+    } = {},
   ) {
     const hqRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-watch-delete-"));
     const companyRoot = path.join(hqRoot, "companies", "indigo");
@@ -7591,6 +7597,9 @@ describe("watcher delete intents without pre-seeded authorization", () => {
     });
     let initialPullGated = options.gateInitialPull === true;
     const runPass = vi.fn(async (argv: string[]) => {
+      // Lets a test hold a pass mid-flight and act while the loop is awaiting
+      // it, which is where producer-side state that outlives a pass is decided.
+      await options.onPass?.(argv);
       const direction = argv[argv.indexOf("--direction") + 1];
       if (direction === "push") {
         const journal = readJournal("indigo");
@@ -7665,7 +7674,8 @@ describe("watcher delete intents without pre-seeded authorization", () => {
     });
     const loop = runRunnerWithLoop(
       [
-        "--companies", "--watch", "--event-push", "--direction", "both",
+        "--companies", "--watch", "--event-push",
+        "--direction", options.direction ?? "both",
         "--hq-root", hqRoot, "--poll-remote-ms", "60000",
       ],
       {
@@ -8169,6 +8179,99 @@ describe("watcher delete intents without pre-seeded authorization", () => {
     await stopHarness(h);
   });
 
+  // A pass is awaited, so a bulk removal observed while one is in flight
+  // registers its quarantine root only after that pass's batch was taken — its
+  // own snapshots ride the NEXT batch. Expiring the whole set once the pass
+  // returns would drop the root before `prepareWatcherChanges` ever sees that
+  // batch, re-stamping the revoked descendant intents and handing the engine
+  // the bulk delete the quarantine refused (remotely deleting the subtree under
+  // HQ_SYNC_DELETE_POLICY=all).
+  it("a bulk removal observed during an in-flight pass keeps its quarantine", async () => {
+    const keys = Array.from(
+      { length: 12 }, (_, i) => `knowledge/moved/f-${i}.md`,
+    );
+    let releaseGatedPush = () => {};
+    const gatedPush = new Promise<void>((resolve) => {
+      releaseGatedPush = resolve;
+    });
+    let gateArmed = false;
+    let gateReached = false;
+    // Push-only: a pull would restore the quarantined subtree (the documented
+    // recovery for an intent-less disappearance) before the batch carrying the
+    // episode is prepared, masking whether the refusal itself survived.
+    const h = startDeleteHarness([...keys, "knowledge/other.md"], {
+      direction: "push",
+      onPass: async (_argv) => {
+        if (!gateArmed) return;
+        gateArmed = false;
+        gateReached = true;
+        await gatedPush;
+      },
+    });
+    await settle();
+    const intentCount = () =>
+      Object.values(readJournal("indigo").files).filter(
+        (entry) => entry.localDeleteIntent,
+      ).length;
+
+    // An unrelated edit drains as a scoped push, which then blocks on the gate
+    // with its batch already taken from the pending buffer.
+    gateArmed = true;
+    const otherPath = path.join(h.companyRoot, "knowledge/other.md");
+    fs.writeFileSync(otherPath, "edited");
+    h.watcher.emit("companies/indigo/knowledge/other.md", {
+      paths: new Map([[otherPath, "companies/indigo/knowledge/other.md"]]),
+    } as TreeChangeBatch);
+    h.tick();
+    await settle();
+    expect(gateReached).toBe(true);
+
+    // The whole subtree disappears while that pass is still in flight.
+    const childChanges = new Map<string, TreeChange>();
+    for (const key of keys) {
+      const absolutePath = path.join(h.companyRoot, key);
+      fs.unlinkSync(absolutePath);
+      childChanges.set(absolutePath, {
+        kind: "unlink",
+        deleteSnapshots: h.capture()(`companies/indigo/${key}`, "unlink"),
+      });
+    }
+    const subtree = path.join(h.companyRoot, "knowledge/moved");
+    fs.rmSync(subtree, { recursive: true, force: true });
+    const dirSnapshots = h.capture()(
+      "companies/indigo/knowledge/moved", "unlinkDir",
+    );
+    expect(dirSnapshots).toHaveLength(0);
+    expect(intentCount()).toBe(0);
+    h.watcher.emit("companies/indigo/knowledge/moved", {
+      paths: new Map<string, string>([
+        ...keys.map(
+          (key) =>
+            [
+              path.join(h.companyRoot, key),
+              `companies/indigo/${key}`,
+            ] as [string, string],
+        ),
+        [subtree, "companies/indigo/knowledge/moved"],
+      ]),
+      changes: new Map<string, TreeChange>([
+        ...childChanges,
+        [subtree, { kind: "unlinkDir", deleteSnapshots: dirSnapshots }],
+      ]),
+    } as TreeChangeBatch);
+
+    // Completing the overlapped pass must not expire the refusal recorded
+    // during it: the next drain prepares the batch that carries the episode.
+    releaseGatedPush();
+    await settle();
+    h.tick();
+    await settle();
+
+    expect(intentCount()).toBe(0);
+    for (const key of keys) expect(h.remote.has(key)).toBe(true);
+    await stopHarness(h);
+  });
+
   it("HQ_SYNC_DELETE_BULK_OVERRIDE=1 lets a whole-shard unlinkDir propagate", async () => {
     process.env.HQ_SYNC_DELETE_BULK_OVERRIDE = "1";
     try {

package/src/bin/sync-runner.ts

@@ -402,6 +402,10 @@ export type RunnerEvent =
       Extract<SyncProgressEvent, { type: "skip-junk-key-spelling" }>,
       "type"
     >)
+  | ({ type: "not-shipped"; company: string } & Omit<
+      Extract<SyncProgressEvent, { type: "not-shipped" }>,
+      "type"
+    >)
   | ({
       type: "complete";
       company: string;