@indigoai-us/hq-cloud 6.3.0 → 6.3.1

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

@@ -3643,3 +3643,249 @@ describe("runRunnerWithLoop — operation lock", () => {
     expect(held.command).toBe("sync");
   });
 });
+
+// ---------------------------------------------------------------------------
+// Phase 3 — event-driven publish + pull wiring (US-017/018/019)
+// ---------------------------------------------------------------------------
+//
+// Exercises the rollout-gated bring-up through the `startEventSync` /
+// `getIdTokenClaims` seams: gate-off is byte-identical to today (the seam is
+// never consulted), gate-on passes the wiring the right identity + sync
+// bridge, and the publish leg fires only AFTER a SUCCESSFUL targeted push
+// pass (events must never announce bytes that are not in S3 yet).
+
+interface BatchWatcherStub extends WatcherSurface {
+  emit(changedRelPath?: string, batch?: { paths: Map<string, string> }): void;
+  disposed: boolean;
+}
+
+function makeBatchWatcherStub(): BatchWatcherStub {
+  const listeners = new Set<
+    (p?: string, b?: { paths: Map<string, string> }) => void
+  >();
+  return {
+    disposed: false,
+    onChange(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    start() {},
+    stop() {},
+    dispose() {
+      this.disposed = true;
+      listeners.clear();
+    },
+    emit(changedRelPath?: string, batch?: { paths: Map<string, string> }) {
+      for (const l of [...listeners]) l(changedRelPath, batch);
+    },
+  };
+}
+
+describe("runRunnerWithLoop — Phase 3 event-sync wiring (US-017/018/019)", () => {
+  const ENROLLED_CLAIMS = { email: "hassaan@getindigo.ai" };
+  const UNENROLLED_CLAIMS = { email: "someone@getindigo.ai" };
+
+  function runLoop(opts: {
+    claims: { email?: string } | null;
+    startEventSync?: ReturnType<typeof vi.fn>;
+    watcher?: BatchWatcherStub;
+    runPass?: ReturnType<typeof vi.fn>;
+  }) {
+    const watcher = opts.watcher ?? makeBatchWatcherStub();
+    const runPass = opts.runPass ?? vi.fn().mockResolvedValue(0);
+    const clock = new FakeClock();
+    let triggerShutdown = () => {};
+    const loop = runRunnerWithLoop(
+      ["--companies", "--watch", "--event-push", "--hq-root", "/tmp/hq"],
+      {
+        runPass,
+        clock,
+        createWatcher: () => watcher,
+        sleep: () => new Promise<void>(() => {}),
+        onShutdownSignal: (handler) => {
+          triggerShutdown = handler;
+          return () => {};
+        },
+        getIdTokenClaims: () => opts.claims as never,
+        getAccessToken: async () => "jwt-test",
+        startEventSync: (opts.startEventSync ??
+          vi.fn().mockResolvedValue(null)) as never,
+      },
+    );
+    return { loop, watcher, runPass, clock, shutdown: () => triggerShutdown() };
+  }
+
+  async function microtasks(n = 6) {
+    for (let i = 0; i < n; i++) await Promise.resolve();
+  }
+
+  it("gate OFF (unenrolled email): the event-sync seam is never consulted", async () => {
+    const startEventSync = vi.fn().mockResolvedValue(null);
+    const { loop, shutdown } = runLoop({
+      claims: UNENROLLED_CLAIMS,
+      startEventSync,
+    });
+    await microtasks();
+    shutdown();
+    await loop;
+    expect(startEventSync).not.toHaveBeenCalled();
+  });
+
+  it("gate OFF (no cached claims): the event-sync seam is never consulted", async () => {
+    const startEventSync = vi.fn().mockResolvedValue(null);
+    const { loop, shutdown } = runLoop({ claims: null, startEventSync });
+    await microtasks();
+    shutdown();
+    await loop;
+    expect(startEventSync).not.toHaveBeenCalled();
+  });
+
+  it("gate ON (enrolled email): wiring receives root, api url, auth + a sync bridge", async () => {
+    const startEventSync = vi.fn().mockResolvedValue(null);
+    const { loop, shutdown } = runLoop({
+      claims: ENROLLED_CLAIMS,
+      startEventSync,
+    });
+    await microtasks();
+    shutdown();
+    await loop;
+    expect(startEventSync).toHaveBeenCalledTimes(1);
+    const arg = startEventSync.mock.calls[0][0];
+    expect(arg.hqRoot).toBe("/tmp/hq");
+    expect(arg.apiUrl).toContain("https://");
+    expect(typeof arg.deviceId).toBe("string");
+    expect(arg.deviceId.length).toBeGreaterThan(0);
+    expect(typeof arg.resolveTenantId).toBe("function");
+    expect(typeof arg.syncFn).toBe("function");
+  });
+
+  it("publishes the batch ONLY after a successful targeted push pass", async () => {
+    const publishBatch = vi.fn();
+    const startEventSync = vi.fn().mockResolvedValue({
+      publishBatch,
+      receiver: { start: async () => {}, dispose: async () => {}, connected: true },
+      ownDeviceId: "dev-test",
+      dispose: vi.fn().mockResolvedValue(undefined),
+    });
+    const runPass = vi.fn().mockResolvedValue(0);
+    const { loop, watcher, clock, shutdown } = runLoop({
+      claims: ENROLLED_CLAIMS,
+      startEventSync,
+      runPass,
+    });
+    await microtasks(); // initial poll pass + async event-sync bring-up
+    runPass.mockClear();
+
+    const batch = {
+      paths: new Map([["/tmp/hq/companies/indigo/a.md", "companies/indigo/a.md"]]),
+    };
+    watcher.emit("companies/indigo/a.md", batch);
+    clock.advance(0);
+    await microtasks();
+
+    // Targeted push ran and succeeded → batch published.
+    expect(runPass).toHaveBeenCalled();
+    expect(publishBatch).toHaveBeenCalledTimes(1);
+    expect(publishBatch.mock.calls[0][0]).toBe(batch);
+
+    shutdown();
+    await loop;
+  });
+
+  it("publishes NOTHING when the targeted push pass fails", async () => {
+    const publishBatch = vi.fn();
+    const startEventSync = vi.fn().mockResolvedValue({
+      publishBatch,
+      receiver: { start: async () => {}, dispose: async () => {}, connected: true },
+      ownDeviceId: "dev-test",
+      dispose: vi.fn().mockResolvedValue(undefined),
+    });
+    // Initial poll pass succeeds; the targeted pass fails.
+    const runPass = vi
+      .fn()
+      .mockResolvedValueOnce(0)
+      .mockResolvedValue(1);
+    const { loop, watcher, clock, shutdown } = runLoop({
+      claims: ENROLLED_CLAIMS,
+      startEventSync,
+      runPass,
+    });
+    await microtasks();
+
+    watcher.emit(
+      "companies/indigo/a.md",
+      { paths: new Map([["/tmp/hq/companies/indigo/a.md", "companies/indigo/a.md"]]) },
+    );
+    clock.advance(0);
+    await microtasks();
+
+    expect(publishBatch).not.toHaveBeenCalled();
+    shutdown();
+    await loop;
+  });
+
+  it("falls back to a synthesized single-path batch when the watcher emits a bare path", async () => {
+    const publishBatch = vi.fn();
+    const startEventSync = vi.fn().mockResolvedValue({
+      publishBatch,
+      receiver: { start: async () => {}, dispose: async () => {}, connected: true },
+      ownDeviceId: "dev-test",
+      dispose: vi.fn().mockResolvedValue(undefined),
+    });
+    const { loop, watcher, clock, shutdown } = runLoop({
+      claims: ENROLLED_CLAIMS,
+      startEventSync,
+    });
+    await microtasks();
+
+    watcher.emit("companies/indigo/b.md"); // no batch
+    clock.advance(0);
+    await microtasks();
+
+    expect(publishBatch).toHaveBeenCalledTimes(1);
+    const synthesized = publishBatch.mock.calls[0][0] as {
+      paths: Map<string, string>;
+    };
+    expect([...synthesized.paths.values()]).toEqual(["companies/indigo/b.md"]);
+
+    shutdown();
+    await loop;
+  });
+
+  it("disposes the event-sync handles on shutdown", async () => {
+    const dispose = vi.fn().mockResolvedValue(undefined);
+    const startEventSync = vi.fn().mockResolvedValue({
+      publishBatch: vi.fn(),
+      receiver: { start: async () => {}, dispose: async () => {}, connected: true },
+      ownDeviceId: "dev-test",
+      dispose,
+    });
+    const { loop, shutdown } = runLoop({
+      claims: ENROLLED_CLAIMS,
+      startEventSync,
+    });
+    await microtasks();
+    shutdown();
+    await loop;
+    expect(dispose).toHaveBeenCalled();
+  });
+
+  it("env override HQ_SYNC_EVENT_SYNC=0 keeps the seam dormant for the enrolled account", async () => {
+    const prev = process.env.HQ_SYNC_EVENT_SYNC;
+    process.env.HQ_SYNC_EVENT_SYNC = "0";
+    try {
+      const startEventSync = vi.fn().mockResolvedValue(null);
+      const { loop, shutdown } = runLoop({
+        claims: ENROLLED_CLAIMS,
+        startEventSync,
+      });
+      await microtasks();
+      shutdown();
+      await loop;
+      expect(startEventSync).not.toHaveBeenCalled();
+    } finally {
+      if (prev === undefined) delete process.env.HQ_SYNC_EVENT_SYNC;
+      else process.env.HQ_SYNC_EVENT_SYNC = prev;
+    }
+  });
+});

package/src/bin/sync-runner.ts

@@ -112,12 +112,19 @@ import {
   WatchPushDriver,
   systemClock,
   type Clock,
+  type TreeChangeBatch,
 } from "../watcher.js";
 import {
   NoopPushReceiver,
   type PushReceiver,
   type SyncEngineFn,
 } from "../sync/push-receiver.js";
+import {
+  resolveEventSync,
+  startEventSync as defaultStartEventSync,
+  type EventSyncHandles,
+  type StartEventSyncOptions,
+} from "../sync/event-sync.js";
 import {
   PERSONAL_VAULT_JOURNAL_SLUG,
   migratePersonalVaultJournal,
@@ -1829,6 +1836,27 @@ export interface RunnerLoopDeps {
     syncFn: SyncEngineFn;
     hqRoot: string;
   }) => PushReceiver;
+  /**
+   * Phase 3 (US-017/US-018/US-019): factory for the event-driven publish +
+   * pull wiring, consulted only when `--event-push` is on AND the rollout
+   * gate ({@link resolveEventSync}) passes for the signed-in account.
+   * Defaults to the real {@link defaultStartEventSync}. Tests inject a stub
+   * to assert gate behavior without network/AWS.
+   */
+  startEventSync?: (
+    opts: StartEventSyncOptions,
+  ) => Promise<EventSyncHandles | null>;
+  /**
+   * Identity-claims source for the Phase 3 rollout gate (the loop has no
+   * RunnerDeps; mirror of RunnerDeps.getIdTokenClaims). Defaults to reading
+   * the cached Cognito idToken.
+   */
+  getIdTokenClaims?: () => IdTokenClaims | null;
+  /**
+   * Access-token source for the Phase 3 vault API calls (publish transport +
+   * subscribe). Defaults to {@link getValidAccessToken} non-interactive.
+   */
+  getAccessToken?: () => Promise<string>;
 }
 
 /**
@@ -1843,7 +1871,9 @@ export interface RunnerLoopDeps {
  * relative path so the loop targets just that company.
  */
 export interface WatcherSurface {
-  onChange(listener: (changedRelPath?: string) => void): () => void;
+  onChange(
+    listener: (changedRelPath?: string, batch?: TreeChangeBatch) => void,
+  ): () => void;
   start(): void;
   stop(): void;
   dispose(): void;
@@ -1999,12 +2029,17 @@ export async function runRunnerWithLoop(
   let driver: WatchPushDriver | null = null;
   let detachSignal: (() => void) | null = null;
   let lastChangedRel: string | null = null;
+  let lastBatch: TreeChangeBatch | null = null;
   // ---- pull-on-event receiver (Phase 2, US-009) ------------------------
   // Started after the watcher, disposed before the watcher (mirror of the
   // PushTransport ordering). Dormant by default: the default factory returns
   // a NoopPushReceiver, and even a real receiver stays dormant unless the
   // per-tenant feature flag is on AND a queue URL is provisioned server-side.
   let receiver: PushReceiver | null = null;
+  // ---- event-driven publish + pull (Phase 3, US-017/018/019) ------------
+  // Brought up asynchronously after the watcher when the rollout gate
+  // passes; null until ready (and stays null on startup failure → poll-only).
+  let eventSync: EventSyncHandles | null = null;
 
   if (eventPush) {
     const clock = deps.clock ?? systemClock;
@@ -2032,12 +2067,28 @@ export async function runRunnerWithLoop(
       push: async () => {
         if (stopped) return;
         const rel = lastChangedRel;
+        // Snapshot the settled batch BEFORE the await: a change landing
+        // mid-pass overwrites lastBatch for the NEXT pass, and this pass
+        // must only announce what it actually pushed.
+        const batchForPublish = lastBatch;
+        lastBatch = null;
         const route = rel
           ? routeChangeToTarget(rel)
           : { kind: "personal" as const };
         if (!route) return;
         const targetedArgv = buildTargetedPushArgv(route, passArgv);
-        await runGuarded(() => runPass(targetedArgv));
+        const result = await runGuarded(() => runPass(targetedArgv));
+        // Phase 3 (US-017): publish PushEvents only AFTER the targeted push
+        // pass succeeded — an event must never announce bytes that are not
+        // in S3 yet. A skipped pass (guard held) or a failed pass publishes
+        // nothing; the cadence poll covers the miss. Fall back to a
+        // single-path batch when the watcher emitted a bare path signal.
+        if (result === 0 && eventSync) {
+          const batch: TreeChangeBatch | null =
+            batchForPublish ??
+            (rel ? { paths: new Map([[path.join(hqRoot, rel), rel]]) } : null);
+          if (batch) eventSync.publishBatch(batch);
+        }
       },
     });
 
@@ -2046,9 +2097,10 @@ export async function runRunnerWithLoop(
     // still serialized behind any in-flight pass. A path-aware watcher passes
     // the changed relative path so the push targets just its owning company;
     // the bare-signal TreeWatcher leaves it null → personal-vault route.
-    watcher.onChange((changedRelPath) => {
+    watcher.onChange((changedRelPath, batch) => {
       if (stopped) return;
       lastChangedRel = changedRelPath ?? null;
+      lastBatch = batch ?? null;
       driver?.notifyChange();
     });
     watcher.start();
@@ -2077,6 +2129,60 @@ export async function runRunnerWithLoop(
     // start also keeps the poll loop's microtask timing identical to the
     // pre-US-009 wiring.)
     void Promise.resolve(receiver.start()).catch(() => undefined);
+
+    // ---- Phase 3: event-driven publish + pull (US-017/018/019) ----------
+    // Gated to enrolled accounts (resolveEventSync — exact-email allowlist +
+    // HQ_SYNC_EVENT_SYNC override). Brought up asynchronously so a slow
+    // subscribe/vend can't delay the first poll pass; until (and unless) the
+    // handles resolve, behavior is byte-identical to the gate-off path.
+    const getClaims = deps.getIdTokenClaims ?? defaultGetIdTokenClaims;
+    const email = getClaims()?.email;
+    if (resolveEventSync(email, process.env.HQ_SYNC_EVENT_SYNC)) {
+      const getAccessToken =
+        deps.getAccessToken ??
+        (() => getValidAccessToken(DEFAULT_COGNITO, { interactive: false }));
+      const startES = deps.startEventSync ?? defaultStartEventSync;
+      // Entirely async + caught: NOTHING in the Phase 3 bring-up (device-id
+      // persistence, tenant resolution, subscribe) may crash or delay the
+      // daemon — any failure degrades to poll-only.
+      void (async () => {
+        const handles = await startES({
+          hqRoot,
+          apiUrl: DEFAULT_VAULT_API_URL,
+          authToken: getAccessToken,
+          deviceId: getOrCreateMachineId(hqRoot),
+          // The server rejects publishes whose originTenantId mismatches the
+          // JWT principal, so resolve the SAME canonical person uid the vault
+          // API derives from this token.
+          resolveTenantId: async () => {
+            const client = new VaultClient({
+              apiUrl: DEFAULT_VAULT_API_URL,
+              authToken: getAccessToken,
+              region: DEFAULT_COGNITO.region,
+            });
+            const persons = await client.entity.listByType("person");
+            const pick = pickCanonicalPersonEntity(persons);
+            if (!pick?.uid) {
+              throw new Error("no canonical person entity for this account");
+            }
+            return pick.uid;
+          },
+          syncFn: receiverSyncFn,
+          log: (m) => process.stderr.write(`${m}\n`),
+        });
+        if (!handles) return;
+        if (stopped) {
+          // Shutdown raced the async bring-up — tear straight down.
+          void handles.dispose();
+          return;
+        }
+        eventSync = handles;
+      })().catch((err) => {
+        process.stderr.write(
+          `event-sync: wiring failed, continuing poll-only: ${describeError(err)}\n`,
+        );
+      });
+    }
   }
 
   // ---- clean shutdown --------------------------------------------------
@@ -2101,6 +2207,14 @@ export async function runRunnerWithLoop(
     } catch {
       /* ignore */
     }
+    // Phase 3 wiring (publish transport + live receiver) — torn down with
+    // the same fire-and-forget posture as the Phase 2 receiver above.
+    try {
+      void eventSync?.dispose();
+    } catch {
+      /* ignore */
+    }
+    eventSync = null;
     try {
       driver?.dispose();
     } catch {

package/src/cli/rescue-core.ts

@@ -384,9 +384,22 @@ function doRescue(
     hqRoot = fs.realpathSync(process.cwd());
   }
 
-  if (!isDir(path.join(hqRoot, "companies")) || !isDir(path.join(hqRoot, "personal"))) {
+  // HQ-root sanity gate — guards against wiping a non-HQ directory. `companies/`
+  // is the stable anchor (present and preserved on every HQ install), confirmed
+  // by at least one core scaffold marker. We accept ANY of `.claude/`, `core/`,
+  // or `personal/` because the layout has drifted across releases: v14.0.0 ships
+  // NEITHER `personal/` (added v15) NOR `core/` (the v15 scaffold home) — it only
+  // has `.claude/`. Requiring `personal/` here left v14.0.0 users with no upgrade
+  // path (rescue aborted; DEV-1741). `.claude/` exists on every version v14→v15,
+  // so it admits the full upgrade range while still rejecting a bare directory.
+  const hasHqMarker =
+    isDir(path.join(hqRoot, ".claude")) ||
+    isDir(path.join(hqRoot, "core")) ||
+    isDir(path.join(hqRoot, "personal"));
+  if (!isDir(path.join(hqRoot, "companies")) || !hasHqMarker) {
     err(
-      `error: ${hqRoot} does not look like an HQ root (missing companies/ or personal/). Aborting.\n`,
+      `error: ${hqRoot} does not look like an HQ root ` +
+        `(need companies/ plus one of .claude/, core/, or personal/). Aborting.\n`,
     );
     err("       pass --hq-root <dir> if the script is not at personal/skills/<skill>/.\n");
     throw new ExitError(3);

package/src/cli/rescue-hq-root-guard.test.ts

@@ -0,0 +1,193 @@
+/**
+ * Regression test for the rescue HQ-root sanity gate in src/cli/rescue-core.ts.
+ *
+ * Bug (DEV-1741): the gate required BOTH `companies/` AND `personal/`. The
+ * `personal/` directory was only introduced in v15 — a faithful v14.0.0 install
+ * ships NEITHER `personal/` NOR `core/` (its scaffold lived in top-level dirs
+ * like `scripts/`, `workers/`, `knowledge/`, plus `.claude/`). So every v14.0.0
+ * user hit `error: ... missing companies/ or personal/. Aborting.` (exit 3) and
+ * had no supported upgrade path to v15.
+ *
+ * The gate now anchors on `companies/` plus ANY ONE of `.claude/`, `core/`, or
+ * `personal/`. `.claude/` exists on every release from v14 through v15, so the
+ * relaxed gate admits the full upgrade range while still rejecting a directory
+ * that is not an HQ root at all.
+ *
+ * Like the sibling drift test, the rescue clones its source from GitHub, so we
+ * shim `git clone` to a local fixture repo. All runs are `--dry-run` (no
+ * destructive ops, no backup) and we assert on the gate's behavior (exit code +
+ * message), not the full overlay.
+ */
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { execFileSync } from "child_process";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { runRescue } from "./rescue-core.js";
+
+function hasGit(): boolean {
+  try {
+    execFileSync("git", ["--version"], { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const gitAvailable = hasGit();
+
+/** Run the rescue in-process, capturing its stdout/stderr. */
+function runRescueCapture(argv: string[], env: NodeJS.ProcessEnv) {
+  let stdout = "";
+  let stderr = "";
+  const origOut = process.stdout.write.bind(process.stdout);
+  const origErr = process.stderr.write.bind(process.stderr);
+  process.stdout.write = ((chunk: unknown) => {
+    stdout += String(chunk);
+    return true;
+  }) as typeof process.stdout.write;
+  process.stderr.write = ((chunk: unknown) => {
+    stderr += String(chunk);
+    return true;
+  }) as typeof process.stderr.write;
+  let status: number;
+  try {
+    status = runRescue(argv, { env }).status;
+  } finally {
+    process.stdout.write = origOut;
+    process.stderr.write = origErr;
+  }
+  return { status, stdout, stderr };
+}
+
+describe.skipIf(!gitAvailable)("rescue HQ-root sanity gate", () => {
+  let workDir: string;
+  let upstream: string;
+  let shimDir: string;
+  let floorSha: string;
+  let env: NodeJS.ProcessEnv;
+
+  const git = (cwd: string, ...args: string[]) =>
+    execFileSync("git", args, {
+      cwd,
+      stdio: ["ignore", "pipe", "pipe"],
+      env: {
+        ...process.env,
+        GIT_AUTHOR_NAME: "t",
+        GIT_AUTHOR_EMAIL: "t@t",
+        GIT_COMMITTER_NAME: "t",
+        GIT_COMMITTER_EMAIL: "t@t",
+      },
+    })
+      .toString()
+      .trim();
+
+  beforeAll(() => {
+    workDir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-rescue-gate-"));
+
+    // --- Minimal local "upstream" repo (one core file, floor + HEAD). ---
+    upstream = path.join(workDir, "upstream");
+    fs.mkdirSync(path.join(upstream, "core"), { recursive: true });
+    git(workDir, "init", "-b", "main", "upstream");
+    fs.writeFileSync(path.join(upstream, "core/x.md"), "v1\n");
+    git(upstream, "add", "-A");
+    git(upstream, "commit", "-m", "floor");
+    floorSha = git(upstream, "rev-parse", "HEAD");
+    fs.writeFileSync(path.join(upstream, "core/x.md"), "v2\n");
+    git(upstream, "add", "-A");
+    git(upstream, "commit", "-m", "head");
+
+    // --- git shim: rewrite `git clone <github-url> dest` to the fixture. ---
+    const realGit =
+      execFileSync("bash", ["-lc", "command -v git"]).toString().trim() || "/usr/bin/git";
+    shimDir = path.join(workDir, "shim");
+    fs.mkdirSync(shimDir, { recursive: true });
+    const shim = `#!/usr/bin/env bash
+if [ "$1" = "clone" ]; then
+  args=()
+  for a in "$@"; do
+    case "$a" in
+      https://github.com/*) a=${JSON.stringify(upstream)} ;;
+    esac
+    args+=("$a")
+  done
+  exec ${JSON.stringify(realGit)} "\${args[@]}"
+fi
+exec ${JSON.stringify(realGit)} "$@"
+`;
+    fs.writeFileSync(path.join(shimDir, "git"), shim, { mode: 0o755 });
+    env = { ...process.env, PATH: `${shimDir}:${process.env.PATH ?? ""}` };
+  }, 60_000); // git init + commits can exceed vitest's 10s default under parallel load
+
+  afterAll(() => {
+    if (workDir) fs.rmSync(workDir, { recursive: true, force: true });
+  });
+
+  function makeRoot(name: string, dirs: string[]): string {
+    const root = path.join(workDir, name);
+    for (const d of dirs) fs.mkdirSync(path.join(root, d), { recursive: true });
+    return root;
+  }
+
+  function rescueDry(hqRoot: string) {
+    return runRescueCapture(
+      [
+        "--hq-root", hqRoot,
+        "--source", "test/repo",
+        "--ref", "main",
+        "--floor-sha", floorSha,
+        "--dry-run",
+        "--yes",
+        "--no-backup",
+      ],
+      env,
+    );
+  }
+
+  it("admits a faithful v14.0.0 root (companies/ + .claude/, NO personal/, NO core/)", () => {
+    // Exactly the shape that aborted before the fix.
+    const root = makeRoot("v14", ["companies", ".claude", "repos", "workspace"]);
+    expect(fs.existsSync(path.join(root, "personal"))).toBe(false);
+    expect(fs.existsSync(path.join(root, "core"))).toBe(false);
+
+    const r = rescueDry(root);
+    const out = `${r.stdout}\n${r.stderr}`;
+    // Must get PAST the gate — not the exit-3 abort.
+    expect(r.status, out).not.toBe(3);
+    expect(out).not.toContain("does not look like an HQ root");
+    expect(r.status, out).toBe(0);
+  });
+
+  it("admits a v15 root (companies/ + core/ + personal/)", () => {
+    const root = makeRoot("v15", ["companies", ".claude", "core", "personal", "repos", "workspace"]);
+    const r = rescueDry(root);
+    const out = `${r.stdout}\n${r.stderr}`;
+    expect(r.status, out).toBe(0);
+    expect(out).not.toContain("does not look like an HQ root");
+  });
+
+  it("admits a core-only root (companies/ + core/, no .claude/ or personal/)", () => {
+    const root = makeRoot("coreonly", ["companies", "core"]);
+    const r = rescueDry(root);
+    const out = `${r.stdout}\n${r.stderr}`;
+    expect(r.status, out).not.toBe(3);
+    expect(out).not.toContain("does not look like an HQ root");
+  });
+
+  it("still rejects a non-HQ directory (companies/ only — no scaffold marker)", () => {
+    const root = makeRoot("bare", ["companies"]);
+    const r = rescueDry(root);
+    const out = `${r.stdout}\n${r.stderr}`;
+    expect(r.status, out).toBe(3);
+    expect(out).toContain("does not look like an HQ root");
+    expect(out).toContain("need companies/ plus one of .claude/, core/, or personal/");
+  });
+
+  it("still rejects a directory with a marker but no companies/", () => {
+    const root = makeRoot("nocompanies", [".claude", "core", "personal"]);
+    const r = rescueDry(root);
+    const out = `${r.stdout}\n${r.stderr}`;
+    expect(r.status, out).toBe(3);
+    expect(out).toContain("does not look like an HQ root");
+  });
+});