@indigoai-us/hq-cloud 6.14.18 → 6.14.19

package/src/qmd-reindex.ts

@@ -24,27 +24,293 @@
  *
  * The index itself is never synced — it is large, binary, and embeds absolute
  * local paths. Only its *freshness* is automated here.
+ *
+ * ## Corruption safety (feedback_b9a369ff)
+ *
+ * The qmd store (`.qmd/index.sqlite`, backed by a sqlite-vec virtual table) was
+ * being corrupted on the vector side (`content_vectors` / `vectors_vec_rowids`)
+ * because TWO uncoordinated writers raced on it: this post-sync reindex and an
+ * interactive session's own qmd maintenance (e.g. a skill's `qmd embed`). Two
+ * defects compounded:
+ *   1. A hard 120s `spawnSync` timeout that KILLED a long `qmd update`/`embed`
+ *      mid-write, tearing down the process between vector-table writes.
+ *   2. No cross-process serialization, so an interactive `qmd embed` and a
+ *      runner-spawned `qmd update` overlapped with near certainty.
+ *
+ * The mitigations here, all inside the runner so every teammate gets them on
+ * their next sync:
+ *   - The exec timeout is raised substantially so a legitimate long pass is no
+ *     longer killed mid-write in the first place. A timed-out pass is treated as
+ *     "not done" (left dirty, retried next cycle) and NEVER advances to embed.
+ *     That not-done handling — together with the writer serialization below — is
+ *     the real protection; the signal used for the (now rare) kill is secondary.
+ *     When the bound does fire the child is sent SIGINT rather than the default
+ *     SIGTERM, but qmd 2.5.3 traps both identically (each just restores the
+ *     cursor and exits), so this is only the same clean exit path qmd takes on
+ *     Ctrl-C — not a guarantee the in-flight SQLite write unwinds.
+ *   - A shared advisory lock at `<hqRoot>/.qmd/.reindex.lock` serializes qmd
+ *     writers. The runner takes it before touching qmd and SKIPS the cycle (and
+ *     marks the tree dirty so the next sync retries) when another writer holds
+ *     it. The lock path sits next to the DB so interactive HQ qmd maintenance
+ *     can honor the same rendezvous.
+ *   - Corruption is detected cheaply from qmd's own output (the SQLITE_CORRUPT
+ *     signature). On detection the corrupt DB files are quarantined aside (moved
+ *     to `index.sqlite.corrupt-<ts>`, never deleted) and the cycle stops writing
+ *     so a clean rebuild happens on the next pass — instead of writing further
+ *     onto an already-damaged store.
  */
 
 import * as fs from "fs";
 import * as path from "path";
 import { spawnSync } from "child_process";
 
+/** Result of a single `qmd` invocation. */
+export interface QmdExecResult {
+  status: number | null;
+  stdout: string;
+  /** Captured stderr (qmd prints SQLITE_CORRUPT errors here). Optional for fakes. */
+  stderr?: string;
+  /** True when the process was killed because it exceeded the exec timeout. */
+  timedOut?: boolean;
+}
+
 /** Injectable command runner — real `spawnSync` in prod, a fake in tests. */
 export interface QmdExec {
-  (args: string[]): { status: number | null; stdout: string };
+  (args: string[]): QmdExecResult;
+}
+
+/**
+ * Default exec timeout for a single `qmd` invocation. The historical 120s bound
+ * routinely killed `qmd update`/`qmd embed` mid-write on a large index (the HQ
+ * root's `hq` collection alone spans the whole tree), which corrupted the vector
+ * store. 15 minutes comfortably covers a cold or embed-heavy pass, so the bound
+ * effectively stops firing on legitimate work; a genuinely wedged process is
+ * still bounded, and a timed-out pass is treated as not-done (never written
+ * further onto) — see {@link defaultExec} and {@link reindexAfterSync}.
+ */
+export const DEFAULT_QMD_EXEC_TIMEOUT_MS = 900_000;
+
+/** Resolve the exec timeout, honoring `HQ_QMD_EXEC_TIMEOUT_MS` (ms) if valid. */
+export function resolveExecTimeoutMs(env: NodeJS.ProcessEnv = process.env): number {
+  const raw = env.HQ_QMD_EXEC_TIMEOUT_MS;
+  if (raw !== undefined && raw !== "") {
+    const n = Number(raw);
+    if (Number.isFinite(n) && n > 0) return Math.round(n);
+  }
+  return DEFAULT_QMD_EXEC_TIMEOUT_MS;
 }
 
 const defaultExec: QmdExec = (args) => {
   const res = spawnSync("qmd", args, {
     encoding: "utf8",
-    // qmd update on a large index can take a while; bound it so a wedged
-    // index never hangs the runner forever.
-    timeout: 120_000,
+    // Bound so a wedged index never hangs the runner forever, but generously —
+    // see DEFAULT_QMD_EXEC_TIMEOUT_MS.
+    timeout: resolveExecTimeoutMs(),
+    // On timeout send SIGINT instead of the default SIGTERM. NOTE: qmd 2.5.3
+    // traps BOTH identically — each handler only restores the cursor and calls
+    // process.exit() — so SIGINT is NOT inherently a graceful transaction
+    // unwind; it is simply the same exit path qmd takes on Ctrl-C. The real
+    // write-safety guarantee is the raised bound above (a kill is now rare) plus
+    // treating a timed-out pass as not-done and never embedding after it (see
+    // reindexAfterSync). SIGINT is kept only so a killed pass exits qmd's normal
+    // way rather than via an unhandled default signal.
+    killSignal: "SIGINT",
+  });
+  const timedOut =
+    res.error != null &&
+    (res.error as NodeJS.ErrnoException).code === "ETIMEDOUT";
+  return {
+    status: res.status,
+    stdout: res.stdout ?? "",
+    stderr: res.stderr ?? "",
+    timedOut,
+  };
+};
+
+/** SQLite corruption signature qmd surfaces when the vector store is damaged. */
+const CORRUPTION_SIGNATURE = /SQLITE_CORRUPT|database disk image is malformed/i;
+
+/** True if a qmd result reports SQLite corruption on stdout or stderr. */
+export function looksCorrupt(r: Partial<Pick<QmdExecResult, "stdout" | "stderr">>): boolean {
+  return CORRUPTION_SIGNATURE.test(`${r.stdout ?? ""}\n${r.stderr ?? ""}`);
+}
+
+/** Handle returned by an acquired reindex lock. `release()` is idempotent. */
+export interface ReindexLockHandle {
+  release(): void;
+}
+
+/**
+ * Acquire the shared reindex lock at `lockPath`. Returns a handle when acquired,
+ * or `null` when another live writer already holds it (caller should skip the
+ * cycle). Must never throw — coordination is advisory and must not fail a sync.
+ */
+export type AcquireReindexLock = (lockPath: string) => ReindexLockHandle | null;
+
+/**
+ * How long a lock file may sit before a new acquirer treats it as abandoned and
+ * reclaims it, even if its recorded PID can't be probed (e.g. a different user,
+ * or a torn/empty file). Backstops the PID-liveness check for the crash case.
+ */
+const DEFAULT_LOCK_STALE_MS = 30 * 60_000;
+
+function reindexLockStaleMs(env: NodeJS.ProcessEnv = process.env): number {
+  const raw = env.HQ_QMD_LOCK_STALE_MS;
+  if (raw !== undefined && raw !== "") {
+    const n = Number(raw);
+    if (Number.isFinite(n) && n >= 0) return Math.round(n);
+  }
+  return DEFAULT_LOCK_STALE_MS;
+}
+
+const NOOP_LOCK: ReindexLockHandle = { release() {} };
+
+// Track locks this process holds so a clean exit/signal removes them; a crash is
+// covered by the stale/PID reclaim path in the acquirer.
+const heldReindexLocks = new Set<string>();
+let reindexExitHookInstalled = false;
+
+function installReindexExitHookOnce(): void {
+  if (reindexExitHookInstalled) return;
+  reindexExitHookInstalled = true;
+  process.on("exit", () => {
+    for (const p of heldReindexLocks) unlinkIfOwned(p);
+  });
+}
+
+/** Is `pid` a live process? ESRCH → dead; EPERM/other → conservatively alive. */
+function pidAlive(pid: number): boolean {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return (err as NodeJS.ErrnoException)?.code !== "ESRCH";
+  }
+}
+
+/** Unlink `lockPath` only if it still records THIS process as the holder. */
+function unlinkIfOwned(lockPath: string): void {
+  try {
+    const info = JSON.parse(fs.readFileSync(lockPath, "utf8")) as { pid?: number };
+    if (info?.pid !== process.pid) return;
+  } catch {
+    // Unreadable/torn/already-gone — don't risk clobbering another holder.
+    return;
+  }
+  try {
+    fs.unlinkSync(lockPath);
+  } catch {
+    /* already gone — fine */
+  }
+}
+
+/**
+ * If the lock at `lockPath` is held by a dead PID or is older than the stale
+ * bound, unlink it so the caller can retry. Returns true when it reclaimed (or
+ * the lock vanished mid-check), false when a live, fresh holder still owns it.
+ */
+function reclaimReindexLockIfStale(lockPath: string): boolean {
+  let st: fs.Stats;
+  try {
+    st = fs.statSync(lockPath);
+  } catch {
+    // Vanished between EEXIST and stat → the holder released; let caller retry.
+    return true;
+  }
+  let holderPid = 0;
+  try {
+    const info = JSON.parse(fs.readFileSync(lockPath, "utf8")) as { pid?: number };
+    if (typeof info?.pid === "number") holderPid = info.pid;
+  } catch {
+    /* torn/empty lock — fall through to the staleness check */
+  }
+  const dead = holderPid > 0 && !pidAlive(holderPid);
+  const stale = Date.now() - st.mtimeMs > reindexLockStaleMs();
+  if (dead || stale) {
+    try {
+      fs.unlinkSync(lockPath);
+    } catch {
+      // Someone else reclaimed it first; the next create attempt re-evaluates.
+    }
+    return true;
+  }
+  return false;
+}
+
+const defaultAcquireReindexLock: AcquireReindexLock = (lockPath) => {
+  // Escape hatch: a caller that manages exclusion itself can disable the lock.
+  if (process.env.HQ_QMD_REINDEX_LOCK === "0") return NOOP_LOCK;
+
+  const payload = JSON.stringify({
+    pid: process.pid,
+    startedAt: new Date().toISOString(),
+    command: "hq-cloud qmd-reindex",
   });
-  return { status: res.status, stdout: res.stdout ?? "" };
+
+  // At most one reclaim + one retry: acquire, or (if stale) reclaim then retry.
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+      const fd = fs.openSync(lockPath, "wx", 0o600);
+      try {
+        fs.writeSync(fd, payload);
+      } finally {
+        fs.closeSync(fd);
+      }
+      heldReindexLocks.add(lockPath);
+      installReindexExitHookOnce();
+      return {
+        release() {
+          heldReindexLocks.delete(lockPath);
+          unlinkIfOwned(lockPath);
+        },
+      };
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException)?.code !== "EEXIST") {
+        // The `.qmd` dir isn't writable (unusual — it holds the DB). Fail OPEN
+        // rather than block the reindex on an infra problem: proceed without the
+        // advisory lock. The corruption guard below is the remaining backstop.
+        return NOOP_LOCK;
+      }
+      // Held. Reclaim iff the holder is dead/stale, then retry once.
+      if (reclaimReindexLockIfStale(lockPath)) continue;
+      return null; // live, fresh holder → skip this cycle
+    }
+  }
+  return null;
 };
 
+/** Move corrupt DB files aside (never delete) so a clean rebuild can follow. */
+export type QuarantineCorruptIndex = (
+  qmdDir: string,
+  timestampSuffix: string,
+) => string | null;
+
+const CORRUPTIBLE_DB_FILES = ["index.sqlite", "index.sqlite-wal", "index.sqlite-shm"];
+
+const defaultQuarantineCorruptIndex: QuarantineCorruptIndex = (qmdDir, tsSuffix) => {
+  let movedBase: string | null = null;
+  for (const name of CORRUPTIBLE_DB_FILES) {
+    const src = path.join(qmdDir, name);
+    try {
+      if (!fs.existsSync(src)) continue;
+      const dest = `${src}.corrupt-${tsSuffix}`;
+      fs.renameSync(src, dest);
+      if (name === "index.sqlite") movedBase = dest;
+    } catch {
+      // Best-effort: move what we can. A file we can't move is left in place;
+      // the corruption guard still prevents further writes this cycle.
+    }
+  }
+  return movedBase;
+};
+
+/** Filesystem-safe timestamp suffix for a quarantined DB file. */
+function quarantineSuffix(nowMs: number): string {
+  return new Date(nowMs).toISOString().replace(/[:.]/g, "-");
+}
+
 const DEFAULT_CHANGED_PATH_DEBOUNCE_MS = 60_000;
 
 export interface ReindexOptions {
@@ -71,6 +337,10 @@ export interface ReindexOptions {
   readCompanies?: (companiesDir: string) => string[];
   /** Returns true if the knowledge dir has at least one indexable .md file. */
   hasIndexableMarkdown?: (knowledgeDir: string) => boolean;
+  /** Reindex-lock acquirer override for tests. */
+  acquireReindexLock?: AcquireReindexLock;
+  /** Corrupt-index quarantine override for tests. */
+  quarantineCorruptIndex?: QuarantineCorruptIndex;
   /** Optional diagnostic sink for unexpected swallowed failures. */
   log?: (diagnostic: {
     event: string;
@@ -80,6 +350,20 @@ export interface ReindexOptions {
   }) => void;
 }
 
+export interface ReindexResult {
+  qmdAvailable: boolean;
+  collectionsAdded: string[];
+  updated: boolean;
+  embedded: boolean;
+  pendingDirty: boolean;
+  /** True when the cycle was skipped because another writer held the lock. */
+  lockBusy: boolean;
+  /** True when a qmd command exceeded the exec timeout and was aborted. */
+  timedOut: boolean;
+  /** True when a corrupt index was detected and quarantined this cycle. */
+  corruptionQuarantined: boolean;
+}
+
 /**
  * Reindex qmd for an HQ tree after a sync. Never throws — all failures are
  * swallowed so a reindex problem can never mask or fail the sync result.
@@ -89,21 +373,20 @@ export interface ReindexOptions {
 export function reindexAfterSync(
   hqRoot: string,
   opts: ReindexOptions = {},
-): {
-  qmdAvailable: boolean;
-  collectionsAdded: string[];
-  updated: boolean;
-  embedded: boolean;
-  pendingDirty: boolean;
-} {
+): ReindexResult {
   const exec = opts.exec ?? defaultExec;
   const existsSync = opts.existsSync ?? fs.existsSync;
-  const result = {
+  const acquireLock = opts.acquireReindexLock ?? defaultAcquireReindexLock;
+  const quarantine = opts.quarantineCorruptIndex ?? defaultQuarantineCorruptIndex;
+  const result: ReindexResult = {
     qmdAvailable: false,
-    collectionsAdded: [] as string[],
+    collectionsAdded: [],
     updated: false,
     embedded: false,
     pendingDirty: false,
+    lockBusy: false,
+    timedOut: false,
+    corruptionQuarantined: false,
   };
 
   try {
@@ -125,75 +408,109 @@ export function reindexAfterSync(
       return result;
     }
 
-    // Guard: qmd must be installed. `qmd collection list` doubles as the
-    // availability probe AND the source for which collections already exist.
-    const list = exec(["collection", "list"]);
-    if (list.status !== 0) return result; // qmd absent or errored — no-op
-    result.qmdAvailable = true;
-    const existingCollections = list.stdout;
-
-    // 1. Auto-register missing company knowledge collections.
-    if (registrationMayBeStale) {
-      const companiesDir = path.join(hqRoot, "companies");
-      const slugs = (opts.readCompanies ?? defaultReadCompanies)(companiesDir);
-      for (const slug of slugs) {
-        const knowledgeDir = path.join(companiesDir, slug, "knowledge");
-        if (!existsSync(knowledgeDir)) continue;
-        const hasMd = (opts.hasIndexableMarkdown ?? defaultHasIndexableMarkdown)(knowledgeDir);
-        if (!hasMd) continue;
-        // Already registered? qmd collection URIs look like `qmd://<slug>/`.
-        if (existingCollections.includes(`qmd://${slug}/`)) continue;
-
-        const add = exec(["collection", "add", knowledgeDir, "--name", slug, "--mask", "**/*.md"]);
-        if (add.status === 0) {
-          exec(["context", "add", `qmd://${slug}`, `Knowledge base for ${slug}.`]);
-          result.collectionsAdded.push(slug);
-        }
-      }
+    const nowMs = opts.nowMs ?? Date.now();
+    const pendingSinceMs =
+      pendingDirty && typeof state.pendingSinceMs === "number"
+        ? state.pendingSinceMs
+        : nowMs;
+
+    // Serialize qmd writers. If another writer (this runner from a prior cycle,
+    // or an interactive session's qmd maintenance) holds the lock, SKIP this
+    // cycle and mark the tree dirty so the next sync retries — never write onto
+    // the vector store concurrently (feedback_b9a369ff).
+    const lockPath = path.join(hqRoot, ".qmd", ".reindex.lock");
+    const lock = acquireLock(lockPath);
+    if (!lock) {
+      writeState(statePath, { ...state, pendingDirty: true, pendingSinceMs });
+      result.lockBusy = true;
+      result.pendingDirty = true;
+      return result;
     }
 
-    // 2. Incremental lexical reindex.
-    const shouldUpdate = dirtyFromChanges || pendingDirty;
-    if (shouldUpdate) {
-      const nowMs = opts.nowMs ?? Date.now();
-      const debounceMs =
-        opts.debounceMs ??
-        (changedPaths === undefined ? 0 : DEFAULT_CHANGED_PATH_DEBOUNCE_MS);
-      const pendingSinceMs =
-        pendingDirty && typeof state.pendingSinceMs === "number"
-          ? state.pendingSinceMs
-          : nowMs;
-      if (debounceMs > 0 && nowMs - pendingSinceMs < debounceMs) {
-        writeState(statePath, {
-          ...state,
-          pendingDirty: true,
-          pendingSinceMs,
-        });
-        result.pendingDirty = true;
+    try {
+      // Guard: qmd must be installed. `qmd collection list` doubles as the
+      // availability probe AND the source for which collections already exist.
+      const list = exec(["collection", "list"]);
+      if (list.status !== 0) return result; // qmd absent or errored — no-op
+      // An already-corrupt store can surface here even on the lexical side.
+      if (looksCorrupt(list)) {
+        handleCorruption(hqRoot, statePath, state, pendingSinceMs, nowMs, quarantine, result);
         return result;
       }
+      result.qmdAvailable = true;
+      const existingCollections = list.stdout;
+
+      // 1. Auto-register missing company knowledge collections.
+      if (registrationMayBeStale) {
+        const companiesDir = path.join(hqRoot, "companies");
+        const slugs = (opts.readCompanies ?? defaultReadCompanies)(companiesDir);
+        for (const slug of slugs) {
+          const knowledgeDir = path.join(companiesDir, slug, "knowledge");
+          if (!existsSync(knowledgeDir)) continue;
+          const hasMd = (opts.hasIndexableMarkdown ?? defaultHasIndexableMarkdown)(knowledgeDir);
+          if (!hasMd) continue;
+          // Already registered? qmd collection URIs look like `qmd://<slug>/`.
+          if (existingCollections.includes(`qmd://${slug}/`)) continue;
 
-      const update = exec(["update"]);
-      result.updated = update.status === 0;
-      if (result.updated) {
-        writeState(statePath, {
-          pendingDirty: false,
-          lastSuccessMs: nowMs,
-        });
-      } else {
-        writeState(statePath, {
-          ...state,
-          pendingDirty: true,
-          pendingSinceMs,
-        });
-        result.pendingDirty = true;
+          const add = exec(["collection", "add", knowledgeDir, "--name", slug, "--mask", "**/*.md"]);
+          if (add.status === 0) {
+            exec(["context", "add", `qmd://${slug}`, `Knowledge base for ${slug}.`]);
+            result.collectionsAdded.push(slug);
+          }
+        }
       }
-    }
 
-    // 3. Embeddings only on explicit request.
-    if (opts.embed) {
-      const embed = exec(["embed"]);
-      result.embedded = embed.status === 0;
+      // 2. Incremental lexical reindex.
+      const shouldUpdate = dirtyFromChanges || pendingDirty;
+      if (shouldUpdate) {
+        const debounceMs =
+          opts.debounceMs ??
+          (changedPaths === undefined ? 0 : DEFAULT_CHANGED_PATH_DEBOUNCE_MS);
+        if (debounceMs > 0 && nowMs - pendingSinceMs < debounceMs) {
+          writeState(statePath, { ...state, pendingDirty: true, pendingSinceMs });
+          result.pendingDirty = true;
+          return result;
+        }
+
+        const update = exec(["update"]);
+        if (looksCorrupt(update)) {
+          handleCorruption(hqRoot, statePath, state, pendingSinceMs, nowMs, quarantine, result);
+          return result;
+        }
+        if (update.timedOut) {
+          // Aborted mid-pass by the timeout. Do NOT treat as done and do NOT
+          // proceed to embed — mark dirty and retry cleanly next cycle.
+          writeState(statePath, { ...state, pendingDirty: true, pendingSinceMs });
+          result.timedOut = true;
+          result.pendingDirty = true;
+          return result;
+        }
+        result.updated = update.status === 0;
+        if (result.updated) {
+          writeState(statePath, { pendingDirty: false, lastSuccessMs: nowMs });
+        } else {
+          writeState(statePath, { ...state, pendingDirty: true, pendingSinceMs });
+          result.pendingDirty = true;
+        }
+      }
+
+      // 3. Embeddings only on explicit request.
+      if (opts.embed) {
+        const embed = exec(["embed"]);
+        if (looksCorrupt(embed)) {
+          handleCorruption(hqRoot, statePath, state, pendingSinceMs, nowMs, quarantine, result);
+          return result;
+        }
+        if (embed.timedOut) {
+          writeState(statePath, { ...state, pendingDirty: true, pendingSinceMs });
+          result.timedOut = true;
+          result.pendingDirty = true;
+          return result;
+        }
+        result.embedded = embed.status === 0;
+      }
+    } finally {
+      lock.release();
     }
   } catch (err) {
     try {
@@ -212,6 +529,27 @@ export function reindexAfterSync(
   return result;
 }
 
+/**
+ * Quarantine the corrupt DB aside and mark the tree dirty so the NEXT cycle
+ * rebuilds from scratch under the lock, instead of writing further onto an
+ * already-damaged vector store. Mutates `result` in place.
+ */
+function handleCorruption(
+  hqRoot: string,
+  statePath: string,
+  state: QmdReindexState,
+  pendingSinceMs: number,
+  nowMs: number,
+  quarantine: QuarantineCorruptIndex,
+  result: ReindexResult,
+): void {
+  const qmdDir = path.join(hqRoot, ".qmd");
+  quarantine(qmdDir, quarantineSuffix(nowMs));
+  writeState(statePath, { ...state, pendingDirty: true, pendingSinceMs });
+  result.corruptionQuarantined = true;
+  result.pendingDirty = true;
+}
+
 interface QmdReindexState {
   pendingDirty?: boolean;
   pendingSinceMs?: number;

package/src/s3.test.ts

@@ -95,6 +95,7 @@ import {
   FILE_BTIME_META_KEY,
   classifyVaultKey,
   validateVaultUploadKey,
+  createStagedSymlink,
   replaceStagedPath,
   sweepStaleStagedFiles,
 } from "./s3.js";
@@ -733,6 +734,84 @@ describe("uploadSymlink", () => {
   });
 });
 
+describe("createStagedSymlink", () => {
+  it("uses an absolute junction for a Windows directory without requiring symlink privilege", () => {
+    const linkPath = path.join(path.sep, "vault", ".agents", "skills");
+    const target = "../.claude/skills";
+    const absTarget = path.resolve(path.dirname(linkPath), target);
+    const symlink = vi.fn(
+      (_target: string, _linkPath: string, type?: fs.symlink.Type) => {
+        if (type !== "junction") {
+          throw Object.assign(new Error("operation not permitted, symlink"), {
+            code: "EPERM",
+          });
+        }
+      },
+    );
+
+    expect(() =>
+      createStagedSymlink(target, linkPath, {
+        platform: "win32",
+        symlink,
+        statIsDirectory: () => true,
+      }),
+    ).not.toThrow();
+    expect(symlink).toHaveBeenCalledWith(absTarget, linkPath, "junction");
+    expect(path.isAbsolute(symlink.mock.calls[0]![0])).toBe(true);
+  });
+
+  it("resolves a relative Windows overlay target before creating a junction", () => {
+    const linkPath = path.join(path.sep, "vault", ".codex", "claude");
+    const target = "../.claude/skills";
+    const symlink = vi.fn();
+
+    createStagedSymlink(target, linkPath, {
+      platform: "win32",
+      symlink,
+      statIsDirectory: () => undefined,
+    });
+
+    expect(symlink).toHaveBeenCalledWith(
+      path.resolve(path.dirname(linkPath), target),
+      linkPath,
+      "junction",
+    );
+  });
+
+  it("preserves a relative target and omits the type outside Windows", () => {
+    const linkPath = path.join(path.sep, "vault", ".agents", "skills");
+    const target = "../.claude/skills";
+    const symlink = vi.fn();
+    const statIsDirectory = vi.fn(() => true);
+
+    createStagedSymlink(target, linkPath, {
+      platform: "linux",
+      symlink,
+      statIsDirectory,
+    });
+
+    expect(symlink).toHaveBeenCalledWith(target, linkPath);
+    expect(statIsDirectory).not.toHaveBeenCalled();
+  });
+
+  it("uses a genuine Windows file symlink for a regular-file target", () => {
+    const linkPath = path.join(path.sep, "vault", "config-link.json");
+    const target = "../shared/config.json";
+    const absTarget = path.resolve(path.dirname(linkPath), target);
+    const symlink = vi.fn();
+    const statIsDirectory = vi.fn(() => false);
+
+    createStagedSymlink(target, linkPath, {
+      platform: "win32",
+      symlink,
+      statIsDirectory,
+    });
+
+    expect(statIsDirectory).toHaveBeenCalledWith(absTarget);
+    expect(symlink).toHaveBeenCalledWith(target, linkPath, "file");
+  });
+});
+
 describe("downloadFile", () => {
   let tmpRoot: string;