@indigoai-us/hq-cloud 6.2.3 → 6.2.5

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

@@ -1,20 +1,23 @@
 /**
- * Regression for the rescue -> sync-journal stale-baseline bug (and its
- * follow-ups). The rescue overlay + the post-overlay core.yaml stamp rewrite
- * scaffold files from upstream, but their personal-vault journal entries keep
- * the PRE-rescue hash. The next sync then reads localHash != journal.hash
- * ("local changed") and mints a false `.conflict-*` mirror.
+ * Regression for the rescue <-> sync-journal interaction (6.2.4 semantics).
  *
- * runRescue now reconciles the baseline by DIFFING the journal against current
- * local hashes (robust — the earlier rsync-itemize regex undercounted), running
- * AFTER every in-doRescue mutation (so it also catches the core.yaml stamp), and
- * scoped to NON-preserved roots so a user's pending edit in personal/ is never
- * marked synced.
+ * 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 stale baselines for several overlaid scaffold files + core.yaml
- * and a pending personal/ edit, runs a real rescue, and asserts: every changed
- * scaffold entry is re-stamped to current local (no false conflict), while the
- * personal/ pending edit is left untouched (still uploads).
+ * 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";
@@ -57,10 +60,12 @@ function runRescueCapture(argv: string[], env: NodeJS.ProcessEnv) {
 
 const SCAFFOLD = ["core/a.md", "core/docs/b.md", ".claude/c.sh", "core/core.yaml"];
 
-describe.skipIf(!gitAvailable)("rescue reconciles sync-journal baseline (complete + robust)", () => {
+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, {
@@ -92,6 +97,7 @@ describe.skipIf(!gitAvailable)("rescue reconciles sync-journal baseline (complet
     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: scaffold == floor (overlaid to v2); a pending personal/ edit ---
     hqRoot = path.join(workDir, "hq");
@@ -102,7 +108,7 @@ describe.skipIf(!gitAvailable)("rescue reconciles sync-journal baseline (complet
     w(hqRoot, "core/core.yaml", "version: 1\n");
     w(hqRoot, "personal/edited.md", "USER_LOCAL\n"); // local pending edit
 
-    // --- state dir + seeded journal: stale baselines for scaffold + a divergent personal/ entry ---
+    // --- 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;
@@ -116,7 +122,12 @@ describe.skipIf(!gitAvailable)("rescue reconciles sync-journal baseline (complet
       mtimeMs: fs.statSync(path.join(hqRoot, rel)).mtimeMs,
     });
     const files: Record<string, unknown> = {};
-    for (const rel of SCAFFOLD) files[rel] = entry(rel, hashFile(path.join(hqRoot, rel))); // hash of v1/version:1
+    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, {
@@ -147,7 +158,7 @@ exec ${JSON.stringify(realGit)} "$@"
     if (workDir) fs.rmSync(workDir, { recursive: true, force: true });
   });
 
-  it("re-stamps EVERY changed scaffold file (incl. core.yaml), and never touches the personal/ pending edit", () => {
+  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,
@@ -161,19 +172,44 @@ exec ${JSON.stringify(realGit)} "$@"
 
     const j = readJournal(PERSONAL_VAULT_JOURNAL_SLUG).files;
 
-    // INVARIANT: after the reconcile, every scaffold entry's baseline == current
-    // local hash -> localChanged is false -> no false conflict on the next sync.
-    // core.yaml is included BECAUSE the reconcile runs AFTER its yq/py stamp.
+    // 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} not reconciled`).toBe(hashFile(path.join(hqRoot, rel)));
-      expect(j[rel].remoteEtag, `${rel} remote side touched`).toBe("seed-etag"); // clean push/converge, not conflict
+      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 preserved (NOT marked synced) so it
-    // still uploads — its baseline stays the divergent seeded hash.
+    // 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")));
 
-    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 {
@@ -216,6 +218,21 @@ export function isEphemeralPath(p: string): boolean {
   return EPHEMERAL_PATH_PATTERN.test(p);
 }
 
+/**
+ * A vault key containing a backslash is never legitimate. HQ keys are POSIX
+ * (`toPosixKey` normalizes at every walker since 5.47.2 and `uploadFile`
+ * hard-normalizes at the S3 boundary), so a `\` in a remote key can only come
+ * from a pre-5.47.2 Windows client whose walker built keys with `path.sep` —
+ * verified live 2026-06-10: one such client duplicated 5,711 keys
+ * (`skills\demo-hq\SKILL.md`, …) into a company vault, and every up-to-date
+ * puller then materialized them as junk single-filename-with-backslash files
+ * that churned conflicts forever. The pull walker refuses these keys
+ * (skip-excluded-policy), symmetric with the ephemeral-mirror filter above.
+ */
+export function isMalformedVaultKey(key: string): boolean {
+  return key.includes("\\");
+}
+
 /**
  * Test-only export. Kept under a `_testing` namespace so the module's public
  * surface stays focused on `share()` / `ShareOptions` / `ShareResult` while
@@ -755,6 +772,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.test.ts

@@ -1100,6 +1100,42 @@ describe("sync", () => {
     expect(result.filesExcludedByPolicy).toBeGreaterThanOrEqual(1);
   });
 
+  it("skips remote keys containing backslashes (malformed Windows-client keys)", async () => {
+    // A pre-5.47.2 Windows client built S3 keys with path.sep, duplicating a
+    // company tree under keys like `skills\\demo-hq\\SKILL.md` (verified live
+    // 2026-06-10: 5,711 such keys in one vault). On POSIX, downloading one
+    // creates a junk FILE whose name contains backslashes, which then churns
+    // conflict mirrors on every sync. The pull planner must refuse them at
+    // planning time — same policy bucket as the ephemeral-mirror filter.
+    vi.mocked(s3Module.listRemoteFiles).mockResolvedValueOnce([
+      // Malformed Windows key — must be filtered, never downloaded.
+      {
+        key: "skills\\demo\\SKILL.md",
+        size: 44,
+        lastModified: new Date(),
+        etag: '"abc"',
+      },
+      // Its legitimate POSIX twin — must still download.
+      { key: "skills/demo/SKILL.md", size: 30, lastModified: new Date(), etag: '"def"' },
+    ]);
+
+    const result = await sync({
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+    });
+
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    // The malformed key MUST NOT be materialized — neither as a literal
+    // backslash-named file nor as a nested path.
+    expect(fs.existsSync(path.join(companyRoot, "skills\\demo\\SKILL.md"))).toBe(false);
+    // The legitimate twin MUST download.
+    expect(fs.existsSync(path.join(companyRoot, "skills", "demo", "SKILL.md"))).toBe(true);
+
+    expect(result.filesDownloaded).toBe(1);
+    expect(result.filesExcludedByPolicy).toBeGreaterThanOrEqual(1);
+  });
+
   it("overwrites local on --on-conflict overwrite", async () => {
     const companyDocs = path.join(tmpDir, "companies", "acme", "docs");
     fs.mkdirSync(companyDocs, { recursive: true });

package/src/cli/sync.ts

@@ -31,6 +31,8 @@ import {
   lastPullRecord,
   appendPullRecord,
   generatePullId,
+  PERSONAL_VAULT_JOURNAL_SLUG,
+  migratePersonalVaultJournal,
 } from "../journal.js";
 import {
   buildScopeShrinkPlan,
@@ -40,7 +42,7 @@ import {
 } from "../scope-shrink.js";
 import { coalescePrefixes, isCoveredByAny } from "../prefix-coalesce.js";
 import { createIgnoreFilter } from "../ignore.js";
-import { isEphemeralPath } from "./share.js";
+import { isEphemeralPath, isMalformedVaultKey } from "./share.js";
 import { resolveConflict } from "./conflict.js";
 import type { ConflictStrategy, ConflictResolution } from "./conflict.js";
 import {
@@ -526,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).
@@ -1469,6 +1477,17 @@ function computePullPlan(
       continue;
     }
 
+    // Malformed-key filter — keys with backslash separators pushed by
+    // pre-5.47.2 Windows clients. Downloading one materializes a junk local
+    // file whose NAME contains backslashes (it is not a path on POSIX), which
+    // then churns conflict mirrors forever. Refuse at planning time, same
+    // policy bucket as the ephemeral filter above. The bogus keys themselves
+    // are cleaned server-side; this keeps clean trees clean in the meantime.
+    if (isMalformedVaultKey(remoteFile.key)) {
+      items.push({ action: "skip-excluded-policy", remoteFile, localPath });
+      continue;
+    }
+
     if (personalMode && remoteFile.key.startsWith("companies/")) {
       // Default: drop every `companies/...` key — the legacy contract
       // is that the personal bucket should never contain them.

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/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)(