@indigoai-us/hq-cloud 6.14.12 → 6.14.14

package/src/cli/reindex.test.ts

@@ -4,8 +4,8 @@
  *
  * The logic is implemented natively in TypeScript in ./reindex.ts; these tests
  * exercise reindex() directly against a temp HQ tree, asserting the observable
- * filesystem outcomes (skill wrappers, personal-overlay mirroring) rather than
- * re-deriving the implementation internals.
+ * filesystem outcomes (skill wrappers, retired personal-overlay mirror cleanup)
+ * rather than re-deriving the implementation internals.
  */
 
 import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
@@ -112,26 +112,29 @@ describe("reindex", () => {
     );
   });
 
-  it("mirrors the personal overlay into core/<type>/", () => {
+  it("does NOT mirror the personal overlay into core/<type>/ (read directly now)", () => {
     fs.mkdirSync(path.join(root, "personal/policies"), { recursive: true });
     fs.writeFileSync(path.join(root, "personal/policies/myrule.md"), "rule\n");
 
     const { status } = reindex({ repoRoot: root });
     expect(status).toBe(0);
 
-    const link = path.join(root, "core/policies/myrule.md");
-    expect(fs.lstatSync(link).isSymbolicLink()).toBe(true);
-    expect(fs.readlinkSync(link)).toBe("../../personal/policies/myrule.md");
+    // personal is the sole read source — reindex must NOT create a mirror
+    // symlink in core/policies. The HQ tooling reads personal/policies directly,
+    // so a mirror would only double-surface every entry.
+    expect(fs.existsSync(path.join(root, "core/policies/myrule.md"))).toBe(false);
   });
 
-  it("collapses per-file overlay-skip spam into ONE summary line (HQ-SYNC-2)", () => {
-    // A REAL core file sits where an overlay symlink would go — the legitimate
-    // no-op that used to spam one stderr line per entry and flood the Sentry
-    // breadcrumb ring, evicting the real per-company sync error.
-    fs.mkdirSync(path.join(root, "personal/policies"), { recursive: true });
-    fs.writeFileSync(path.join(root, "personal/policies/collide.md"), "rule\n");
-    fs.mkdirSync(path.join(root, "core/policies"), { recursive: true });
-    fs.writeFileSync(path.join(root, "core/policies/collide.md"), "REAL core file\n");
+  it("collapses per-file wrapper-skip spam into ONE summary line (HQ-SYNC-2)", () => {
+    // A REAL file sits where a managed skill-wrapper symlink would go — the
+    // legitimate no-op that used to spam one stderr line per entry and flood the
+    // Sentry breadcrumb ring, evicting the real per-company sync error.
+    writeSkill("core/skills/demo");
+    reindex({ repoRoot: root });
+    // Replace the managed per-file symlink with a real (non-symlink) file.
+    const slot = path.join(root, ".claude/skills/core:demo/SKILL.md");
+    fs.rmSync(slot);
+    fs.writeFileSync(slot, "REAL file, not a link\n");
 
     const writes: string[] = [];
     const spy = vi
@@ -150,7 +153,7 @@ describe("reindex", () => {
 
     expect(status).toBe(0);
     // The pre-existing real file is left untouched (never overwritten).
-    expect(fs.lstatSync(path.join(root, "core/policies/collide.md")).isSymbolicLink()).toBe(false);
+    expect(fs.lstatSync(slot).isSymbolicLink()).toBe(false);
     // No per-file spam…
     expect(stderr).not.toContain("already exists and is not a symlink; skipping");
     // …just ONE collapsed summary naming the count.
@@ -158,11 +161,12 @@ describe("reindex", () => {
     expect(stderr).toContain("HQ_REINDEX_VERBOSE=1");
   });
 
-  it("keeps per-file overlay-skip detail under HQ_REINDEX_VERBOSE=1", () => {
-    fs.mkdirSync(path.join(root, "personal/policies"), { recursive: true });
-    fs.writeFileSync(path.join(root, "personal/policies/collide.md"), "rule\n");
-    fs.mkdirSync(path.join(root, "core/policies"), { recursive: true });
-    fs.writeFileSync(path.join(root, "core/policies/collide.md"), "REAL\n");
+  it("keeps per-file wrapper-skip detail under HQ_REINDEX_VERBOSE=1", () => {
+    writeSkill("core/skills/demo");
+    reindex({ repoRoot: root });
+    const slot = path.join(root, ".claude/skills/core:demo/SKILL.md");
+    fs.rmSync(slot);
+    fs.writeFileSync(slot, "REAL\n");
 
     const writes: string[] = [];
     const spy = vi
@@ -180,7 +184,7 @@ describe("reindex", () => {
     }
     const stderr = writes.join("");
     expect(stderr).toContain(
-      "core/policies/collide.md already exists and is not a symlink; skipping",
+      ".claude/skills/core:demo/SKILL.md already exists and is not a symlink; skipping",
     );
   });
 
@@ -203,75 +207,55 @@ describe("reindex", () => {
     ).toBe("../../../core/skills/demo/SKILL.md");
   });
 
-  // ── Cleanup pass C: orphan personal-overlay mirror symlinks ──────────────
-  // The mirror creates core/<type>/<entry> -> ../../personal/<type>/<entry>.
-  // When the personal source is later deleted/renamed, the next reindex must
-  // prune the now-dangling core symlink — the gap that used to leave a retired
-  // personal policy pointer surfacing in core/policies/ until hand-deleted.
+  // ── Migration cleanup: retired personal-overlay mirror symlinks ──────────
+  // reindex no longer CREATES core/<type>/<entry> -> ../../personal/<type>/<entry>
+  // mirror symlinks — personal is read directly. A managed mirror symlink a
+  // PRIOR release left behind must be pruned on the next reindex, WHETHER OR NOT
+  // its personal source still exists, so it can never double-surface alongside
+  // the direct read.
+
+  // Forge a legacy managed mirror symlink exactly as the old reindex would have.
+  function legacyMirror(type: string, entry: string): string {
+    const coreDir = path.join(root, "core", type);
+    fs.mkdirSync(coreDir, { recursive: true });
+    const link = path.join(coreDir, entry);
+    fs.symlinkSync(`../../personal/${type}/${entry}`, link);
+    return link;
+  }
 
-  it("prunes an orphan personal-overlay mirror symlink when the source is deleted", () => {
+  it("prunes a legacy mirror symlink even when its personal source still exists", () => {
     fs.mkdirSync(path.join(root, "personal/policies"), { recursive: true });
     fs.writeFileSync(path.join(root, "personal/policies/myrule.md"), "rule\n");
-    reindex({ repoRoot: root });
-    const link = path.join(root, "core/policies/myrule.md");
+    const link = legacyMirror("policies", "myrule.md");
     expect(fs.lstatSync(link).isSymbolicLink()).toBe(true);
 
-    // Retire the personal source, then reindex again.
-    fs.rmSync(path.join(root, "personal/policies/myrule.md"));
     expect(reindex({ repoRoot: root }).status).toBe(0);
 
-    // The dangling mirror symlink is gone — no entry at all (lstat throws).
+    // Pruned — personal/policies/myrule.md is read directly now, no mirror.
     expect(fs.existsSync(link)).toBe(false);
     expect(() => fs.lstatSync(link)).toThrow();
+    // The personal source itself is untouched.
+    expect(fs.existsSync(path.join(root, "personal/policies/myrule.md"))).toBe(true);
   });
 
-  it("prunes mirror symlinks when the ENTIRE personal/<type>/ directory is removed", () => {
-    fs.mkdirSync(path.join(root, "personal/policies"), { recursive: true });
-    fs.writeFileSync(path.join(root, "personal/policies/a.md"), "a\n");
-    fs.writeFileSync(path.join(root, "personal/policies/b.md"), "b\n");
-    reindex({ repoRoot: root });
-    expect(fs.lstatSync(path.join(root, "core/policies/a.md")).isSymbolicLink()).toBe(true);
-    expect(fs.lstatSync(path.join(root, "core/policies/b.md")).isSymbolicLink()).toBe(true);
+  it("prunes a legacy mirror symlink whose personal source was deleted", () => {
+    const link = legacyMirror("policies", "gone.md"); // dangling: no source
+    expect(fs.lstatSync(link).isSymbolicLink()).toBe(true);
 
-    // Nuke the whole personal/policies dir (the creation loop's isDir guard would
-    // skip the type entirely — the prune must still run and clean both links).
-    fs.rmSync(path.join(root, "personal/policies"), { recursive: true, force: true });
     expect(reindex({ repoRoot: root }).status).toBe(0);
-
-    expect(fs.existsSync(path.join(root, "core/policies/a.md"))).toBe(false);
-    expect(fs.existsSync(path.join(root, "core/policies/b.md"))).toBe(false);
-  });
-
-  it("keeps a LIVE personal-overlay mirror symlink (only orphans are pruned)", () => {
-    fs.mkdirSync(path.join(root, "personal/policies"), { recursive: true });
-    fs.writeFileSync(path.join(root, "personal/policies/keep.md"), "keep\n");
-    fs.writeFileSync(path.join(root, "personal/policies/drop.md"), "drop\n");
-    reindex({ repoRoot: root });
-
-    // Retire only one source; the other stays live.
-    fs.rmSync(path.join(root, "personal/policies/drop.md"));
-    reindex({ repoRoot: root });
-
-    const keep = path.join(root, "core/policies/keep.md");
-    expect(fs.lstatSync(keep).isSymbolicLink()).toBe(true);
-    expect(fs.readlinkSync(keep)).toBe("../../personal/policies/keep.md");
-    expect(fs.readFileSync(keep, "utf-8")).toBe("keep\n");
-    expect(fs.existsSync(path.join(root, "core/policies/drop.md"))).toBe(false);
+    expect(fs.existsSync(link)).toBe(false);
   });
 
-  it("prunes an orphan personal-overlay mirror DIRECTORY symlink (DEV-1767 shape)", () => {
-    // personal/knowledge/<kb>/ mirrors as a directory symlink; deleting the kb
-    // must prune the dangling directory symlink too (rmSync on a symlink, not
-    // recursive into a resolved dir).
+  it("prunes a legacy mirror DIRECTORY symlink without recursing into the source (DEV-1767 shape)", () => {
     fs.mkdirSync(path.join(root, "personal/knowledge/my-kb"), { recursive: true });
     fs.writeFileSync(path.join(root, "personal/knowledge/my-kb/note.md"), "n\n");
-    reindex({ repoRoot: root });
-    const link = path.join(root, "core/knowledge/my-kb");
+    const link = legacyMirror("knowledge", "my-kb"); // directory-shaped symlink
     expect(fs.lstatSync(link).isSymbolicLink()).toBe(true);
 
-    fs.rmSync(path.join(root, "personal/knowledge/my-kb"), { recursive: true, force: true });
     expect(reindex({ repoRoot: root }).status).toBe(0);
     expect(fs.existsSync(link)).toBe(false);
+    // rmSync on the symlink must NOT recurse into the resolved directory.
+    expect(fs.existsSync(path.join(root, "personal/knowledge/my-kb/note.md"))).toBe(true);
   });
 
   it("leaves a real core file and a foreign symlink in core/<type>/ untouched (cross-check invariant)", () => {
@@ -369,24 +353,21 @@ describe("reindex", () => {
     expect(fs.readlinkSync(agentsLink)).toBe("../../../core/skills/demo/agents");
   });
 
-  it("mirrors a personal/<type> DIRECTORY entry as a directory symlink into core/ and preserves it", () => {
-    // personal/knowledge/<kb>/ is a directory of notes — the exact DEV-1767
-    // reindex artifact shape that rescue/update-hq used to choke on.
+  it("does NOT mirror a personal/<type> DIRECTORY entry into core/ (read directly now)", () => {
+    // personal/knowledge/<kb>/ is a directory of notes. It used to mirror as a
+    // core/ directory symlink (the DEV-1767 shape rescue/update-hq choked on).
+    // The mirror is retired: qmd indexes personal/knowledge directly, so reindex
+    // must leave core/knowledge alone — nothing to choke on anymore.
     fs.mkdirSync(path.join(root, "personal/knowledge/my-kb"), { recursive: true });
     fs.writeFileSync(path.join(root, "personal/knowledge/my-kb/note.md"), "owned by personal\n");
 
     expect(reindex({ repoRoot: root }).status).toBe(0);
 
-    const link = path.join(root, "core/knowledge/my-kb");
-    expect(fs.lstatSync(link).isSymbolicLink()).toBe(true);
-    expect(fs.readlinkSync(link)).toBe("../../personal/knowledge/my-kb");
-    expect(fs.statSync(link).isDirectory()).toBe(true);
-    expect(fs.readFileSync(path.join(link, "note.md"), "utf-8")).toBe("owned by personal\n");
-
-    // Idempotent re-run: existing directory symlink recognised, left in place.
-    expect(reindex({ repoRoot: root }).status).toBe(0);
-    expect(fs.readlinkSync(link)).toBe("../../personal/knowledge/my-kb");
-    expect(fs.readFileSync(path.join(link, "note.md"), "utf-8")).toBe("owned by personal\n");
+    expect(fs.existsSync(path.join(root, "core/knowledge/my-kb"))).toBe(false);
+    // The personal source is untouched.
+    expect(fs.readFileSync(path.join(root, "personal/knowledge/my-kb/note.md"), "utf-8")).toBe(
+      "owned by personal\n",
+    );
   });
 
   // ── operation lock: reindex uses a SEPARATE scope from sync/rescue ──────
@@ -497,22 +478,6 @@ describe("reindex", () => {
     }
   });
 
-  it("does not abort reindex when a core/<type> mirror mkdir fails", () => {
-    writeSkill("core/skills/demo");
-    fs.mkdirSync(path.join(root, "personal/knowledge/my-kb"), { recursive: true });
-    fs.writeFileSync(path.join(root, "personal/knowledge/my-kb/note.md"), "n\n");
-
-    hoisted.failMkdirContaining = path.join("core", "knowledge");
-    try {
-      expect(reindex({ repoRoot: root }).status).toBe(0);
-    } finally {
-      hoisted.failMkdirContaining = "";
-    }
-
-    // The mirror for the failed type is skipped; skill surfacing still happened.
-    expect(fs.existsSync(path.join(root, ".claude/skills/core:demo"))).toBe(true);
-  });
-
   // ── HQ-CLI-4: symlink creation is privileged on Windows. Without Developer
   //    Mode, fs.symlinkSync throws EPERM. The HQ-B0 work guarded every mkdir
   //    site but left the symlink sites unguarded, so `hq reindex` still aborted
@@ -536,28 +501,6 @@ describe("reindex", () => {
     ).toBe(false);
   });
 
-  it("does not abort reindex when a personal-mirror symlink fails with EPERM, and other work still runs", () => {
-    writeSkill("core/skills/demo");
-    fs.mkdirSync(path.join(root, "personal/knowledge/my-kb"), { recursive: true });
-    fs.writeFileSync(path.join(root, "personal/knowledge/my-kb/note.md"), "n\n");
-
-    // Fail ONLY the core/<type> personal-mirror symlinks; wrapper symlinks
-    // succeed, proving the skip is scoped and the reindex completes.
-    hoisted.failSymlinkContaining = path.join("core", "knowledge");
-    try {
-      expect(reindex({ repoRoot: root }).status).toBe(0);
-    } finally {
-      hoisted.failSymlinkContaining = "";
-    }
-
-    // The personal mirror was skipped (EPERM)...
-    expect(fs.existsSync(path.join(root, "core/knowledge/my-kb"))).toBe(false);
-    // ...but unaffected work still happened: the skill wrapper + its symlink.
-    expect(
-      fs.lstatSync(path.join(root, ".claude/skills/core:demo/SKILL.md")).isSymbolicLink(),
-    ).toBe(true);
-  });
-
   // --- multi-harness session-log capture into workspace/.session-logs/<harness>/
   describe("session-log capture", () => {
     let claudeDir: string; // CLAUDE_CONFIG_DIR

package/src/cli/reindex.ts

@@ -1,9 +1,10 @@
 /**
  * hq reindex — surfaces namespaced skills as Claude Code skill wrappers under
- * .claude/skills/<ns>:<skill>/ (one symlink per source file), mirrors
- * personal/{knowledge,policies,workers,settings}/<entry> into core/<type>/,
- * prunes orphan wrappers + legacy command symlinks, captures this HQ tree's
- * coding-harness session logs (Claude Code / Codex / Grok) into
+ * .claude/skills/<ns>:<skill>/ (one symlink per source file), prunes orphan
+ * wrappers + legacy command symlinks (plus a migration cleanup of retired
+ * personal/{knowledge,policies,workers,settings} mirror symlinks in core/<type>/
+ * — that overlay is now read directly from personal/, not mirrored), captures
+ * this HQ tree's coding-harness session logs (Claude Code / Codex / Grok) into
  * workspace/.session-logs/<harness>/, and regenerates the workers registry.
  *
  * The logic historically lived in a bundled bash script (scripts/reindex.sh)
@@ -689,63 +690,24 @@ export function reindex(opts: ReindexOptions = {}): ReindexResult {
     }
   }
 
-  // --- Personal type mirroring ----------------------------------------------
-  // Mirror personal/<type>/<entry> into core/<type>/<entry> as symlinks.
-  for (const type of ["knowledge", "policies", "workers", "settings"]) {
-    const personalDir = path.join(root, "personal", type);
-    const coreDir = path.join(root, "core", type);
-
-    if (!isDir(personalDir)) continue;
-    if (!safeMkdir(coreDir, `core/${type} directory`)) continue;
-
-    for (const entry of globEntries(personalDir)) {
-      const entryPath = path.join(personalDir, entry);
-      if (!existsFollow(entryPath)) continue;
-
-      const linkPath = path.join(coreDir, entry);
-      const relativeTarget = `../../personal/${type}/${entry}`;
-
-      const lst = lstatOrNull(linkPath);
-      if (lst && lst.isSymbolicLink()) {
-        const current = readlinkOrNull(linkPath);
-        if (current === relativeTarget) continue;
-        skippedPointsElsewhere++;
-        if (verbose) {
-          warn(
-            `reindex: core/${type}/${entry} already points to '${current}' (expected '${relativeTarget}'); leaving alone`,
-          );
-        }
-        continue;
-      } else if (lst) {
-        skippedNonSymlink++;
-        if (verbose) {
-          warn(`reindex: core/${type}/${entry} already exists and is not a symlink; skipping`);
-        }
-        continue;
-      }
-
-      safeSymlink(relativeTarget, linkPath, `core/${type}/${entry}`);
-    }
-  }
-
-  // --- Cleanup pass C: drop orphan personal-overlay mirror symlinks ----------
-  // The mirror above creates core/<type>/<entry> -> ../../personal/<type>/<entry>
-  // for each LIVE personal entry, but historically never removed that symlink
-  // when its personal source was later deleted or renamed — leaving a dangling
-  // link in core/<type>/ (e.g. a retired personal policy that still surfaced via
-  // the policy-trigger hook until a human hand-deleted it). This pass prunes it.
+  // --- Personal-overlay mirroring: RETIRED + migration cleanup ---------------
+  // personal/{knowledge,policies,workers,settings} is now read DIRECTLY by the
+  // HQ tooling (the inject-policy-on-trigger hook reads personal/policies, the
+  // workers-registry generator walks personal/workers, qmd-reindex-after-sync
+  // registers a personal/knowledge collection, and repo-run-registry reads
+  // personal/settings/orchestrator.yaml). personal is the SOLE read source for
+  // the personal overlay, so reindex no longer SYMLINKS personal/<type>/<entry>
+  // into core/<type>/<entry> — a mirror would now double-surface every entry
+  // (read once directly, once via the link).
   //
-  // Ownership discriminator (policy wrapper-sync-orphan-cleanup-cross-check): a
-  // core/<type>/<entry> is "managed by this mirror" ONLY when it is a symlink
-  // whose target is EXACTLY `../../personal/<type>/<entry>` — i.e. the target
-  // encodes the same <type> and <entry> as the link's own location and name.
-  // That exact cross-check means a real release-shipped core file (not a
-  // symlink), or a human-authored symlink pointing anywhere else, never matches
-  // and is left untouched. A managed link is pruned IFF its target no longer
-  // resolves (existsFollow=false) — which, given the exact-target shape, is
-  // precisely "the personal source was removed". This runs independently of the
-  // creation loop above (note: no `isDir(personalDir)` guard) so that deleting
-  // the ENTIRE personal/<type>/ directory still prunes every mirror it produced.
+  // Migration cleanup: prune any mirror symlink a PRIOR release created —
+  // core/<type>/<entry> whose target is EXACTLY `../../personal/<type>/<entry>`.
+  // That exact-target discriminator (policy wrapper-sync-orphan-cleanup-cross-
+  // check) means a real release-shipped core file (not a symlink) or a human-
+  // authored symlink pointing elsewhere is never touched. Unlike the old
+  // "Cleanup pass C", this prunes the link WHETHER OR NOT its personal source
+  // still exists: the mirror is retired, so every managed link is now stale.
+  // Kept for a few releases so existing trees self-heal on the next reindex.
   for (const type of ["knowledge", "policies", "workers", "settings"]) {
     const coreDir = path.join(root, "core", type);
     for (const entry of globEntries(coreDir)) {
@@ -753,8 +715,7 @@ export function reindex(opts: ReindexOptions = {}): ReindexResult {
       const lst = lstatOrNull(linkPath);
       if (!lst || !lst.isSymbolicLink()) continue; // real file/dir → not ours
       if (readlinkOrNull(linkPath) !== `../../personal/${type}/${entry}`) continue; // not a managed mirror link
-      if (existsFollow(linkPath)) continue; // live: personal source still present
-      // Managed mirror symlink whose personal source is gone → prune.
+      // Managed mirror symlink from a prior release → prune (mirror is retired).
       try {
         fs.rmSync(linkPath);
       } catch {

package/src/cli/rescue.reindex.test.ts

@@ -1,7 +1,8 @@
 /**
  * Wiring tests: `rescue()` runs `reindex()` after a successful, non-dry-run
- * rescue so the generated skill wrappers / personal mirrors / workers registry
- * are refreshed once core/ has been re-laid-down.
+ * rescue so the generated skill wrappers / workers registry are refreshed once
+ * core/ has been re-laid-down (the personal overlay is read directly, not
+ * mirrored, so there are no personal mirror symlinks to refresh).
  *
  * The rescue algorithm (./rescue-core.js) is mocked so no real clone/overlay
  * runs, and ./reindex.js is mocked to a spy so we assert the call without

package/src/cli/share.test.ts

@@ -41,6 +41,7 @@ import * as readline from "readline";
 import { share, _testing as shareTesting } from "./share.js";
 import { deleteRemoteFile, downloadFile, headRemoteFile, uploadFile, uploadSymlink } from "../s3.js";
 import type { EntityContext } from "../types.js";
+import { VaultAuthError } from "../vault-client.js";
 
 const mockConfig: VaultServiceConfig = {
   apiUrl: "https://vault-api.test",
@@ -207,6 +208,25 @@ describe("share", () => {
     expect(uploadFile).toHaveBeenCalledWith(expect.anything(), testFile, "test.md", undefined, expect.anything());
   });
 
+  it("propagates a per-file vault 401 to the runner auth boundary", async () => {
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    fs.mkdirSync(companyRoot, { recursive: true });
+    const testFile = path.join(companyRoot, "private.md");
+    fs.writeFileSync(testFile, "private");
+    vi.mocked(uploadFile).mockRejectedValueOnce(
+      new VaultAuthError("upload unauthorized"),
+    );
+
+    await expect(
+      share({
+        paths: [testFile],
+        company: "acme",
+        vaultConfig: mockConfig,
+        hqRoot: tmpDir,
+      }),
+    ).rejects.toBeInstanceOf(VaultAuthError);
+  });
+
   it("respects ignore rules", async () => {
     const companyRoot = path.join(tmpDir, "companies", "acme");
     fs.mkdirSync(path.join(companyRoot, ".git"), { recursive: true });

package/src/cli/share.ts

@@ -67,6 +67,7 @@ import {
 } from "../lib/conflict-file.js";
 import { appendConflictEntry } from "../lib/conflict-index.js";
 import { isCloudAuthoritative } from "../lib/cloud-authoritative.js";
+import { VaultAuthError } from "../vault-client.js";
 
 /**
  * Push-side fresh-collision convergence probe.
@@ -110,7 +111,8 @@ async function remoteContentDiffers(
       ? hashSymlinkTarget(fs.readlinkSync(probePath))
       : hashFile(probePath);
     return remoteHash !== localHash;
-  } catch {
+  } catch (err) {
+    if (err instanceof VaultAuthError) throw err;
     return true;
   } finally {
     try {
@@ -1388,6 +1390,7 @@ async function executeUploads(
     try {
       await performUpload(precondition);
     } catch (err) {
+      if (err instanceof VaultAuthError) throw err;
       if (isPreconditionFailed(err)) {
         conflictPaths.push(relativePath);
         const resolution = await resolveConflictSerialized({
@@ -1410,6 +1413,7 @@ async function executeUploads(
           try {
             await performUpload(undefined);
           } catch (retryErr) {
+            if (retryErr instanceof VaultAuthError) throw retryErr;
             run.emit({
               type: "error",
               path: relativePath,
@@ -1501,6 +1505,7 @@ async function writePushConflictMirror(
       });
     }
   } catch (mirrorErr) {
+    if (mirrorErr instanceof VaultAuthError) throw mirrorErr;
     run.emit({
       type: "error",
       path: item.relativePath,
@@ -1562,6 +1567,7 @@ async function executeDeletes(
         deleted: true,
       });
     } catch (err) {
+      if (err instanceof VaultAuthError) throw err;
       run.emit({
         type: "error",
         path: relativePath,

package/src/cli/sync.test.ts

@@ -58,6 +58,7 @@ import { share } from "./share.js";
 import * as s3Module from "../s3.js";
 import { reindex } from "./reindex.js";
 import { readSyncProgress } from "../sync-progress.js";
+import { VaultAuthError } from "../vault-client.js";
 
 const mockConfig: VaultServiceConfig = {
   apiUrl: "https://vault-api.test",
@@ -154,6 +155,19 @@ describe("sync", () => {
     expect(s3Module.classifyVaultKey("docs/readme.md", "company")).toBeNull();
   });
 
+  it("propagates a per-file vault 401 to the runner auth boundary", async () => {
+    vi.mocked(s3Module.listRemoteFiles).mockResolvedValueOnce([
+      { key: "docs/private.md", size: 10, lastModified: new Date(), etag: '"private"' },
+    ]);
+    vi.mocked(s3Module.downloadFile).mockRejectedValueOnce(
+      new VaultAuthError("download unauthorized"),
+    );
+
+    await expect(
+      sync({ company: "acme", vaultConfig: mockConfig, hqRoot: tmpDir }),
+    ).rejects.toBeInstanceOf(VaultAuthError);
+  });
+
   it("runs reindex against hqRoot after a sync that downloaded files", async () => {
     await sync({ company: "acme", vaultConfig: mockConfig, hqRoot: tmpDir });
     // skipLock: the surrounding sync run already holds the per-root lock.

package/src/cli/sync.ts

@@ -12,7 +12,7 @@ import type {
   VaultServiceConfig,
   SyncJournal,
 } from "../types.js";
-import { VaultClient, type SyncMode } from "../vault-client.js";
+import { VaultAuthError, VaultClient, type SyncMode } from "../vault-client.js";
 import {
   emitCloudTelemetry,
   type TelemetryClaims,
@@ -1311,6 +1311,7 @@ async function executeConflictItem(
       : (downloaded.contentHash ?? hashFile(conflictAbs));
     converged = remoteHash === item.localHash;
   } catch (probeErr) {
+    if (probeErr instanceof VaultAuthError) throw probeErr;
     run.emit({
       type: "error",
       path: remoteFile.key,
@@ -1563,6 +1564,7 @@ async function downloadOne(
     counters.bytesDownloaded += size;
     counters.changedPaths.push(remoteFile.key);
   } catch (err) {
+    if (err instanceof VaultAuthError) throw err;
     if (err instanceof LocalSnapshotChangedError) {
       reportLocalSnapshotConflict(run, counters, remoteFile.key);
     } else if (isAccessDenied(err)) {
@@ -1617,6 +1619,7 @@ async function emitAndReportNewFiles(
             addedBy = head.metadata["created-by"];
           }
         } catch (headErr) {
+          if (headErr instanceof VaultAuthError) throw headErr;
           try {
             console.error(
               `[hq-sync] HeadObject failed for ${nf.path}: ${
@@ -1683,6 +1686,7 @@ async function verifyPlannedJournalTombstones(
           const head = await headRemoteFile(run.ctx, tombstone.key);
           return head === null ? tombstone : null;
         } catch (err) {
+          if (err instanceof VaultAuthError) throw err;
           if (isAccessDenied(err)) return null;
           run.emit({
             type: "error",