@indigoai-us/hq-cloud 6.11.10 → 6.11.11

package/src/cli/reindex.test.ts

@@ -8,13 +8,36 @@
  * re-deriving the implementation internals.
  */
 
-import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
 import * as fs from "fs";
 import * as path from "path";
 import * as os from "os";
 import { reindex } from "./reindex.js";
 import { lockPathFor, OPERATION_LOCKED_EXIT } from "../operation-lock.js";
 
+// HQ-B0: simulate the Windows filesystem rejecting a ':' in a path segment.
+// The flag is off by default, so every other test sees the real `mkdirSync`;
+// the regression test below flips it on only for its own run.
+const hoisted = vi.hoisted(() => ({ failNamespacedMkdir: false }));
+vi.mock("fs", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("fs")>();
+  const mkdirSync = ((p: unknown, opts: unknown) => {
+    if (
+      hoisted.failNamespacedMkdir &&
+      typeof p === "string" &&
+      /[:][^/\\]*$/.test(p) // a colon in the final path segment
+    ) {
+      throw Object.assign(
+        new Error(`ENOENT: no such file or directory, mkdir '${p}'`),
+        { code: "ENOENT" },
+      );
+    }
+    return (actual.mkdirSync as (p: unknown, opts: unknown) => unknown)(p, opts);
+  }) as typeof actual.mkdirSync;
+  const patched = { ...actual, mkdirSync };
+  return { ...patched, default: patched };
+});
+
 describe("reindex", () => {
   let root: string;
   let stateDir: string;
@@ -223,4 +246,27 @@ describe("reindex", () => {
     reindex({ repoRoot: root });
     expect(fs.existsSync(lockPathFor(root))).toBe(false);
   });
+
+  // ── HQ-B0: wrapper dir name uses ':' which is illegal on Windows ─────────
+  // `<ns>:<skill>` wrapper dirs contain a colon — fine on macOS/Linux, but a
+  // reserved drive/ADS separator on Windows, where mkdirSync throws ENOENT.
+  // A single un-creatable wrapper must not abort the entire reindex run.
+
+  it("does not abort reindex when a namespaced wrapper dir cannot be created (':' illegal on Windows)", () => {
+    writeSkill("core/skills/demo");
+    writeSkill("companies/acme/skills/widget");
+
+    hoisted.failNamespacedMkdir = true;
+    try {
+      // Without the guard the wrapper mkdir throws ENOENT and aborts the whole
+      // command; with it, the run completes and the bad wrappers are skipped.
+      expect(reindex({ repoRoot: root }).status).toBe(0);
+    } finally {
+      hoisted.failNamespacedMkdir = false;
+    }
+
+    // The un-creatable wrappers are skipped (not half-written).
+    expect(fs.existsSync(path.join(root, ".claude/skills/core:demo"))).toBe(false);
+    expect(fs.existsSync(path.join(root, ".claude/skills/acme:widget"))).toBe(false);
+  });
 });

package/src/cli/reindex.ts

@@ -270,7 +270,23 @@ export function reindex(opts: ReindexOptions = {}): ReindexResult {
           /* best-effort */
         }
       }
-      fs.mkdirSync(wrapper, { recursive: true });
+      try {
+        fs.mkdirSync(wrapper, { recursive: true });
+      } catch (err) {
+        // Namespaced wrappers embed a ':' in the directory name
+        // (`<ns>:<skill>`). That is a legal filename character on macOS/Linux
+        // but a reserved drive/ADS separator on Windows, so mkdir there fails
+        // with ENOENT. Skip this one wrapper with a clear message instead of
+        // aborting the whole reindex (the skill's source folder is untouched).
+        const code = (err as NodeJS.ErrnoException).code;
+        warn(
+          `reindex: could not create skill wrapper '${wrapperName}' ` +
+            `(${code ?? "error"}: ${(err as Error).message}). Namespaced wrappers ` +
+            `use a ':' in the directory name, which is not a legal filename ` +
+            `character on this platform (e.g. Windows); skipping this skill.`,
+        );
+        continue;
+      }
 
       // Symlink every (non-hidden) entry in the source skill folder. The
       // wrapper lives three levels below REPO_ROOT.

package/src/cli/rescue-core.ts

@@ -869,6 +869,16 @@ function doRescue(
     }
   }
 
+  // --- Restore executable bit on shipped shebang scripts (defense-in-depth) ---
+  // rsync -a already propagated each file's upstream git tree mode; this guards
+  // the case where upstream itself committed an executable script as 0644 -- a
+  // hook the runtime exec's then dies with EACCES and is silently disabled. A
+  // shebang is an unambiguous "meant to be run" marker. See restoreShebangExecBits.
+  const execBitFixes = restoreShebangExecBits(srcDir, hqRoot, env);
+  if (execBitFixes > 0) {
+    out(`==> Restored executable bit on ${execBitFixes} shipped shebang script(s) lacking +x\n`);
+  }
+
   // --- Stamp sync-point provenance into core/core.yaml ---
   // `last_sync_at` = the source commit's committer time, NOT wall-clock now:
   // the stamp must be a pure function of srcSha so every machine rescuing the
@@ -1269,6 +1279,83 @@ function diffAppendClaudeMd(ctx: WalkCtx): void {
   ctx.counts.claudeDiffAppend += 1;
 }
 
+/**
+ * Defense-in-depth for executable scaffold scripts. `rescue` rebuilds the tree
+ * with `git clone` + `rsync -a`, faithfully propagating each file's git tree
+ * mode (100755 vs 100644). So a script accidentally committed upstream WITHOUT
+ * its executable bit (e.g. a `.claude/hooks/*.sh` checked in as 100644) is
+ * delivered non-executable to every machine, and a hook the runtime exec's
+ * directly then fails with EACCES ("Permission denied") and is silently
+ * disabled.
+ *
+ * A `#!` shebang is an unambiguous "this file is meant to be run" marker, so
+ * after the overlay we ensure every shipped shebang script is executable,
+ * regardless of the (possibly wrong) upstream mode bit. Execute is added only
+ * where read is already granted (0644 -> 0755, 0640 -> 0750), mirroring the
+ * umask convention; files that already carry any exec bit, non-files, and
+ * symlinks are left untouched. Paths are enumerated from the SOURCE repo's git
+ * index, so this only ever touches release-shipped scaffold -- never user
+ * content the rescue leaves in place.
+ *
+ * Best-effort and non-fatal: a failed `git ls-files` or chmod (read-only FS,
+ * EPERM) is swallowed, matching the rest of rescue's posture. Returns the count
+ * of files whose mode was changed, for the run summary.
+ */
+function restoreShebangExecBits(
+  srcDir: string,
+  hqRoot: string,
+  env: NodeJS.ProcessEnv,
+): number {
+  let listing: string;
+  try {
+    const r = spawnSync("git", ["-C", srcDir, "ls-files", "-z"], {
+      encoding: "utf-8",
+      env,
+      maxBuffer: 128 * 1024 * 1024,
+    });
+    if (r.status !== 0 || typeof r.stdout !== "string") return 0;
+    listing = r.stdout;
+  } catch {
+    return 0;
+  }
+  let fixed = 0;
+  for (const rel of listing.split("\0")) {
+    if (!rel) continue;
+    const dest = path.join(hqRoot, rel);
+    let st: fs.Stats;
+    try {
+      st = fs.lstatSync(dest);
+    } catch {
+      continue; // not delivered here (preserve-excluded, ignored, narrowed out)
+    }
+    if (!st.isFile()) continue; // skip dirs and symlinks (lstat: a link is not a file)
+    if ((st.mode & 0o111) !== 0) continue; // already executable
+    // Sniff the first two bytes for a shebang.
+    let head = "";
+    try {
+      const fd = fs.openSync(dest, "r");
+      try {
+        const buf = Buffer.alloc(2);
+        const n = fs.readSync(fd, buf, 0, 2, 0);
+        head = buf.subarray(0, n).toString("latin1");
+      } finally {
+        fs.closeSync(fd);
+      }
+    } catch {
+      continue;
+    }
+    if (head !== "#!") continue;
+    const execBits = (st.mode & 0o444) >> 2; // copy r-bits into the x-bit slots
+    try {
+      fs.chmodSync(dest, st.mode | execBits);
+      fixed += 1;
+    } catch {
+      // read-only FS / EPERM -- non-fatal.
+    }
+  }
+  return fixed;
+}
+
 function readFileOrEmpty(p: string): string {
   try {
     return fs.readFileSync(p, "utf-8");

package/src/cli/rescue-exec-bit-preserve.test.ts

@@ -0,0 +1,187 @@
+/**
+ * Regression for the rescue executable-bit guarantee in src/cli/rescue-core.ts
+ * (restoreShebangExecBits).
+ *
+ * rescue rebuilds the tree with `git clone` + `rsync -a`, which faithfully
+ * propagates the upstream git tree mode. So a script committed upstream WITHOUT
+ * its executable bit (a `.sh` checked in as 100644) is delivered non-executable
+ * to every machine -- and a hook the runtime exec's directly then fails with
+ * "Permission denied". After the overlay, rescue restores +x on any shipped
+ * file that begins with a `#!` shebang (and leaves non-shebang files alone).
+ *
+ * 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 for real.
+ */
+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 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 FLOOR_EPOCH = 1577836800; // 2020-01-01
+const HEAD_EPOCH = 1609459200; // 2021-01-01
+
+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 restores +x on shipped shebang scripts", () => {
+  let workDir: string;
+  let upstream: string;
+  let hqRoot: string;
+  let shimDir: string;
+  let floorSha: string;
+  let env: NodeJS.ProcessEnv;
+
+  const gitAt = (cwd: string, epoch: number, ...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();
+
+  const isExec = (p: string) => (fs.statSync(p).mode & 0o111) !== 0;
+  const mode = (p: string) => fs.statSync(p).mode & 0o777;
+
+  beforeAll(() => {
+    workDir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-rescue-exec-"));
+
+    // --- "upstream" repo ----------------------------------------------------
+    upstream = path.join(workDir, "upstream");
+    fs.mkdirSync(path.join(upstream, "core/scripts"), { recursive: true });
+    fs.mkdirSync(path.join(upstream, "core/docs"), { recursive: true });
+    gitAt(workDir, FLOOR_EPOCH, "init", "-b", "main", "upstream");
+
+    // Shebang script committed WITHOUT +x (the bug: arrives non-executable).
+    const needs = path.join(upstream, "core/scripts/needs-exec.sh");
+    fs.writeFileSync(needs, "#!/bin/bash\necho needs\n", { mode: 0o644 });
+    fs.chmodSync(needs, 0o644);
+    // Shebang script committed WITH +x (control: rsync -a already preserves it).
+    const already = path.join(upstream, "core/scripts/already-exec.sh");
+    fs.writeFileSync(already, "#!/bin/bash\necho already\n");
+    fs.chmodSync(already, 0o755);
+    // Non-shebang data file (control: must NOT be made executable).
+    fs.writeFileSync(path.join(upstream, "core/docs/note.md"), "# note\n", { mode: 0o644 });
+
+    gitAt(upstream, FLOOR_EPOCH, "add", "-A");
+    gitAt(upstream, FLOOR_EPOCH, "commit", "-m", "floor");
+    floorSha = gitAt(upstream, FLOOR_EPOCH, "rev-parse", "HEAD");
+    // A second commit so floor != HEAD (mirrors the mtime fixture).
+    fs.writeFileSync(path.join(upstream, "core/docs/head.md"), "head\n");
+    gitAt(upstream, HEAD_EPOCH, "add", "-A");
+    gitAt(upstream, HEAD_EPOCH, "commit", "-m", "head");
+
+    // Confirm the fixture actually stored the intended tree modes.
+    const lsFloor = gitAt(upstream, HEAD_EPOCH, "ls-tree", "-r", "HEAD");
+    if (!/100644\s+blob\s+\S+\s+core\/scripts\/needs-exec\.sh/.test(lsFloor)) {
+      throw new Error(`fixture needs-exec.sh not stored as 100644:\n${lsFloor}`);
+    }
+    if (!/100755\s+blob\s+\S+\s+core\/scripts\/already-exec\.sh/.test(lsFloor)) {
+      throw new Error(`fixture already-exec.sh not stored as 100755:\n${lsFloor}`);
+    }
+
+    // --- local HQ root being rescued (fresh; upstream files are brand-new) --
+    hqRoot = path.join(workDir, "hq");
+    fs.mkdirSync(path.join(hqRoot, "core"), { recursive: true });
+    fs.mkdirSync(path.join(hqRoot, "personal"), { recursive: true });
+    fs.mkdirSync(path.join(hqRoot, "companies"), { recursive: true });
+
+    // --- 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 ?? ""}` };
+
+    const r = runRescueCapture(
+      [
+        "--hq-root", hqRoot,
+        "--source", "test/repo",
+        "--ref", "main",
+        "--floor-sha", floorSha,
+        "--yes",
+        "--no-backup",
+      ],
+      env,
+    );
+    if (r.status !== 0) {
+      throw new Error(`rescue failed (${r.status}):\n${r.stdout}\n${r.stderr}`);
+    }
+  });
+
+  afterAll(() => {
+    if (workDir) fs.rmSync(workDir, { recursive: true, force: true });
+  });
+
+  it("restores +x on a shebang script shipped as 0644 (the bug)", () => {
+    const f = path.join(hqRoot, "core/scripts/needs-exec.sh");
+    expect(fs.readFileSync(f, "utf-8")).toBe("#!/bin/bash\necho needs\n");
+    expect(isExec(f)).toBe(true);
+    expect(mode(f)).toBe(0o755); // 0644 + (read-bits -> exec-bits)
+  });
+
+  it("leaves an already-executable shebang script executable", () => {
+    const f = path.join(hqRoot, "core/scripts/already-exec.sh");
+    expect(isExec(f)).toBe(true);
+  });
+
+  it("never makes a non-shebang data file executable", () => {
+    const f = path.join(hqRoot, "core/docs/note.md");
+    expect(fs.existsSync(f)).toBe(true);
+    expect(isExec(f)).toBe(false);
+  });
+});

package/src/cli/sync.test.ts

@@ -611,6 +611,165 @@ describe("sync", () => {
     expect(fs.existsSync(path.join(tmpDir, "companies", "acme", "docs", "readme.md"))).toBe(false);
   });
 
+  it("personalMode: downloads + journals companies/manifest.yaml (carve-out round-trips) while still skipping other companies/* keys", async () => {
+    vi.mocked(s3Module.listRemoteFiles).mockResolvedValueOnce([
+      { key: "companies/foo/bar.md",    size: 50, lastModified: new Date(), etag: '"xyz789"' },
+      { key: "companies/manifest.yaml", size: 40, lastModified: new Date(), etag: '"man111"' },
+    ]);
+
+    const result = await sync({
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      personalMode: true,
+    });
+
+    // The manifest is the lone companies/* exemption: it downloads; other
+    // companies/* keys are still dropped.
+    expect(result.filesSkipped).toBe(1);
+    expect(result.filesDownloaded).toBe(1);
+    expect(fs.existsSync(path.join(tmpDir, "companies", "manifest.yaml"))).toBe(true);
+    expect(fs.existsSync(path.join(tmpDir, "companies", "foo", "bar.md"))).toBe(false);
+
+    // The whole point: it now gets a journal baseline, so the push side stops
+    // re-firing a transient conflict every sync (the bug this fix closes).
+    const journaledManifest = fs
+      .readdirSync(stateDir)
+      .filter((f) => f.startsWith("sync-journal."))
+      .some((f) => {
+        const j = JSON.parse(fs.readFileSync(path.join(stateDir, f), "utf8"));
+        return j.files?.["companies/manifest.yaml"] != null;
+      });
+    expect(journaledManifest).toBe(true);
+  });
+
+  it("personalMode pull lands the session-continuity pointer + active thread file under <hqRoot>/workspace/threads/ so a handoff resumes on machine B (DEV-1778)", async () => {
+    // End-to-end download leg of the cross-machine handoff. Machine A pushed
+    // workspace/threads/handoff.json + the thread file it points to into the
+    // personal bucket; machine B pulls and both must land hq-root-relative
+    // (NOT under companies/<slug>/) with the pointer still resolving to the
+    // thread file that also landed — that is what lets /startwork resume.
+    const handoffKey = "workspace/threads/handoff.json";
+    const threadKey = "workspace/threads/T-20260619-1200-resume-me.json";
+
+    vi.mocked(s3Module.listRemoteFiles).mockResolvedValueOnce([
+      { key: handoffKey, size: 80, lastModified: new Date(), etag: '"h1"' },
+      { key: threadKey, size: 40, lastModified: new Date(), etag: '"t1"' },
+    ]);
+
+    // Materialize realistic bytes per key (the default mock writes a fixed
+    // string, but the pointer must be valid JSON referencing the thread).
+    const origDownload = vi.mocked(s3Module.downloadFile).getMockImplementation();
+    vi.mocked(s3Module.downloadFile).mockImplementation(
+      async (_ctx: unknown, key: string, localPath: string) => {
+        fs.mkdirSync(path.dirname(localPath), { recursive: true });
+        const body = key.endsWith("handoff.json")
+          ? JSON.stringify({ thread_path: threadKey, message: "from machine A" })
+          : JSON.stringify({ conversation_summary: "pick up here" });
+        fs.writeFileSync(localPath, body);
+        return { metadata: {} };
+      },
+    );
+
+    try {
+      const result = await sync({
+        company: "acme",
+        vaultConfig: mockConfig,
+        hqRoot: tmpDir,
+        personalMode: true,
+      });
+
+      expect(result.filesDownloaded).toBe(2);
+
+      const handoffLocal = path.join(tmpDir, "workspace", "threads", "handoff.json");
+      const threadLocal = path.join(
+        tmpDir,
+        "workspace",
+        "threads",
+        "T-20260619-1200-resume-me.json",
+      );
+      expect(fs.existsSync(handoffLocal)).toBe(true);
+      expect(fs.existsSync(threadLocal)).toBe(true);
+
+      // Pointer round-trips and resolves to the thread file that also landed.
+      const pointer = JSON.parse(fs.readFileSync(handoffLocal, "utf-8"));
+      expect(pointer.thread_path).toBe(threadKey);
+      expect(fs.existsSync(path.join(tmpDir, pointer.thread_path))).toBe(true);
+
+      // Must NOT be misfiled under companies/<slug>/.
+      expect(
+        fs.existsSync(path.join(tmpDir, "companies", "acme", handoffKey)),
+      ).toBe(false);
+    } finally {
+      if (origDownload) {
+        vi.mocked(s3Module.downloadFile).mockImplementation(origDownload);
+      }
+    }
+  });
+
+  it("personalMode pull does NOT clobber a newer local session-continuity pointer (conflict → keep local) (DEV-1778)", async () => {
+    // Machine B did its OWN /handoff after machine A's push, so B's local
+    // handoff.json is newer than the remote. The pull must preserve B's
+    // pointer rather than overwrite it with A's stale one — the brief's
+    // "download cleanly without clobbering a newer local pointer".
+    const threadsLocal = path.join(tmpDir, "workspace", "threads");
+    fs.mkdirSync(threadsLocal, { recursive: true });
+    fs.writeFileSync(
+      path.join(threadsLocal, "handoff.json"),
+      JSON.stringify({
+        thread_path: "workspace/threads/T-machineB.json",
+        message: "newer local from B",
+      }),
+    );
+
+    // Journal records a prior synced baseline (stale hash, no remoteEtag) so
+    // the planner sees local-changed AND remote-changed → conflict. Keys are
+    // hq-root-relative in personalMode.
+    fs.writeFileSync(
+      journalPath,
+      JSON.stringify({
+        version: "1",
+        lastSync: new Date().toISOString(),
+        files: {
+          "workspace/threads/handoff.json": {
+            hash: "old-hash-from-last-sync",
+            size: 10,
+            syncedAt: new Date(Date.now() - 3600000).toISOString(),
+            direction: "down",
+          },
+        },
+      }),
+    );
+
+    vi.mocked(s3Module.listRemoteFiles).mockResolvedValueOnce([
+      {
+        key: "workspace/threads/handoff.json",
+        size: 50,
+        lastModified: new Date(),
+        etag: '"remote-from-A"',
+      },
+    ]);
+
+    const result = await sync({
+      company: "acme",
+      onConflict: "keep",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      personalMode: true,
+    });
+
+    expect(result.conflicts).toBe(1);
+    expect(result.conflictPaths).toEqual(["workspace/threads/handoff.json"]);
+    expect(result.filesSkipped).toBeGreaterThanOrEqual(1);
+
+    // B's newer local pointer is preserved verbatim — not clobbered by A's.
+    const kept = JSON.parse(
+      fs.readFileSync(path.join(threadsLocal, "handoff.json"), "utf-8"),
+    );
+    expect(kept.message).toBe("newer local from B");
+    expect(kept.thread_path).toBe("workspace/threads/T-machineB.json");
+  });
+
   it("personalMode + includeLocalCompanies: downloads companies/{cloud-false-slug}/... keys when slug NOT in teamSyncedSlugs", async () => {
     // The symmetric flip for the cloud:false → personal-bucket fallback.
     // Machine A pushed `companies/free-co/notes.md` to the personal bucket

package/src/cli/sync.ts

@@ -35,6 +35,7 @@ import {
   PERSONAL_VAULT_JOURNAL_SLUG,
   migratePersonalVaultJournal,
 } from "../journal.js";
+import { PERSONAL_VAULT_MANIFEST_KEY } from "../personal-vault.js";
 import {
   buildScopeShrinkPlan,
   applyScopeShrink,
@@ -1751,7 +1752,17 @@ function computePullPlan(
       continue;
     }
 
-    if (personalMode && remoteFile.key.startsWith("companies/")) {
+    if (
+      personalMode &&
+      remoteFile.key.startsWith("companies/") &&
+      // EXEMPTION: companies/manifest.yaml is the routing source-of-truth
+      // carved INTO the personal vault on the push side
+      // (computePersonalVaultPaths). It must round-trip on the pull leg too —
+      // skipping it here leaves it forever unjournaled, which re-fires a
+      // transient push-side conflict every sync (no journal baseline). Let it
+      // fall through to download + journal like any personal file.
+      remoteFile.key !== PERSONAL_VAULT_MANIFEST_KEY
+    ) {
       // Default: drop every `companies/...` key — the legacy contract
       // is that the personal bucket should never contain them.
       //

package/src/personal-vault.ts

@@ -94,6 +94,15 @@ export interface PersonalVaultOptions {
  * hqRoot returns []; callers treat that as "no personal content to push"
  * rather than a hard error.
  */
+/**
+ * S3 key (hq-root-relative, forward-slash) of the companies manifest — the
+ * routing source-of-truth — carved into the personal vault even though
+ * `companies/` is otherwise excluded. Exported so the PULL plan applies the
+ * SAME exemption: skipping it on the pull leaves it unjournaled, which re-fires
+ * a transient push-side conflict every sync (no journal baseline).
+ */
+export const PERSONAL_VAULT_MANIFEST_KEY = "companies/manifest.yaml";
+
 export function computePersonalVaultPaths(
   hqRoot: string,
   opts: PersonalVaultOptions = {},
@@ -114,7 +123,7 @@ export function computePersonalVaultPaths(
   // because the parent `companies/` is in PERSONAL_VAULT_EXCLUDED_TOP_LEVEL
   // (we never enumerate the whole companies tree wholesale).
   const manifest: string[] = [];
-  const manifestPath = path.join(hqRoot, "companies", "manifest.yaml");
+  const manifestPath = path.join(hqRoot, PERSONAL_VAULT_MANIFEST_KEY);
   try {
     if (fs.statSync(manifestPath).isFile()) {
       manifest.push(manifestPath);