@indigoai-us/hq-cloud 6.14.7 → 6.14.9

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

@@ -1,4 +1,5 @@
 import * as path from "path";
+import { inventoryManagedSnapshots } from "../backup-prune.js";
 import { VaultClient } from "../index.js";
 import { pickCanonicalPersonEntity } from "../vault-client.js";
 import {
@@ -98,6 +99,15 @@ export async function runWatchLoop(
   const eventPush = argv.includes("--event-push");
   const companiesMode = argv.includes("--companies");
   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
+  // the explicitly-gated apply surface.
+  let nextBackupPruneAt = Date.now() + 60_000;
+  const runBackupPrune = deps.runBackupPrune ?? (async (root: string) => {
+    const backupRoot = path.join(process.env.HOME ?? "", ".hq", "backups");
+    const plan = inventoryManagedSnapshots(backupRoot, root, (m) => { try { process.kill(m.creatorPid, 0); return true; } catch { return false; } });
+    process.stderr.write(`hq-sync-runner: backup retention dry-run — ${plan.candidates.length} candidate(s), ${plan.protected.length} protected\n`);
+  });
 
   const passArgv = argv.filter((a, i) => {
     if (a === "--watch") return false;
@@ -510,6 +520,14 @@ export async function runWatchLoop(
       } else if (result !== 0) {
         return result;
       }
+      if (Date.now() >= nextBackupPruneAt) {
+        // Advance before invoking: a failed/unavailable backstop cannot become
+        // an every-tick retry loop. It is diagnostic only and never restarts
+        // the sync daemon.
+        nextBackupPruneAt = Date.now() + 24 * 60 * 60 * 1000;
+        try { await runBackupPrune(hqRoot); }
+        catch (error) { process.stderr.write(`hq-sync-runner: backup retention dry-run failed — ${error instanceof Error ? error.message : String(error)}\n`); }
+      }
       await Promise.race([sleep(pollMs), stoppedSignal]);
     }
     return 0;

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

@@ -47,7 +47,7 @@ import type {
   PendingInviteByEmail,
   TelemetryEventsBatch,
 } from "../vault-client.js";
-import { VaultAuthError } from "../vault-client.js";
+import { VaultAuthError, VaultNotFoundError } from "../vault-client.js";
 import type { PushEvent } from "../sync/push-event.js";
 
 // ---------------------------------------------------------------------------
@@ -219,6 +219,7 @@ function makeDeps(overrides: Partial<RunnerDeps> = {}): TestDeps {
       embedded: false,
       pendingDirty: false,
     })),
+    reconcileManifest: vi.fn().mockResolvedValue(undefined),
     ...overrides,
     stdout,
     stderr,
@@ -926,6 +927,86 @@ describe("fanout-plan", () => {
     expect(plan.companies).toEqual([{ uid: "cmp_ghost", slug: "cmp_ghost" }]);
   });
 
+  it("skips a ghost membership whose entity is gone so it cannot force exit 2", async () => {
+    const sync = vi.fn().mockResolvedValue(defaultSyncResult());
+    const deps = makeDeps({
+      createVaultClient: () =>
+        makeVaultStub({
+          memberships: [
+            { companyUid: "cmp_live" },
+            { companyUid: "cmp_ghost" },
+          ],
+          entityGet: (uid: string) => {
+            if (uid === "cmp_ghost") {
+              return Promise.reject(new VaultNotFoundError("company deleted"));
+            }
+            return Promise.resolve({
+              uid,
+              slug: "live",
+              type: "company",
+              status: "active",
+              createdAt: "2026-01-01T00:00:00Z",
+            });
+          },
+        }),
+      sync,
+    });
+
+    const code = await runRunner(["--companies"], deps);
+
+    expect(code).toBe(0);
+    expect(sync).toHaveBeenCalledTimes(1);
+    expect(sync).toHaveBeenCalledWith(
+      expect.objectContaining({ company: "cmp_live" }),
+    );
+    const plan = deps.stdout
+      .events()
+      .find((e) => e.type === "fanout-plan") as Extract<
+      RunnerEvent,
+      { type: "fanout-plan" }
+    >;
+    expect(plan.companies).toEqual([{ uid: "cmp_live", slug: "live" }]);
+  });
+
+  it("reconciles after the personal leg completes", async () => {
+    const order: string[] = [];
+    const deps = makeDeps({
+      createVaultClient: () =>
+        makeVaultStub({
+          memberships: [{ companyUid: "cmp_acme" }],
+          entityGet: (uid: string) =>
+            Promise.resolve({
+              uid,
+              slug: "acme",
+              type: "company",
+              status: "active",
+              createdAt: "2026-01-01T00:00:00Z",
+            }),
+          listPersons: () =>
+            Promise.resolve([
+              {
+                uid: "prs_me",
+                slug: "me",
+                type: "person",
+                status: "active",
+                bucketName: "hq-vault-prs-me",
+                createdAt: "2026-01-01T00:00:00Z",
+              } as EntityInfo,
+            ]),
+        }),
+      sync: vi.fn().mockImplementation(async (options: SyncOptions) => {
+        order.push(options.personalMode === true ? "personal" : "company");
+        return defaultSyncResult();
+      }),
+      reconcileManifest: vi.fn().mockImplementation(async () => {
+        order.push("reconcile");
+      }),
+    });
+
+    expect(await runRunner(["--companies"], deps)).toBe(0);
+    expect(order).toEqual(["company", "personal", "reconcile"]);
+  });
+
   it("includes entity.name on plan entries when available", async () => {
     const deps = makeDeps({
       createVaultClient: () =>

package/src/bin/sync-runner.ts

@@ -139,6 +139,10 @@ import {
   emitFanoutPlan,
   resolveMembershipsForRun,
 } from "./sync-runner-planning.js";
+import {
+  reconcileCompanyManifest,
+  type ManifestReconcileOptions,
+} from "../manifest-reconcile.js";
 import { executeCompanyFanout } from "./sync-runner-company.js";
 import { rollupAllComplete } from "./sync-runner-rollup.js";
 import { emitTelemetry } from "./sync-runner-telemetry.js";
@@ -351,6 +355,10 @@ export type RunnerEvent =
   | { type: "new-files"; company: string; files: Array<{ path: string; bytes: number; addedBy: string | null }> }
   | { type: "scope-excluded"; company: string; count: number; samplePaths: string[] }
   | { type: "ignore-excluded"; company: string; count: number; totalExcluded: number; samplePaths: string[] }
+  | ({ type: "skip-invalid-scoped-key"; company: string } & Omit<
+      Extract<SyncProgressEvent, { type: "skip-invalid-scoped-key" }>,
+      "type"
+    >)
   | ({
       type: "complete";
       company: string;
@@ -603,6 +611,14 @@ export interface RunnerDeps {
     hqRoot: string,
     options: QmdReindexOptions,
   ) => ReturnType<typeof reindexAfterSync>;
+  /**
+   * Merge successfully pulled cloud companies into the local manifest after
+   * the complete fanout. Injectable so runner tests do not touch a developer's
+   * HQ root.
+   */
+  reconcileManifest?: (
+    options: ManifestReconcileOptions,
+  ) => Promise<void>;
   /** Internal: set when runRunner is invoked under the per-root operation lock. */
   operationLockAlreadyHeld?: boolean;
   /** Share function (push phase). Defaults to `cli/share.share`. */
@@ -1311,6 +1327,33 @@ export async function runRunner(
   const { errors, allConflicts, meaningfulOutcomeCount } = fanout;
   const rollup = rollupAllComplete(plan, fanout.stateByCompany);
 
+  // The personal-vault target runs last and can pull an older copy of the
+  // manifest. Reconcile only after the entire pull fanout has settled so the
+  // successfully materialized cloud directories restore their own entries.
+  if (parsed.direction !== "push") {
+    try {
+      const completedCompanySlugs = new Set(
+        Array.from(fanout.stateByCompany.entries())
+          .filter(([, state]) => state.status === "complete")
+          .map(([slug]) => slug),
+      );
+      await (deps.reconcileManifest ?? reconcileCompanyManifest)({
+        hqRoot: parsed.hqRoot,
+        targets: plan,
+        completedCompanySlugs,
+        getEntity: client.entity.get,
+      });
+    } catch (err) {
+      reportDiagnostic({
+        component: "manifest-reconcile",
+        event: "runner.manifest_reconcile.failed",
+        message: "post-fanout manifest reconciliation failed",
+        err,
+        context: { hqRoot: parsed.hqRoot },
+      });
+    }
+  }
+
   if (rollup.needsReindex) {
     try {
       const reindexOptions = {
@@ -1649,6 +1692,8 @@ export interface RunnerLoopDeps {
    * `deps` and forwards just the argv to `runRunner`.
    */
   runPass?: (passArgv: string[]) => Promise<number>;
+  /** Stage-0 backup retention backstop: a dry-run only, never a sync-tick action. */
+  runBackupPrune?: (hqRoot: string) => Promise<void>;
   /**
    * Clock seam for the event-push watcher's debounce window. Defaults to
    * {@link systemClock}; tests inject a `FakeClock` to advance the window

package/src/cli/rescue-classify-ordering.test.ts

@@ -369,4 +369,125 @@ exec ${JSON.stringify(realGit)} "$@"
     expect(lexists(link)).toBe(true);
     expect(fs.existsSync(path.join(hqRoot, "core/a.md"))).toBe(true);
   });
+
+  it("fails with a typed state-change error when reindex replaces a classified symlink before apply", () => {
+    const hqRoot = makeHqRoot();
+    const target = path.join(hqRoot, "personal/skills/foreman/tests");
+    fs.mkdirSync(target, { recursive: true });
+    const link = path.join(hqRoot, ".claude/skills/personal:foreman/tests");
+    fs.mkdirSync(path.dirname(link), { recursive: true });
+    fs.symlinkSync("../../../personal/skills/foreman/tests", link);
+
+    const args = [
+      "--hq-root", hqRoot,
+      "--source", "test/repo",
+      "--ref", "main",
+      "--floor-sha", floorSha,
+      "--yes",
+      "--no-backup",
+    ];
+    const r = runRescueCapture(args, {
+      ...baseEnv,
+      HQ_RESCUE_FAULT_BEFORE_APPLY_REL: ".claude/skills/personal:foreman/tests",
+      HQ_RESCUE_FAULT_BEFORE_APPLY_KIND: "directory",
+    });
+    const out = `${r.stdout}\n${r.stderr}\n${String(r.threw ?? "")}`;
+
+    expect(r.threw, out).toBeInstanceOf(Error);
+    expect(out).toContain("changed after classification");
+    expect(out).toContain("expected symlink, found directory");
+    expect(out).not.toContain("EISDIR");
+    expect(fs.readFileSync(path.join(hqRoot, "core/a.md"), "utf-8")).toBe("v1\n");
+  });
+
+  it("keeps the full default wipe set out of worktrees and omits transient build state from the snapshot", () => {
+    const hqRoot = makeHqRoot();
+    const backupRoot = path.join(workDir, `backups-${caseSeq}`);
+    const writeTransient = (rel: string) => {
+      const dest = path.join(hqRoot, rel, "large.bin");
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      fs.writeFileSync(dest, "reproducible\n");
+    };
+    for (const rel of [
+      "worktrees/repo",
+      ".worktrees/repo",
+      ".sst-sandbox-home/runtime",
+      ".tmp-codex-asar/cache",
+      ".claude/worktrees/agent/repo",
+      ".claude/skills/demo/node_modules/pkg",
+      ".claude/skills/demo/.pnpm-store/v3",
+      ".claude/skills/demo/.sst/build",
+      ".claude/skills/demo/.next/cache",
+      ".claude/skills/demo/target/debug",
+    ]) {
+      writeTransient(rel);
+    }
+
+    const r = runRescueCapture(
+      [
+        "--hq-root", hqRoot,
+        "--source", "test/repo",
+        "--ref", "main",
+        "--floor-sha", floorSha,
+        "--backup-dir", backupRoot,
+        "--yes",
+      ],
+      baseEnv,
+    );
+    const out = `${r.stdout}\n${r.stderr}\n${String(r.threw ?? "")}`;
+
+    expect(r.threw, out).toBeUndefined();
+    expect(r.status, out).toBe(0);
+    for (const rel of ["worktrees", ".worktrees", ".sst-sandbox-home", ".tmp-codex-asar"]) {
+      expect(fs.existsSync(path.join(hqRoot, rel, "repo", "large.bin")) ||
+        fs.existsSync(path.join(hqRoot, rel, "runtime", "large.bin")) ||
+        fs.existsSync(path.join(hqRoot, rel, "cache", "large.bin")), rel).toBe(true);
+    }
+
+    const snapshots = fs.readdirSync(backupRoot).filter((name) => name.startsWith("pre-update-"));
+    expect(snapshots).toHaveLength(1);
+    const snapshot = path.join(backupRoot, snapshots[0]);
+    expect(fs.existsSync(path.join(snapshot, "core/a.md"))).toBe(true);
+    expect(fs.existsSync(path.join(snapshot, "RECOVERY.md"))).toBe(true);
+    for (const rel of [
+      "worktrees",
+      ".worktrees",
+      ".sst-sandbox-home",
+      ".tmp-codex-asar",
+      ".claude/worktrees",
+      ".claude/skills/demo/node_modules",
+      ".claude/skills/demo/.pnpm-store",
+      ".claude/skills/demo/.sst",
+      ".claude/skills/demo/.next",
+      ".claude/skills/demo/target",
+    ]) {
+      expect(lexists(path.join(snapshot, rel)), `snapshot unexpectedly contains ${rel}`).toBe(false);
+    }
+  });
+
+  it("dry-run never allocates or prunes snapshots", () => {
+    const hqRoot = makeHqRoot();
+    const backupRoot = path.join(workDir, `dry-backups-${caseSeq}`);
+    const existing = path.join(backupRoot, "pre-update-existing");
+    fs.mkdirSync(existing, { recursive: true });
+    fs.writeFileSync(path.join(existing, "keep.txt"), "do not prune\n");
+
+    const r = runRescueCapture(
+      [
+        "--hq-root", hqRoot,
+        "--source", "test/repo",
+        "--ref", "main",
+        "--floor-sha", floorSha,
+        "--backup-dir", backupRoot,
+        "--dry-run",
+      ],
+      baseEnv,
+    );
+    const out = `${r.stdout}\n${r.stderr}\n${String(r.threw ?? "")}`;
+
+    expect(r.threw, out).toBeUndefined();
+    expect(r.status, out).toBe(0);
+    expect(fs.readdirSync(backupRoot)).toEqual(["pre-update-existing"]);
+    expect(fs.readFileSync(path.join(existing, "keep.txt"), "utf-8")).toBe("do not prune\n");
+  });
 });