@indigoai-us/hq-cloud 6.14.17 → 6.14.19

package/src/bin/sync-runner.ts

@@ -125,7 +125,11 @@ import {
 } from "../lib/net-errors.js";
 import { PARTIAL_SYNC_EXIT } from "../lib/exit-codes.js";
 import { describeError } from "../lib/describe-error.js";
-import type { Clock, TreeChangeBatch } from "../watcher.js";
+import type {
+  Clock,
+  LocalDeleteSnapshot,
+  TreeChangeBatch,
+} from "../watcher.js";
 import type { PushReceiver, SyncEngineFn } from "../sync/push-receiver.js";
 import {
   type EventSyncHandles,
@@ -140,10 +144,18 @@ import {
   buildFanoutPlan,
   emitFanoutPlan,
   resolveMembershipsForRun,
+  type RunnerTarget,
+  type SetupNeededReason,
 } from "./sync-runner-planning.js";
+import {
+  seedActiveCompany,
+  type SeedActiveCompanyOptions,
+  type SeedActiveCompanyResult,
+} from "../active-company.js";
 import {
   reconcileCompanyManifest,
   type ManifestReconcileOptions,
+  type ManifestReconcileResult,
 } from "../manifest-reconcile.js";
 import { executeCompanyFanout } from "./sync-runner-company.js";
 import { rollupAllComplete } from "./sync-runner-rollup.js";
@@ -333,11 +345,28 @@ export { PERSONAL_VAULT_EXCLUDED_TOP_LEVEL, computePersonalVaultPaths };
  * specific company".
  */
 export type RunnerEvent =
-  | { type: "setup-needed" }
+  | {
+      /**
+       * The run cannot proceed. `reason` and `pendingInviteCount` are additive
+       * and optional by design: a consumer that only reads `type` behaves
+       * exactly as before, while /setup and /hq-sync can tell the user WHY they
+       * look solo — most usefully, that an invite is still waiting.
+       */
+      type: "setup-needed";
+      reason?: SetupNeededReason;
+      pendingInviteCount?: number;
+    }
   | { type: "auth-error"; message: string }
   | {
+      /**
+       * The resolved fanout plan. Carries whole `RunnerTarget`s: the runtime
+       * payload has always been the plan entries verbatim, so the previous
+       * `{uid, slug, name?}` declaration understated the wire contract (it
+       * already omitted `bucketName`, `personalMode`, and `journalSlug`).
+       * Consumers deserialize leniently and ignore fields they do not know.
+       */
       type: "fanout-plan";
-      companies: Array<{ uid: string; slug: string; name?: string }>;
+      companies: RunnerTarget[];
     }
   | ({
       /**
@@ -632,11 +661,15 @@ export interface RunnerDeps {
    */
   reconcileManifest?: (
     options: ManifestReconcileOptions,
-  ) => Promise<void>;
+  ) => Promise<ManifestReconcileResult>;
+  /** Internal test seam for `.hq/config.json` activeCompany seeding. */
+  seedActiveCompany?: (options: SeedActiveCompanyOptions) => SeedActiveCompanyResult;
   /** Internal: set when runRunner is invoked under the per-root operation lock. */
   operationLockAlreadyHeld?: boolean;
   /** Internal watch-loop result override; one-shot callers keep exit 0. */
   authRequiredExitCode?: number;
+  /** Internal watch-loop callback carrying uncapped per-path push outcomes. */
+  onPassResult?: (result: RunnerPassResult) => void;
   /** Share function (push phase). Defaults to `cli/share.share`. */
   share?: (options: ShareOptions) => Promise<ShareResult>;
   /**
@@ -652,6 +685,20 @@ export interface RunnerDeps {
   telemetryTimeoutMs?: number;
 }
 
+export interface RunnerPassResult {
+  pushPathResults: Array<{
+    relativePath: string;
+    status: "accepted" | "refused";
+    operation: "delete" | "tombstone";
+    reason?: string;
+  }>;
+}
+
+export interface RunnerPassOutcome {
+  exitCode: number;
+  result?: RunnerPassResult;
+}
+
 // ---------------------------------------------------------------------------
 // JWT claim decoder — inlined to avoid pulling a dep just to read an idToken.
 // We do NOT verify the signature here — Cognito already did that when it
@@ -698,10 +745,11 @@ async function runClaimDance(
   client: VaultClientSurface,
   claims: IdTokenClaims,
   stderr: { write: (chunk: string) => boolean | void },
-): Promise<void> {
+  reportDiagnostic: RunnerDiagnosticReporter = () => undefined,
+): Promise<number> {
   try {
     const pending = await client.listMyPendingInvitesByEmail();
-    if (pending.length === 0) return;
+    if (pending.length === 0) return 0;
 
     const displayName =
       claims.name ??
@@ -710,10 +758,15 @@ async function runClaimDance(
       "";
     const ownerSub = claims.sub ?? "";
     if (!ownerSub || !displayName) {
-      stderr.write(
-        "hq-sync-runner: skipping claim-dance — idToken missing sub/name\n",
-      );
-      return;
+      reportDiagnostic({
+        component: "claim-dance",
+        event: "runner.claim_dance.skipped",
+        message: "skipping claim-dance — idToken missing sub/name",
+        context: { pendingInviteCount: pending.length },
+      });
+      // The invites are real and still pending; the caller must be able to say
+      // so even though we could not claim them.
+      return pending.length;
     }
 
     const person = await client.ensureMyPersonEntity({
@@ -721,9 +774,19 @@ async function runClaimDance(
       displayName,
     });
     await client.claimPendingInvitesByEmail(person.uid);
+    return pending.length;
   } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    stderr.write(`hq-sync-runner: claim-dance skipped — ${msg}\n`);
+    // Non-throwing by contract: a claim-dance failure must never take down a
+    // sync. But it stops being invisible — a systematic failure here is exactly
+    // what makes a joiner look permanently solo.
+    reportDiagnostic({
+      component: "claim-dance",
+      event: "runner.claim_dance.skipped",
+      message: "claim-dance skipped",
+      err,
+      context: {},
+    });
+    return 0;
   }
 }
 
@@ -769,6 +832,11 @@ interface ParsedArgs {
   skipPersonal: boolean;
   /** Repeatable company/personal-relative path scope for push-only passes. */
   scopePaths: string[];
+  /**
+   * Internal watcher-only delete roots. Unlike `scopePaths`, these remain
+   * meaningful after the corresponding local file or directory is absent.
+   */
+  deleteScopePaths: string[];
   /**
    * Bounded wait (seconds) for the per-root operation lock when another op is
    * already running. `0` → refuse immediately (pre-wait behavior); omitted →
@@ -789,6 +857,7 @@ function parseArgs(argv: string[]): ParsedArgs | { error: string } {
   let pollRemoteMs: number | undefined;
   let skipPersonal = false;
   const scopePaths: string[] = [];
+  const deleteScopePaths: string[] = [];
   let eventPush = false;
   let lockTimeoutSec: number | undefined;
 
@@ -870,6 +939,12 @@ function parseArgs(argv: string[]): ParsedArgs | { error: string } {
         scopePaths.push(val);
         break;
       }
+      case "--delete-scope-path": {
+        const val = argv[++i];
+        if (!val) return { error: "--delete-scope-path requires a value" };
+        deleteScopePaths.push(val);
+        break;
+      }
       case "--lock-timeout": {
         const val = argv[++i];
         if (!val) return { error: "--lock-timeout requires a value (seconds)" };
@@ -921,6 +996,7 @@ function parseArgs(argv: string[]): ParsedArgs | { error: string } {
     pollRemoteMs,
     skipPersonal,
     scopePaths,
+    deleteScopePaths,
     eventPush,
     lockTimeoutSec,
   };
@@ -1276,11 +1352,18 @@ export async function runRunner(
       client,
       claims,
       stderr,
-      runClaimDance,
+      runClaimDance: (client, claims, stderr) =>
+        runClaimDance(client, claims, stderr, reportDiagnostic),
       listMemberships: listMembershipsWithRetry,
     });
     if (resolution.status === "setup-needed") {
-      emit({ type: "setup-needed" });
+      emit({
+        type: "setup-needed",
+        reason: resolution.reason,
+        ...(resolution.pendingInviteCount === undefined
+          ? {}
+          : { pendingInviteCount: resolution.pendingInviteCount }),
+      });
       return 0;
     }
     memberships = resolution.memberships;
@@ -1335,7 +1418,7 @@ export async function runRunner(
     return isTransientNetworkError(err) ? TRANSIENT_NETWORK_EXIT : 1;
   }
   if (targetPlan.status === "setup-needed") {
-    emit({ type: "setup-needed" });
+    emit({ type: "setup-needed", reason: targetPlan.reason });
     return 0;
   }
   const plan = targetPlan.plan;
@@ -1368,6 +1451,7 @@ export async function runRunner(
       resolveDeletePolicy,
       emit,
       scopePaths: parsed.scopePaths,
+      deleteScopePaths: parsed.deleteScopePaths,
       telemetryClient: client,
       telemetryClaims: claims,
       telemetrySessionId,
@@ -1381,24 +1465,49 @@ export async function runRunner(
     throw err;
   }
   const { errors, allConflicts, meaningfulOutcomeCount } = fanout;
+  deps.onPassResult?.({ pushPathResults: fanout.pushPathResults });
   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") {
+  //
+  // `--companies` only. A single-company run (`--company <slug>`) and a
+  // `--personal` run both see just one leg of the fanout, so neither has the
+  // full picture the manifest is reconciled against; treating a partial view as
+  // authoritative is how entries get lost. A push-only pass materializes
+  // nothing new locally, so it has nothing to reconcile either.
+  if (parsed.companies && parsed.direction !== "push") {
+    const completedCompanySlugs = new Set(
+      Array.from(fanout.stateByCompany.entries())
+        .filter(([, state]) => state.status === "complete")
+        .map(([slug]) => slug),
+    );
+    // The personal vault is never a manifest entry. The reconciler filters it
+    // too, but that is its own internal invariant — excluding it here means
+    // the personal target is never even handed across the seam.
+    const companyTargets = plan.filter(
+      (target) => target.personalMode !== true && target.slug !== "personal",
+    );
     try {
-      const completedCompanySlugs = new Set(
-        Array.from(fanout.stateByCompany.entries())
-          .filter(([, state]) => state.status === "complete")
-          .map(([slug]) => slug),
-      );
-      await (deps.reconcileManifest ?? reconcileCompanyManifest)({
+      const result = await (deps.reconcileManifest ?? reconcileCompanyManifest)({
         hqRoot: parsed.hqRoot,
-        targets: plan,
+        targets: companyTargets,
         completedCompanySlugs,
-        getEntity: client.entity.get,
+        reportDiagnostic: (diagnostic) =>
+          reportDiagnostic({ component: "manifest-reconcile", ...diagnostic }),
       });
+      // Only on an actual write. A steady-state sync stays silent, so an
+      // unexpected diagnostic rate is itself the signal that skip-if-unchanged
+      // has regressed.
+      if (result.written) {
+        reportDiagnostic({
+          component: "manifest-reconcile",
+          event: "manifest-reconciled",
+          message: "restored company entries in companies/manifest.yaml",
+          context: { added: result.added, updated: result.updated },
+        });
+      }
     } catch (err) {
       reportDiagnostic({
         component: "manifest-reconcile",
@@ -1408,6 +1517,38 @@ export async function runRunner(
         context: { hqRoot: parsed.hqRoot },
       });
     }
+
+    // A joiner whose manifest entry was just restored still has nothing telling
+    // HQ which company is current. Seed it only when the answer cannot be wrong
+    // — deliberately its own try, so a manifest failure does not also cost the
+    // user their routing.
+    try {
+      const localCompanySlugs = companyTargets
+        .map((target) => target.slug)
+        .filter((slug) => completedCompanySlugs.has(slug));
+      const seeded = (deps.seedActiveCompany ?? seedActiveCompany)({
+        hqRoot: parsed.hqRoot,
+        companySlugs: localCompanySlugs,
+        reportDiagnostic: (diagnostic) =>
+          reportDiagnostic({ component: "active-company", ...diagnostic }),
+      });
+      if (seeded.written) {
+        reportDiagnostic({
+          component: "active-company",
+          event: "active-company-seeded",
+          message: "seeded activeCompany in .hq/config.json",
+          context: { activeCompany: seeded.activeCompany },
+        });
+      }
+    } catch (err) {
+      reportDiagnostic({
+        component: "active-company",
+        event: "runner.active_company.failed",
+        message: "seeding activeCompany failed",
+        err,
+        context: { hqRoot: parsed.hqRoot },
+      });
+    }
   }
 
   if (rollup.needsReindex) {
@@ -1754,7 +1895,7 @@ export interface RunnerLoopDeps {
    * targeted push share one seam and one in-flight guard. The default ignores
    * `deps` and forwards just the argv to `runRunner`.
    */
-  runPass?: (passArgv: string[]) => Promise<number>;
+  runPass?: (passArgv: string[]) => Promise<number | RunnerPassOutcome>;
   /** Stage-0 backup retention backstop: a dry-run only, never a sync-tick action. */
   runBackupPrune?: (hqRoot: string) => Promise<void>;
   /**
@@ -1772,6 +1913,10 @@ export interface RunnerLoopDeps {
     hqRoot: string;
     debounceMs: number;
     clock: Clock;
+    captureLocalDeleteSnapshots: (
+      relativePath: string,
+      kind: "unlink" | "unlinkDir",
+    ) => LocalDeleteSnapshot[];
   }) => WatcherSurface;
   /**
    * Register a one-shot shutdown signal handler. Defaults to listening for
@@ -1849,11 +1994,17 @@ export async function runRunnerWithLoop(
 ): Promise<number> {
   const parsed = parseArgs(argv);
   const runtime = {
-    runPassWithOperationLockAlreadyHeld: (passArgv: string[]) =>
-      runRunner(passArgv, {
+    runPassWithOperationLockAlreadyHeld: async (passArgv: string[]) => {
+      let result: RunnerPassResult | undefined;
+      const exitCode = await runRunner(passArgv, {
         operationLockAlreadyHeld: true,
         authRequiredExitCode: AUTH_REQUIRED_PASS_EXIT,
-      }),
+        onPassResult: (passResult) => {
+          result = passResult;
+        },
+      });
+      return { exitCode, ...(result ? { result } : {}) };
+    },
     authRequiredPassExit: AUTH_REQUIRED_PASS_EXIT,
     defaultGetIdTokenClaims,
     defaultGetAccessToken: () =>

package/src/cli/rescue-core.ts

@@ -1515,6 +1515,31 @@ function masterSyncSymlinkTarget(localPath: string): string | null {
   return tgt.includes("/personal/") || tgt.startsWith("personal/") ? tgt : null;
 }
 
+/**
+ * Drop a reindex symlink with lstat + unlink semantics: treat the path as a
+ * link and remove the link itself, never following or recursing into its
+ * target.
+ *
+ * `fs.rmSync(p, { force: true })` stat-follows on some platforms (notably
+ * macOS): a symlink whose target is a directory is seen as a directory, and
+ * with `recursive` unset it throws `EISDIR` ("Path is a directory"). During a
+ * rescue apply that abort rolls back the whole update — the exact failure this
+ * guards against (a directory-target overlay symlink such as
+ * core/knowledge/<name> -> personal/knowledge/<name>). `unlink(2)` removes the
+ * link regardless of what it points at, so file- and directory-target reindex
+ * symlinks are dropped identically. reindex.sh re-lays the link afterward.
+ *
+ * A missing path is a no-op (force-equivalent); a non-symlink is left untouched
+ * so we can never recurse into or delete a real directory (the classifier only
+ * ever routes real symlinks here — this stays defensive).
+ */
+function dropReindexSymlink(localPath: string): void {
+  const st = lstatOrNull(localPath);
+  if (!st) return; // already gone — nothing to drop
+  if (!st.isSymbolicLink()) return; // never follow/recurse into a real target
+  fs.unlinkSync(localPath);
+}
+
 function isUnderPreserve(cfg: Config, rel: string): boolean {
   for (const sp of cfg.preserveSubpaths) {
     if (rel === sp || rel.startsWith(sp + "/")) return true;
@@ -1972,7 +1997,7 @@ function buildRescueActions(ctx: WalkCtx): RescueAction[] {
         break;
       case "drop-reindex-symlink":
         add(`drop reindex symlink: ${decision.rel}`, [decision.rel], () => {
-          fs.rmSync(localPath, { force: true });
+          dropReindexSymlink(localPath);
           ctx.appendLog(`symlink-dropped\t${decision.rel}\t(reindex regenerable)\n`);
         });
         break;

package/src/cli/rescue-drop-dir-symlink.test.ts

@@ -0,0 +1,224 @@
+/**
+ * Regression for the rescue "drop reindex symlink" fix in
+ * src/cli/rescue-core.ts (dropReindexSymlink).
+ *
+ * The bug: the apply step removed a reindex overlay symlink with
+ * `fs.rmSync(localPath, { force: true })`. `rmSync` stat-FOLLOWS on some
+ * platforms (notably macOS), so a symlink whose target is a directory — e.g.
+ * core/knowledge/ad-creative-engine -> personal/knowledge/ad-creative-engine —
+ * is seen as a directory and, with `recursive` unset, throws `EISDIR`
+ * ("Path is a directory"). During a rescue apply that abort rolls back the
+ * whole update, so /update-hq fails on any install carrying a directory-target
+ * overlay symlink. The fix removes the link with lstat + unlink semantics
+ * (`fs.unlinkSync`), which drops the link itself regardless of what it points
+ * at and never recurses into the target.
+ *
+ * The macOS `rmSync` follow-behavior is not reproducible with a plain path on
+ * Linux CI, so we reproduce it deterministically: `fs` is mocked so `rmSync`
+ * throws `EISDIR` on exactly a directory-target symlink (every other call is
+ * delegated to the real implementation). Under that fault the OLD code aborts
+ * the apply and rolls the whole update back; the fixed code drops the link with
+ * `unlinkSync` and the rescue still succeeds.
+ *
+ * Mirrors rescue-mtime-preserve.test.ts: shim `git clone` to a local fixture
+ * and run the real rescue (non-dry-run, --no-backup) so the overlay lays files
+ * down and the symlink-drop action really runs.
+ */
+import { describe, it, expect, beforeAll, afterAll, vi } 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";
+
+// Simulate the reporter's platform (macOS): fs.rmSync stat-follows a
+// symlink-to-directory and throws EISDIR ("Path is a directory"). Only the
+// dir-target symlink trips this; every other rmSync call — and every other fs
+// function — is the real implementation, so clone/overlay/backup all work.
+vi.mock("fs", async (importOriginal) => {
+  const real = await importOriginal<typeof import("fs")>();
+  const patchedRmSync: typeof real.rmSync = ((p: fs.PathLike, opts?: fs.RmOptions) => {
+    try {
+      const lst = real.lstatSync(p as fs.PathLike);
+      if (lst.isSymbolicLink() && real.statSync(p as fs.PathLike).isDirectory()) {
+        const err = new Error(
+          `EISDIR: illegal operation on a directory, Path is a directory: ${String(p)}`,
+        ) as NodeJS.ErrnoException;
+        err.code = "ERR_FS_EISDIR";
+        throw err;
+      }
+    } catch (e) {
+      if ((e as NodeJS.ErrnoException).code === "ERR_FS_EISDIR") throw e;
+      // lstat/stat failed (missing path / broken link) — fall through to real rm.
+    }
+    return real.rmSync(p, opts);
+  }) as typeof real.rmSync;
+  return { ...real, rmSync: patchedRmSync };
+});
+
+function has(bin: string, ...args: string[]): boolean {
+  try {
+    execFileSync(bin, args, { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+const toolsAvailable = has("git", "--version") && has("rsync", "--version");
+
+const EPOCH = 1609459200; // 2021-01-01T00:00:00Z
+
+/** 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(!toolsAvailable)("rescue drops directory-target reindex symlinks", () => {
+  let workDir: string;
+  let upstream: string;
+  let shimDir: string;
+  let floorSha: string;
+  let env: NodeJS.ProcessEnv;
+
+  const gitAt = (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",
+        GIT_AUTHOR_DATE: `${EPOCH} +0000`,
+        GIT_COMMITTER_DATE: `${EPOCH} +0000`,
+      },
+    })
+      .toString()
+      .trim();
+
+  beforeAll(() => {
+    workDir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-rescue-dirsymlink-"));
+
+    // --- "upstream" repo: a single core/ file so the wipe set includes core/ --
+    upstream = path.join(workDir, "upstream");
+    fs.mkdirSync(path.join(upstream, "core/knowledge"), { recursive: true });
+    gitAt(workDir, "init", "-b", "main", "upstream");
+    fs.writeFileSync(path.join(upstream, "core/knowledge/README.md"), "shipped\n");
+    gitAt(upstream, "add", "-A");
+    gitAt(upstream, "commit", "-m", "floor");
+    floorSha = gitAt(upstream, "rev-parse", "HEAD");
+
+    // --- git shim: redirect `git clone <github-url>` to the local 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 ?? ""}` };
+  });
+
+  afterAll(() => {
+    if (workDir) fs.rmSync(workDir, { recursive: true, force: true });
+  });
+
+  /**
+   * Build a fresh local HQ root carrying a directory-target reindex symlink
+   * (core/knowledge/ad-creative-engine -> <hqRoot>/personal/knowledge/ad-creative-engine),
+   * whose target directory holds a sentinel file that must survive the drop.
+   */
+  function makeHqRoot(): { hqRoot: string; link: string; targetDir: string; sentinel: string } {
+    const hqRoot = fs.mkdtempSync(path.join(workDir, "hq-"));
+    // HQ-root shape check: companies/ + one of .claude/|core/|personal/.
+    fs.mkdirSync(path.join(hqRoot, "companies"), { recursive: true });
+    fs.mkdirSync(path.join(hqRoot, "core/knowledge"), { recursive: true });
+    // Unchanged vs upstream so the overlay is a no-op for it.
+    fs.writeFileSync(path.join(hqRoot, "core/knowledge/README.md"), "shipped\n");
+
+    const targetDir = path.join(hqRoot, "personal/knowledge/ad-creative-engine");
+    fs.mkdirSync(targetDir, { recursive: true });
+    const sentinel = path.join(targetDir, "brief.md");
+    fs.writeFileSync(sentinel, "authored locally\n");
+
+    const link = path.join(hqRoot, "core/knowledge/ad-creative-engine");
+    // Absolute target that includes "/personal/" — matches the overlay
+    // convention masterSyncSymlinkTarget() recognizes.
+    fs.symlinkSync(targetDir, link);
+
+    return { hqRoot, link, targetDir, sentinel };
+  }
+
+  function rescueArgs(hqRoot: string): string[] {
+    return [
+      "--hq-root", hqRoot,
+      "--source", "test/repo",
+      "--ref", "main",
+      "--floor-sha", floorSha,
+      "--yes",
+      "--no-backup",
+    ];
+  }
+
+  it("sanity: the mocked rmSync reproduces the macOS EISDIR on a dir-target symlink", () => {
+    const { link, targetDir, sentinel } = makeHqRoot();
+    // The old apply path used exactly this call — it must throw under the fault.
+    expect(() => fs.rmSync(link, { force: true })).toThrow(/Path is a directory/);
+    // ...and the fixed path (unlink) removes the link while sparing the target.
+    fs.unlinkSync(link);
+    expect(fs.existsSync(link)).toBe(false);
+    expect(fs.existsSync(targetDir)).toBe(true);
+    expect(fs.readFileSync(sentinel, "utf-8")).toBe("authored locally\n");
+  });
+
+  it("does not abort the apply on a directory-target symlink (drops it, spares the target)", () => {
+    const { hqRoot, link, targetDir, sentinel } = makeHqRoot();
+
+    const r = runRescueCapture(rescueArgs(hqRoot), env);
+
+    // The apply must survive the simulated-macOS rmSync fault: the fix removes
+    // the link with unlink semantics, so the whole update no longer rolls back.
+    // (The old rmSync-based drop throws EISDIR here → non-zero + rollback.)
+    if (r.status !== 0) {
+      throw new Error(`rescue aborted on the dir-target symlink (${r.status}):\n${r.stdout}\n${r.stderr}`);
+    }
+
+    // The link itself is gone (reindex.sh re-lays it later)...
+    expect(fs.existsSync(link)).toBe(false);
+    // ...but the target directory and its contents are untouched — the drop
+    // must never follow/recurse into the target.
+    expect(fs.existsSync(targetDir)).toBe(true);
+    expect(fs.readFileSync(sentinel, "utf-8")).toBe("authored locally\n");
+  });
+});