@indigoai-us/hq-cloud 6.2.2 → 6.2.4

package/src/cli/rescue-core.ts

@@ -28,13 +28,6 @@ import { spawnSync } from "child_process";
 import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
-import {
-  readJournal,
-  writeJournal,
-  hashFile,
-  updateEntry,
-  PERSONAL_VAULT_JOURNAL_SLUG,
-} from "../journal.js";
 
 export interface RunRescueResult {
   status: number;
@@ -568,6 +561,16 @@ function doRescue(
   }
 
   const srcSha = run("git", ["rev-parse", "HEAD"], { cwd: srcDir, env }).stdout.trim();
+  // Committer timestamp of the source SHA — the DETERMINISTIC stamp value for
+  // core/core.yaml's `last_sync_at`. Stamping wall-clock "now" made every
+  // rescue run on every machine produce a byte-different core.yaml for the
+  // SAME release, which is exactly the genuine local≠remote divergence that
+  // minted `core.yaml.conflict-*` mirrors across machines. Same SHA in →
+  // identical bytes out, on any machine, any day.
+  const srcCommitIsoRaw = run("git", ["show", "-s", "--format=%cI", "HEAD"], {
+    cwd: srcDir,
+    env,
+  }).stdout.trim();
   out(`==> Source SHA: ${srcSha}\n`);
 
   // --- Restore file mtimes from git history ---
@@ -799,7 +802,7 @@ function doRescue(
   }
   const overlay = run(
     "rsync",
-    ["-ai", ...overlayProtect, ...rsyncExcludes, srcDir + "/", hqRoot + "/"],
+    ["-a", ...overlayProtect, ...rsyncExcludes, srcDir + "/", hqRoot + "/"],
     { env },
   );
   if (overlay.status !== 0) {
@@ -825,71 +828,24 @@ function doRescue(
     }
   }
 
-  // --- Reconcile the sync-journal baseline for re-laid files ---
-  // The overlay rewrote scaffold files from upstream, but their personal-vault
-  // sync-journal entries still carry the PRE-rescue hash. The next sync would
-  // then read localHash != journal.hash ("local changed") and — when the vault
-  // also moved — mint a false `.conflict-*` mirror (the root cause of the
-  // conflict-file litter). Re-stamp the baseline to the freshly laid-down
-  // content so `localChanged` is false: the common single-machine case
-  // converges silently, and a genuinely-divergent vault degrades to a clean
-  // pull instead of a conflict mirror.
-  //
-  // Scoped STRICTLY to the paths rsync reported transferring (`-i` itemize) —
-  // never a blanket journal rewrite — so a user's unsynced pending edit (which
-  // the walk already rescued to personal/ rather than overlaying) is never
-  // silently marked as synced. Best-effort: a reconcile failure must never
-  // fail the rescue.
-  try {
-    const relaid: string[] = [];
-    for (const line of overlay.stdout.split("\n")) {
-      // itemize line: 11-char change code, space, path. 2nd col `f` = file.
-      const m = /^[<>ch.]f\S{9} (.+)$/.exec(line);
-      if (m) relaid.push(m[1]);
-    }
-    if (relaid.length > 0) {
-      const journal = readJournal(PERSONAL_VAULT_JOURNAL_SLUG);
-      let restamped = 0;
-      for (const rel of relaid) {
-        const prev = journal.files[rel];
-        if (!prev) continue; // only re-stamp paths already in the synced baseline
-        const abs = path.join(hqRoot, rel);
-        let st: fs.Stats;
-        try {
-          st = fs.lstatSync(abs);
-        } catch {
-          continue;
-        }
-        if (st.isSymbolicLink() || !st.isFile()) continue;
-        updateEntry(
-          journal,
-          rel,
-          hashFile(abs),
-          st.size,
-          prev.direction,
-          prev.remoteEtag,
-          st.mtimeMs,
-        );
-        restamped++;
-      }
-      if (restamped > 0) {
-        writeJournal(PERSONAL_VAULT_JOURNAL_SLUG, journal);
-        out(
-          `==> Reconciled sync-journal baseline for ${restamped} re-laid file(s)\n`,
-        );
-      }
-    }
-  } catch (e) {
-    out(
-      `    (sync-journal reconcile skipped: ${
-        e instanceof Error ? e.message : String(e)
-      })\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
+  // same release writes byte-identical core.yaml (see srcCommitIsoRaw). An
+  // unparseable commit timestamp skips the stamp entirely — a nondeterministic
+  // stamp is worse than no stamp (it re-creates cross-machine conflict mirrors).
+  const srcCommitDate = new Date(srcCommitIsoRaw);
+  if (cfg.narrowPaths.length === 0 && isFileFollow(coreYaml) && Number.isNaN(srcCommitDate.getTime())) {
+    err(
+      `    WARN: could not parse source commit timestamp (${JSON.stringify(srcCommitIsoRaw)}); skipping core/core.yaml stamp to keep it deterministic\n`,
     );
   }
-
-  // --- Stamp sync-point provenance into core/core.yaml ---
-  if (cfg.narrowPaths.length === 0 && isFileFollow(coreYaml)) {
-    const nowUtc = utcStamp(new Date(), "colon");
+  if (
+    cfg.narrowPaths.length === 0 &&
+    isFileFollow(coreYaml) &&
+    !Number.isNaN(srcCommitDate.getTime())
+  ) {
+    const nowUtc = utcStamp(srcCommitDate, "colon");
     if (yqAvailable) {
       const stampEnv: NodeJS.ProcessEnv = {
         ...env,
@@ -955,6 +911,15 @@ function doRescue(
     }
   }
 
+  // NOTE (6.2.4): the post-rescue "sync-journal baseline reconcile" that lived
+  // here (6.2.1 itemize-parse, 6.2.3 hash-diff) is intentionally GONE. Masking
+  // rescue-changed scaffold as already-synced starved the push leg — the vault
+  // silently kept stale scaffold bytes while the journal claimed convergence.
+  // Correct semantics: leave rescue-changed files visible as "local changed";
+  // the next bidirectional sync pushes them up (vault converges to the rescue
+  // output), and the pull-side byte-identical convergence probe (6.2.0)
+  // absorbs cross-machine races without minting `.conflict-*` mirrors.
+
   // --- File count summary ---
   out("\n");
   out("==> File count summary:\n");

package/src/cli/rescue-journal-reconcile.test.ts

@@ -1,17 +1,23 @@
 /**
- * Regression for the rescue → sync-journal stale-baseline bug.
+ * Regression for the rescue <-> sync-journal interaction (6.2.4 semantics).
  *
- * Root cause: the rescue overlay rewrites scaffold files from upstream but
- * never re-stamps the personal-vault sync journal. The journal keeps the
- * PRE-rescue hash, so the next sync reads localHash != journal.hash ("local
- * changed") and — when the vault also moved — mints a false `.conflict-*`
- * mirror. `runRescue` now re-stamps the journal baseline for the files the
- * overlay actually re-laid (scoped to rsync `-i` itemize output, so a user's
- * pending edit is never touched).
+ * History: 6.2.1/6.2.3 "reconciled" the journal after a rescue by re-stamping
+ * changed scaffold entries to the current local hash. That MASKED the rescue's
+ * changes from the sync engine: the push leg saw localChanged=false and never
+ * uploaded the regenerated scaffold, so the vault silently kept stale bytes
+ * while the journal claimed convergence (verified live 2026-06-10: 4 scaffold
+ * files byte-diverged from the vault under a 0-conflict sync).
  *
- * This test seeds a journal whose entry for an overlaid file carries the OLD
- * hash, runs a real (non-dry-run) rescue, and asserts the entry was re-stamped
- * to the freshly laid-down content — i.e. `localChanged` would now be false.
+ * Correct semantics (this test): the rescue must NOT touch the personal-vault
+ * sync journal at all. Rescue-changed scaffold stays visible as "local
+ * changed", the next bidirectional sync pushes it up, and the pull-side
+ * byte-identical convergence probe (6.2.0) absorbs cross-machine races.
+ *
+ * Also covered: the core/core.yaml provenance stamp must be DETERMINISTIC —
+ * a pure function of the source SHA (committer time, not wall-clock now) — so
+ * every machine rescuing the same release writes byte-identical core.yaml.
+ * The wall-clock stamp was the one genuine cross-machine divergence engine
+ * behind `core.yaml.conflict-*` mirrors.
  */
 import { describe, it, expect, beforeAll, afterAll } from "vitest";
 import { execFileSync } from "child_process";
@@ -52,10 +58,14 @@ function runRescueCapture(argv: string[], env: NodeJS.ProcessEnv) {
   return { status, stdout };
 }
 
-describe.skipIf(!gitAvailable)("rescue re-stamps sync-journal baseline for re-laid files", () => {
+const SCAFFOLD = ["core/a.md", "core/docs/b.md", ".claude/c.sh", "core/core.yaml"];
+
+describe.skipIf(!gitAvailable)("rescue leaves the sync journal untouched + stamps core.yaml deterministically", () => {
   let workDir: string, upstream: string, hqRoot: string, stateDir: string, floorSha: string;
   let env: NodeJS.ProcessEnv;
   let savedStateDir: string | undefined;
+  let headCommitterIso: string;
+  let seededHashes: Record<string, string>;
 
   const git = (cwd: string, ...args: string[]) =>
     execFileSync("git", args, {
@@ -64,52 +74,67 @@ describe.skipIf(!gitAvailable)("rescue re-stamps sync-journal baseline for re-la
       env: { ...process.env, GIT_AUTHOR_NAME: "t", GIT_AUTHOR_EMAIL: "t@t", GIT_COMMITTER_NAME: "t", GIT_COMMITTER_EMAIL: "t@t" },
     }).toString().trim();
 
+  const w = (root: string, rel: string, body: string) => {
+    const p = path.join(root, rel);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, body);
+  };
+
   beforeAll(() => {
     workDir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-rescue-journal-"));
 
-    // upstream: floor (doc.md=v1), then HEAD advances doc.md -> v2.
+    // --- upstream: floor (all scaffold = v1), HEAD advances the 3 docs to v2 ---
     upstream = path.join(workDir, "upstream");
-    fs.mkdirSync(path.join(upstream, "core"), { recursive: true });
+    fs.mkdirSync(upstream, { recursive: true });
     git(workDir, "init", "-b", "main", "upstream");
-    fs.writeFileSync(path.join(upstream, "core/doc.md"), "v1\n");
-    git(upstream, "add", "-A");
-    git(upstream, "commit", "-m", "floor");
+    w(upstream, "core/a.md", "v1\n");
+    w(upstream, "core/docs/b.md", "v1\n");
+    w(upstream, ".claude/c.sh", "v1\n");
+    w(upstream, "core/core.yaml", "version: 1\n");
+    git(upstream, "add", "-A"); git(upstream, "commit", "-m", "floor");
     floorSha = git(upstream, "rev-parse", "HEAD");
-    fs.writeFileSync(path.join(upstream, "core/doc.md"), "v2\n");
-    git(upstream, "add", "-A");
-    git(upstream, "commit", "-m", "head");
+    w(upstream, "core/a.md", "v2\n");
+    w(upstream, "core/docs/b.md", "v2\n");
+    w(upstream, ".claude/c.sh", "v2\n");
+    git(upstream, "add", "-A"); git(upstream, "commit", "-m", "head");
+    headCommitterIso = git(upstream, "show", "-s", "--format=%cI", "HEAD");
 
-    // local HQ root: doc.md == floor (v1) -> rescue overlays it to HEAD (v2).
+    // --- local HQ root: scaffold == floor (overlaid to v2); a pending personal/ edit ---
     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 });
-    const docAbs = path.join(hqRoot, "core/doc.md");
-    fs.writeFileSync(docAbs, "v1\n");
+    w(hqRoot, "core/a.md", "v1\n");
+    w(hqRoot, "core/docs/b.md", "v1\n");
+    w(hqRoot, ".claude/c.sh", "v1\n");
+    w(hqRoot, "core/core.yaml", "version: 1\n");
+    w(hqRoot, "personal/edited.md", "USER_LOCAL\n"); // local pending edit
 
-    // state dir + seeded personal-vault journal carrying the STALE (v1) hash.
+    // --- state dir + seeded journal: pre-rescue baselines for scaffold + a divergent personal/ entry ---
     stateDir = path.join(workDir, "state");
     fs.mkdirSync(stateDir, { recursive: true });
     savedStateDir = process.env.HQ_STATE_DIR;
-    process.env.HQ_STATE_DIR = stateDir; // getStateDir() reads process.env
-    const staleHash = hashFile(docAbs); // hash of v1
+    process.env.HQ_STATE_DIR = stateDir;
+    const entry = (rel: string, hash: string) => ({
+      hash,
+      size: fs.statSync(path.join(hqRoot, rel)).size,
+      syncedAt: new Date(0).toISOString(),
+      direction: "down" as const,
+      remoteEtag: "seed-etag",
+      mtimeMs: fs.statSync(path.join(hqRoot, rel)).mtimeMs,
+    });
+    const files: Record<string, unknown> = {};
+    seededHashes = {};
+    for (const rel of SCAFFOLD) {
+      const h = hashFile(path.join(hqRoot, rel)); // hash of v1/version:1
+      seededHashes[rel] = h;
+      files[rel] = entry(rel, h);
+    }
+    // personal/ pending edit: journal records a DIFFERENT (already-synced) hash than local.
+    files["personal/edited.md"] = { ...entry("personal/edited.md", "remote-side-hash-differs-from-local") };
     writeJournal(PERSONAL_VAULT_JOURNAL_SLUG, {
-      version: "2",
-      lastSync: new Date(0).toISOString(),
-      files: {
-        "core/doc.md": {
-          hash: staleHash,
-          size: fs.statSync(docAbs).size,
-          syncedAt: new Date(0).toISOString(),
-          direction: "down",
-          remoteEtag: "seed-etag",
-          mtimeMs: fs.statSync(docAbs).mtimeMs,
-        },
-      },
-      pulls: [],
+      version: "2", lastSync: new Date(0).toISOString(), files, pulls: [],
     } as never);
 
-    // git shim: redirect `git clone <github-url>` to the local fixture.
+    // --- git shim: redirect clone to the local fixture ---
     const realGit = execFileSync("bash", ["-lc", "command -v git"]).toString().trim() || "/usr/bin/git";
     const shimDir = path.join(workDir, "shim");
     fs.mkdirSync(shimDir, { recursive: true });
@@ -133,24 +158,58 @@ exec ${JSON.stringify(realGit)} "$@"
     if (workDir) fs.rmSync(workDir, { recursive: true, force: true });
   });
 
-  it("re-stamps the journal so the overlaid file is no longer seen as locally changed", () => {
-    const docAbs = path.join(hqRoot, "core/doc.md");
-    const staleHash = readJournal(PERSONAL_VAULT_JOURNAL_SLUG).files["core/doc.md"].hash;
-
+  it("leaves EVERY journal entry untouched so the push leg uploads rescue output (vault converges)", () => {
     const r = runRescueCapture(
       ["--hq-root", hqRoot, "--source", "test/repo", "--ref", "main", "--floor-sha", floorSha, "--yes", "--no-backup"],
       env,
     );
     expect(r.status, r.stdout).toBe(0);
 
-    // overlay actually re-laid the file (v1 -> v2)
-    expect(fs.readFileSync(docAbs, "utf-8")).toBe("v2\n");
+    // the 3 docs were overlaid v1 -> v2
+    for (const rel of ["core/a.md", "core/docs/b.md", ".claude/c.sh"]) {
+      expect(fs.readFileSync(path.join(hqRoot, rel), "utf-8")).toBe("v2\n");
+    }
+
+    const j = readJournal(PERSONAL_VAULT_JOURNAL_SLUG).files;
+
+    // INVARIANT: the rescue never rewrites journal baselines. Every scaffold
+    // entry still carries its PRE-rescue hash -> localChanged=true on the next
+    // sync -> the push leg uploads the regenerated scaffold and the VAULT
+    // converges to the rescue output. (Masking these — 6.2.1/6.2.3 — left the
+    // vault silently stale.)
+    for (const rel of SCAFFOLD) {
+      expect(j[rel].hash, `${rel} baseline was rewritten`).toBe(seededHashes[rel]);
+      expect(j[rel].remoteEtag, `${rel} remote side touched`).toBe("seed-etag");
+      // and the local file genuinely changed, so the entry is push-visible
+      expect(j[rel].hash).not.toBe(hashFile(path.join(hqRoot, rel)));
+    }
+
+    // SAFETY: the personal/ pending edit is untouched too — still uploads.
+    expect(j["personal/edited.md"].hash).toBe("remote-side-hash-differs-from-local");
+    expect(j["personal/edited.md"].hash).not.toBe(hashFile(path.join(hqRoot, "personal/edited.md")));
 
-    // journal entry was re-stamped to the NEW content's hash
-    const entry = readJournal(PERSONAL_VAULT_JOURNAL_SLUG).files["core/doc.md"];
-    expect(entry.hash).toBe(hashFile(docAbs)); // == hash(v2): localChanged would be FALSE
-    expect(entry.hash).not.toBe(staleHash); // proves it changed from the stale v1 baseline
-    expect(entry.remoteEtag).toBe("seed-etag"); // remote side untouched -> clean push/converge, not conflict
-    expect(r.stdout).toContain("Reconciled sync-journal baseline");
+    // the masking reconcile is gone
+    expect(r.stdout).not.toContain("Reconciled sync-journal baseline");
+  });
+
+  it("stamps core.yaml deterministically: byte-identical across runs, last_sync_at = source committer time", () => {
+    const coreYaml = path.join(hqRoot, "core/core.yaml");
+    const firstRun = fs.readFileSync(coreYaml, "utf-8");
+
+    // last_sync_at must be derived from the HEAD commit, not wall-clock now.
+    // utcStamp(_, "colon") renders UTC as YYYY-MM-DDTHH:MM:SSZ — compare on
+    // the epoch second, not the string, to stay offset-agnostic.
+    const stamped = /last_sync_at:\s*["']?([0-9TZ:.-]+)["']?/.exec(firstRun);
+    expect(stamped, `no last_sync_at in:\n${firstRun}`).not.toBeNull();
+    expect(new Date(stamped![1]).getTime()).toBe(new Date(headCommitterIso).getTime());
+
+    // a second rescue of the SAME SHA must write byte-identical core.yaml —
+    // this is the cross-machine `core.yaml.conflict-*` mirror regression.
+    const r2 = runRescueCapture(
+      ["--hq-root", hqRoot, "--source", "test/repo", "--ref", "main", "--floor-sha", floorSha, "--yes", "--no-backup"],
+      env,
+    );
+    expect(r2.status, r2.stdout).toBe(0);
+    expect(fs.readFileSync(coreYaml, "utf-8")).toBe(firstRun);
   });
 });

package/src/cli/share.ts

@@ -30,6 +30,8 @@ import {
   updateEntry,
   removeEntry,
   normalizeEtag,
+  PERSONAL_VAULT_JOURNAL_SLUG,
+  migratePersonalVaultJournal,
 } from "../journal.js";
 import { createIgnoreFilter, isWithinSizeLimit } from "../ignore.js";
 import {
@@ -755,6 +757,10 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
     ? wrapFilterWithPersonalVaultDefaults(ignoreFilter, syncRoot, onExcluded)
     : ignoreFilter;
   const journalSlug = options.journalSlug ?? ctx.slug;
+  // Seed the canonical personal-vault journal from the legacy `personal` file
+  // exactly once — engine-side so every consumer (sync-runner, hq-cli) gets
+  // it; see the matching guard in sync.ts.
+  if (journalSlug === PERSONAL_VAULT_JOURNAL_SLUG) migratePersonalVaultJournal();
   const journal = readJournal(journalSlug);
 
   let filesUploaded = 0;

package/src/cli/sync-scope.test.ts

@@ -48,7 +48,12 @@ vi.mock("../s3.js", async () => {
         if (!innerFs.existsSync(dir)) innerFs.mkdirSync(dir, { recursive: true });
         // Deterministic per-key body so re-downloads produce a stable hash.
         innerFs.writeFileSync(localPath, `mock:${key}`);
-        return { metadata: {} };
+        // Real GETs carry author metadata; surface a fixed uploader sub so
+        // journal entries are stamped with a KNOWN author. With no `callerSub`
+        // passed (the default for these tests), that author is "foreign", so
+        // the scope-shrink prune/block paths behave exactly as pre-guard —
+        // only the new own-author retention test passes a matching callerSub.
+        return { metadata: { "created-by-sub": "uploader-sub" } };
       }),
     listRemoteFiles: innerVi.fn().mockImplementation(async () => REMOTE.current),
     deleteRemoteFile: innerVi.fn().mockResolvedValue(undefined),
@@ -230,6 +235,35 @@ describe("sync — scope-aware download (US-005)", () => {
     expect(fs.existsSync(companyRel("knowledge/readme.md"))).toBe(true);
   });
 
+  it("scope shrink (all → shared) RETAINS the owner's own out-of-scope file", async () => {
+    // Corey's exact scenario: the caller authored everything (the mock stamps
+    // `created-by-sub: "uploader-sub"`), so passing the matching `callerSub`
+    // means narrowing to `shared` must NOT prune their own work — mode only
+    // governs mirroring OTHER people's files.
+    const all = await sync({
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      syncMode: "all",
+      callerSub: "uploader-sub",
+    });
+    expect(all.filesDownloaded).toBe(2);
+
+    const shared = await sync({
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      syncMode: "shared",
+      prefixSet: ["knowledge/"],
+      callerSub: "uploader-sub",
+    });
+    // Out of scope, but authored by the caller → retained, not pruned.
+    expect(shared.scopeOrphansRemoved).toBe(0);
+    expect(shared.scopeOrphansBlocked).toBe(0);
+    expect(fs.existsSync(companyRel("docs/handoff.md"))).toBe(true);
+    expect(fs.existsSync(companyRel("knowledge/readme.md"))).toBe(true);
+  });
+
   it("refuses a bulk auto-prune over the safety cap, then proceeds when forced", async () => {
     // Pull both files under all-mode, then narrow to a scope covering neither
     // → 2 clean orphans. With the cap set to 1, the auto-prune is refused.

package/src/cli/sync.ts

@@ -31,6 +31,8 @@ import {
   lastPullRecord,
   appendPullRecord,
   generatePullId,
+  PERSONAL_VAULT_JOURNAL_SLUG,
+  migratePersonalVaultJournal,
 } from "../journal.js";
 import {
   buildScopeShrinkPlan,
@@ -330,6 +332,14 @@ export interface SyncOptions {
    * tombstoned. Mirrors `hq sync narrow --force`.
    */
   forceScopeShrink?: boolean;
+  /**
+   * The caller's own Cognito `sub`, used by the scope-shrink authorship guard
+   * so a scope shrink never prunes content the caller authored. Injected by the
+   * entry point — the runner sources it from its decoded idToken claims (the
+   * same sub stamped onto uploads as `created-by-sub`). The engine never reads
+   * it from disk, so it stays pure/hermetic; undefined degrades safely.
+   */
+  callerSub?: string;
   /**
    * Skip the post-sync `reindex()` refresh (skill wrappers + personal overlay
    * mirrors + workers registry). By default, when a sync changes on-disk
@@ -518,6 +528,12 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
   const shouldSync = createIgnoreFilter(hqRoot);
   const journalSlug = options.journalSlug ?? ctx.slug;
   const startedAt = new Date().toISOString();
+  // Personal-vault callers must never start from an empty journal when only
+  // the legacy `personal` file exists (mass re-download/etag churn). Seeding
+  // here — inside the engine — covers every consumer (sync-runner already
+  // seeds; hq-cli historically didn't, which split the vault's bookkeeping
+  // across two journal files and re-flagged synced files as conflicts).
+  if (journalSlug === PERSONAL_VAULT_JOURNAL_SLUG) migratePersonalVaultJournal();
   // Migrate v1 → v2 in place so the scope-shrink / pull-record machinery has
   // its fields, and GC any tombstones past the 30-day retention window before
   // we re-evaluate orphans (so a long-pruned path can re-download cleanly).
@@ -536,6 +552,13 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
   const syncMode: SyncMode = options.syncMode ?? "all";
   const currentPrefixSet =
     syncMode === "all" ? [""] : coalescePrefixes(options.prefixSet ?? []);
+  // Authorship guard input (scope-shrink): the caller's own Cognito sub,
+  // injected by the entry point (the runner sources it from its decoded
+  // idToken claims — the same sub stamped onto uploads as `created-by-sub`).
+  // Undefined degrades safely: own-author files lose their special shield, but
+  // the `protectUnknownAuthors` conservative path below still prevents a
+  // routine sync from deleting anything it can't prove is foreign.
+  const callerSub = options.callerSub;
 
   let filesDownloaded = 0;
   let bytesDownloaded = 0;
@@ -603,6 +626,11 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
     hqRoot: companyRoot,
     lastPrefixSet,
     currentPrefixSet,
+    callerSub,
+    // Automatic pull: never auto-prune content the caller authored, and never
+    // make a destructive guess about unknown-author (legacy) orphans. The
+    // explicit `hq sync narrow` ritual opts out of the unknown-author shield.
+    protectUnknownAuthors: true,
   });
   if (shrinkPlan.dirty.length > 0 && options.forceScopeShrink !== true) {
     throw new ScopeShrinkBlockedError(
@@ -988,6 +1016,9 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
       try {
         const { metadata } = await downloadFile(ctx, remoteFile.key, localPath);
         const author = metadata?.["created-by"] ?? null;
+        // Author sub for the scope-shrink authorship guard — same field the
+        // upload side stamps, read straight off the GET response metadata.
+        const createdBySub = metadata?.["created-by-sub"];
 
         // Symlink records materialize as real symlinks on disk. lstat
         // (does not follow) lets us detect that case so the journal stamp
@@ -1026,6 +1057,7 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
           "down",
           remoteFile.etag,
           localLstat.mtimeMs,
+          createdBySub,
         );
 
         // Attach message from the prior journal entry if present (set by a

package/src/index.ts

@@ -41,6 +41,13 @@ export {
   gcTombstones,
   TOMBSTONE_TTL_MS,
   JOURNAL_VERSION_CURRENT,
+  // Canonical personal-vault journal slug + its one-time legacy seed. Exported
+  // so downstream CLIs (hq-cli `sync --personal`) journal the personal vault
+  // under the SAME slug as hq-sync-runner. hq-cli hardcoding the legacy
+  // `"personal"` slug split the vault's bookkeeping across two journal files —
+  // each surface re-flagged the other's already-synced files as conflicts.
+  PERSONAL_VAULT_JOURNAL_SLUG,
+  migratePersonalVaultJournal,
 } from "./journal.js";
 
 // Prefix coalescing helper (US-005)

package/src/journal.ts

@@ -211,6 +211,7 @@ export function updateEntry(
   direction: "up" | "down",
   remoteEtag?: string,
   mtimeMs?: number,
+  createdBySub?: string,
 ): void {
   const entry: JournalEntry = {
     hash,
@@ -224,6 +225,12 @@ export function updateEntry(
   if (mtimeMs !== undefined) {
     entry.mtimeMs = mtimeMs;
   }
+  // Authorship (scope-shrink guard input). Stamped from the object's
+  // `created-by-sub` S3 metadata on download. Only persisted when present so
+  // legacy journals and author-less uploads stay byte-identical.
+  if (createdBySub !== undefined && createdBySub !== "") {
+    entry.createdBySub = createdBySub;
+  }
   journal.files[relativePath] = entry;
   journal.lastSync = new Date().toISOString();
 }

package/src/public-surface.test.ts

@@ -33,6 +33,11 @@ describe("public package surface contract (@indigoai-us/hq-cloud)", () => {
     "VendInput",
     "VendResult",
     "VendCredentials",
+    // Canonical personal-vault journal slug (+ legacy seed) — consumed by
+    // hq-cli `sync --personal` so the CLI and hq-sync-runner journal the
+    // vault under ONE slug (split-brain regression, 2026-06-10).
+    "PERSONAL_VAULT_JOURNAL_SLUG",
+    "migratePersonalVaultJournal",
   ] as const;
 
   it.each(SYNC_BROWSE_NAMES)(