@indigoai-us/hq-cloud 6.14.5 → 6.14.7

package/src/cli/share.test.ts

@@ -595,6 +595,60 @@ describe("share", () => {
     });
   });
 
+  it("cloud-authoritative: never pushes a stale local ontology/.last-run over the server value (one-sided-change clobber guard)", async () => {
+    // Regression for the gardener watermark clobber. A second HQ root sharing this
+    // machine's sync journal can leave the local mirror holding a STALE value A while
+    // the shared journal has already been advanced to the gardener's value B (etag EB).
+    // On this root's push leg that reads as localChanged (A != journal B) &&
+    // !remoteChanged (remote etag EB == journal remoteEtag EB). Previously that
+    // one-sided combination slipped past the CONFLICT-scoped isCloudAuthoritative
+    // fence and PUT the stale local value back over the server's — rewinding it. The
+    // fence now runs at the TOP of processUploadItem, so any ontology/ (server-owned)
+    // path is skipped before HEAD/upload regardless of the divergence shape.
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    fs.mkdirSync(path.join(companyRoot, "ontology"), { recursive: true });
+    const testFile = path.join(companyRoot, "ontology", ".last-run");
+    fs.writeFileSync(testFile, "1782275168000"); // stale value A
+
+    // The journal is already advanced to the gardener's value B (a sibling HQ root's
+    // pull stamped the shared journal), so localChanged=true. The fence skips the file
+    // BEFORE any HEAD/upload, so we deliberately queue NO headRemoteFile response and
+    // assert it is never consulted below — the skip is cheap, and a leftover
+    // mockResolvedValueOnce would otherwise leak into a later test's HEAD queue.
+    const journalPath = path.join(stateDir, "sync-journal.acme.json");
+    fs.writeFileSync(
+      journalPath,
+      JSON.stringify({
+        version: "1",
+        lastSync: new Date().toISOString(),
+        files: {
+          "ontology/.last-run": {
+            hash: "advanced-value-B-hash", // != hash(A) → localChanged=true
+            size: 13,
+            syncedAt: new Date().toISOString(),
+            direction: "up",
+            remoteEtag: "eb-advanced-etag", // == remote → remoteChanged=false
+          },
+        },
+      }),
+    );
+
+    const result = await share({
+      paths: [testFile],
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+    });
+
+    // Server-owned file: push is skipped BEFORE HEAD, the stale local value is NEVER
+    // uploaded (the pull leg refreshes local from cloud instead), and it is not a conflict.
+    expect(uploadFile).not.toHaveBeenCalled();
+    expect(headRemoteFile).not.toHaveBeenCalled();
+    expect(result.filesUploaded).toBe(0);
+    expect(result.filesSkipped).toBeGreaterThanOrEqual(1);
+    expect(result.conflictPaths).toEqual([]);
+  });
+
   it("first-time-upload-with-cloud-collision: emits conflict + writes mirror under --on-conflict keep (Bug #7)", async () => {
     // Bug #7 (data-loss class) from the 5.33.0 deep test: when a file has
     // NO prior journal entry (fresh upload from this machine) but the

package/src/cli/share.ts

@@ -11,6 +11,7 @@ import * as path from "path";
 import type { EntityContext, VaultServiceConfig, SyncJournal } from "../types.js";
 import { resolveEntityContext, isExpiringSoon, refreshEntityContext } from "../context.js";
 import { createSyncProgressRecorder } from "../sync-progress.js";
+import { localPathForVaultKey, vaultKeyForLocalPath } from "../local-path-codec.js";
 import {
   uploadFile,
   uploadSymlink,
@@ -788,7 +789,7 @@ function wrapFilterWithScope(
 ): (absPath: string, isDir?: boolean) => boolean {
   return (absPath: string, isDir?: boolean) => {
     if (!underlying(absPath, isDir)) return false;
-    const rel = path.relative(syncRoot, absPath).split(path.sep).join("/");
+    const rel = vaultKeyForLocalPath(syncRoot, absPath);
     if (rel === "" || rel.startsWith("..")) return true; // root / outside — defer
     if (isDir) {
       if (isDirInScope(rel, prefixSet)) return true;
@@ -819,7 +820,7 @@ export function wrapFilterWithIgnoreVisibility(
     if (allowed) return true;
 
     onAnyExcluded?.();
-    const rel = path.relative(hqRoot, absPath).split(path.sep).join("/");
+    const rel = vaultKeyForLocalPath(hqRoot, absPath);
     if (rel === "" || rel.startsWith("..")) return false;
     if (!isExpectedIgnore(rel)) onIgnoreExcluded(rel);
     return false;
@@ -1232,6 +1233,19 @@ async function executeUploads(
     if (aborted) return;
     const { absolutePath, relativePath, localHash } = item;
 
+    // Cloud-authoritative paths (server-regenerated: company-brief.md, board.json,
+    // ontology/ signals/ sources/) are PULL-WINS and server-owned. The push leg must
+    // NEVER upload the local copy over them — not just on a two-sided conflict, but on
+    // ANY divergence, including a one-sided local change. A stale local mirror (e.g. a
+    // second HQ root that shares this machine's sync journal) would otherwise read as
+    // `localChanged && !remoteChanged`, slip past the conflict-scoped guard below, and
+    // rewind the server's value — the `.last-run` watermark clobber. Skip before HEAD.
+    if (isCloudAuthoritative(relativePath)) {
+      run.emit({ type: "reconciled", path: relativePath, direction: "push" });
+      counters.filesSkipped++;
+      return;
+    }
+
     if (run.vaultConfig && isExpiringSoon(run.ctx.expiresAt)) {
       run.ctx = await refreshEntityContext(run.companyRef, run.vaultConfig);
     }
@@ -1286,16 +1300,9 @@ async function executeUploads(
       }
 
       if ((localChanged && remoteChanged) || isFreshCollision) {
-        // Cloud-authoritative paths (server-regenerated: company-brief.md,
-        // board.json, ontology/ signals/ sources/) are PULL-WINS. Never push the
-        // local copy over the server-owned version and never mint a `.conflict-`
-        // mirror — the pull leg overwrites local from cloud. Declining here is
-        // what stops the per-sync conflict-mirror loop on these files.
-        if (isCloudAuthoritative(relativePath)) {
-          run.emit({ type: "reconciled", path: relativePath, direction: "push" });
-          counters.filesSkipped++;
-          return;
-        }
+        // Cloud-authoritative paths are already skipped at the top of
+        // processUploadItem (before HEAD), so anything reaching here is a genuine
+        // conflict on a client-owned file.
         conflictPaths.push(relativePath);
 
         const resolution = await resolveConflictSerialized({
@@ -1450,13 +1457,13 @@ async function writePushConflictMirror(
   try {
     const detectedAt = new Date().toISOString();
     const machineId = readShortMachineId(run.hqRoot);
-    const originalRelative = path.relative(run.hqRoot, item.absolutePath);
+    const originalRelative = vaultKeyForLocalPath(run.hqRoot, item.absolutePath);
     const conflictRelative = buildConflictPath(
       originalRelative,
       detectedAt,
       machineId,
     );
-    const conflictAbs = path.join(run.hqRoot, conflictRelative);
+    const conflictAbs = localPathForVaultKey(run.hqRoot, conflictRelative);
     if (!isMaterializationPathStillContained(run.syncRoot, conflictAbs)) {
       run.emit({
         type: "error",
@@ -1781,7 +1788,7 @@ function collectFiles(
         console.error(`  Warning: ${p} is outside company folder, skipping.`);
         continue;
       }
-      const relativePath = toPosixKey(path.relative(syncRoot, absolutePath));
+      const relativePath = vaultKeyForLocalPath(syncRoot, absolutePath);
       // Probe the filter with both isDir hints — we don't know whether
       // the link's target is a file or a directory without
       // stat-following the link, which we explicitly avoid (it would
@@ -1811,7 +1818,7 @@ function collectFiles(
       if (!filter(absolutePath, true)) continue;
       results.push(...walkDir(absolutePath, syncRoot, filter));
     } else if (lstat.isFile()) {
-      const relativePath = toPosixKey(path.relative(syncRoot, absolutePath));
+      const relativePath = vaultKeyForLocalPath(syncRoot, absolutePath);
       if (filter(absolutePath)) {
         results.push({ kind: "file", absolutePath, relativePath });
       }
@@ -1861,7 +1868,7 @@ function walkDir(
       results.push({
         kind: "symlink",
         absolutePath,
-        relativePath: toPosixKey(path.relative(syncRoot, absolutePath)),
+        relativePath: vaultKeyForLocalPath(syncRoot, absolutePath),
         target: fs.readlinkSync(absolutePath),
       });
       continue;
@@ -1877,7 +1884,7 @@ function walkDir(
       results.push({
         kind: "file",
         absolutePath,
-        relativePath: toPosixKey(path.relative(syncRoot, absolutePath)),
+        relativePath: vaultKeyForLocalPath(syncRoot, absolutePath),
       });
     }
   }
@@ -1996,11 +2003,11 @@ function resolveDeleteScopeRoots(
     if (!isWithin(syncRoot, absolutePath)) continue;
     const stat = fs.statSync(absolutePath);
     if (!stat.isDirectory()) continue;
-    const rel = path.relative(syncRoot, absolutePath);
+    const rel = vaultKeyForLocalPath(syncRoot, absolutePath);
     if (rel === "" || rel === ".") {
       return [""];
     }
-    prefixes.add(rel.split(path.sep).join("/"));
+    prefixes.add(rel);
   }
   return Array.from(prefixes);
 }
@@ -2238,7 +2245,7 @@ async function computeDeletePlan(
     );
     if (!inScope) continue;
     inScopeJournalEntries++;
-    const localPath = path.join(syncRoot, relativeKey);
+    const localPath = localPathForVaultKey(syncRoot, relativeKey);
     let presentLocally = true;
     try {
       fs.lstatSync(localPath);

package/src/cli/sync.ts

@@ -19,6 +19,7 @@ import {
 } from "../telemetry-events.js";
 import { resolveEntityContext, isExpiringSoon, refreshEntityContext } from "../context.js";
 import { createSyncProgressRecorder } from "../sync-progress.js";
+import { localPathForVaultKey, vaultKeyForLocalPath } from "../local-path-codec.js";
 import {
   downloadFile,
   listRemoteFiles,
@@ -26,7 +27,7 @@ import {
   primeObjectTransport,
   toPosixKey,
 } from "../s3.js";
-import type { RemoteFile } from "../s3.js";
+import type { DownloadModeWarning, RemoteFile } from "../s3.js";
 import {
   readJournal,
   writeJournal,
@@ -971,6 +972,30 @@ function reportInvalidScopedKeys(run: PullRunContext, plan: PullPlan): void {
   }, { claims: run.options.telemetryClaims });
 }
 
+/**
+ * A legacy object without hq-mode can otherwise downgrade a hook to the
+ * receiver umask with no durable signal. downloadFile already prints a local
+ * warning for every caller; the sync path also records a path-free telemetry
+ * event so operators can find vaults that still need the one-time backfill.
+ */
+function reportModeWarnings(
+  run: PullRunContext,
+  warnings: DownloadModeWarning[] | undefined,
+): void {
+  for (const warning of warnings ?? []) {
+    void emitCloudTelemetry(new VaultClient(run.vaultConfig), {
+      eventName: "sync_mode_guardrail_warning",
+      source: "hq-sync",
+      companyUid: run.ctx.uid,
+      properties: {
+        leg: "pull",
+        reason: warning.reason,
+        fallback: warning.fallback ?? null,
+      },
+    }, { claims: run.options.telemetryClaims });
+  }
+}
+
 function createPullCounters(): PullCounters {
   return {
     filesDownloaded: 0,
@@ -1220,7 +1245,7 @@ async function executeConflictItem(
   // the REMOTE hash/etag) and skip the conflict path entirely. This removes both
   // the `.conflict-` mirror loop AND the journal false-stamp (remote etag over
   // divergent local content) that the keep path produced for these files.
-  if (isCloudAuthoritative(path.relative(run.hqRoot, localPath))) {
+  if (isCloudAuthoritative(vaultKeyForLocalPath(run.hqRoot, localPath))) {
     downloadItems.push({ action: "download", remoteFile, localPath, isNew: false });
     run.emit({ type: "reconciled", path: remoteFile.key, direction: "pull" });
     return null;
@@ -1230,14 +1255,14 @@ async function executeConflictItem(
 
   const detectedAt = new Date().toISOString();
   const machineId = readShortMachineId(run.hqRoot);
-  const originalRelative = path.relative(run.hqRoot, localPath);
+  const originalRelative = vaultKeyForLocalPath(run.hqRoot, localPath);
   const conflictRelative = buildConflictPath(
     originalRelative,
     detectedAt,
     machineId,
   );
-  const conflictAbs = path.join(run.hqRoot, conflictRelative);
-  const conflictKey = toPosixKey(path.relative(run.companyRoot, conflictAbs));
+  const conflictAbs = localPathForVaultKey(run.hqRoot, conflictRelative);
+  const conflictKey = vaultKeyForLocalPath(run.companyRoot, conflictAbs);
 
   if (!isDownloadWritePathStillContained(run.companyRoot, conflictKey, conflictAbs)) {
     counters.filesSkipped++;
@@ -1459,11 +1484,12 @@ async function downloadOne(
   }
 
   try {
-    const { metadata, contentHash, contentSize } = await downloadFile(
+    const { metadata, contentHash, contentSize, modeWarnings } = await downloadFile(
       run.ctx,
       remoteFile.key,
       localPath,
     );
+    reportModeWarnings(run, modeWarnings);
     const author = metadata?.["created-by"] ?? null;
     const createdBySub = metadata?.["created-by-sub"];
 
@@ -1803,7 +1829,7 @@ function resolveContainedVaultPath(root: string, key: string): string | null {
   if (isMalformedVaultKey(key) || hasTraversalSegment(key)) return null;
 
   const resolvedRoot = path.resolve(root);
-  const resolvedLocal = path.resolve(resolvedRoot, key);
+  const resolvedLocal = localPathForVaultKey(resolvedRoot, key);
   if (!isPathWithin(resolvedRoot, resolvedLocal)) return null;
 
   let realRoot: string;

package/src/local-path-codec.ts

@@ -0,0 +1,95 @@
+/**
+ * Reversible local filename adapter for canonical vault keys on Win32.
+ *
+ * Vault keys are POSIX identifiers and may contain ':' (for example
+ * `factory:slack`).  Win32 cannot materialize those strings as filename
+ * segments, so keep the key canonical in S3 and journals while encoding only
+ * the local segment that reaches the filesystem.
+ */
+import * as path from "path";
+
+const WIN32_RESERVED_CHARS = /[<>:"/\\|?*]/;
+const WIN32_DEVICE_NAME = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\..*)?$/i;
+
+function isWin32ReservedCharacter(char: string): boolean {
+  return char.charCodeAt(0) <= 0x1f || WIN32_RESERVED_CHARS.test(char);
+}
+
+function percentEscape(char: string): string {
+  return `%${char.charCodeAt(0).toString(16).toUpperCase().padStart(2, "0")}`;
+}
+
+/**
+ * Encode one canonical vault-key segment for a Win32 filename. Percent is
+ * escaped before every other character so decoding cannot collide with a
+ * literal `%3A` name. The optional flag makes platform-specific behavior
+ * directly testable without mutating `process.platform`.
+ */
+export function encodeLocalVaultSegment(
+  segment: string,
+  win32: boolean = process.platform === "win32",
+): string {
+  if (!win32) return segment;
+
+  let encoded = "";
+  for (let index = 0; index < segment.length; index++) {
+    const char = segment[index]!;
+    const isTrailingDotOrSpace =
+      index === segment.length - 1 && (char === "." || char === " ");
+    const isDotSegment = (segment === "." || segment === "..") && index === 0;
+    const isReservedDeviceFirstChar = WIN32_DEVICE_NAME.test(segment) && index === 0;
+    if (
+      char === "%" ||
+      isWin32ReservedCharacter(char) ||
+      isTrailingDotOrSpace ||
+      isDotSegment ||
+      isReservedDeviceFirstChar
+    ) {
+      encoded += percentEscape(char);
+    } else {
+      encoded += char;
+    }
+  }
+  return encoded;
+}
+
+/** Decode one local filename segment back to its canonical vault-key form. */
+export function decodeLocalVaultSegment(
+  segment: string,
+  win32: boolean = process.platform === "win32",
+): string {
+  if (!win32) return segment;
+  return segment.replace(/%([0-9a-f]{2})/gi, (_whole, hex: string) =>
+    String.fromCharCode(Number.parseInt(hex, 16)),
+  );
+}
+
+/** Materialize a canonical slash-delimited vault key beneath a local root. */
+export function localPathForVaultKey(
+  root: string,
+  key: string,
+  win32: boolean = process.platform === "win32",
+): string {
+  return path.join(
+    root,
+    ...key.split("/").map((segment) => encodeLocalVaultSegment(segment, win32)),
+  );
+}
+
+/**
+ * Turn a local, root-relative path back into its canonical vault key. This
+ * recognizes legacy percent-encoded Windows materializations as well as the
+ * current codec, so they converge on one remote/journal key instead of
+ * creating duplicates.
+ */
+export function vaultKeyForLocalPath(
+  root: string,
+  localPath: string,
+  win32: boolean = process.platform === "win32",
+): string {
+  return path
+    .relative(root, localPath)
+    .split(path.sep)
+    .map((segment) => decodeLocalVaultSegment(segment, win32))
+    .join("/");
+}

package/src/s3.ts

@@ -764,6 +764,13 @@ export async function uploadSymlink(
  * return it to callers — e.g. the pull loop reads `created-by` to
  * attribute downloaded files to their author with zero extra network.
  */
+export interface DownloadModeWarning {
+  /** The mode guardrail that could not be applied exactly. */
+  reason: "missing-hq-mode" | "invalid-hq-mode" | "chmod-failed";
+  /** Legacy objects can retain a local file's known-good permission bits. */
+  fallback?: "preserved-local-mode" | "receiver-default";
+}
+
 export async function downloadFile(
   ctx: EntityContext,
   key: string,
@@ -772,6 +779,8 @@ export async function downloadFile(
   metadata?: Record<string, string>;
   contentHash?: string;
   contentSize?: number;
+  /** Non-fatal mode guardrail warnings for caller telemetry. */
+  modeWarnings?: DownloadModeWarning[];
 }> {
   const io = resolveObjectIO(ctx);
 
@@ -867,15 +876,25 @@ export async function downloadFile(
     return { metadata };
   }
   const tempPath = downloadTempPath(localPath);
+  // A legacy object has no hq-mode. If it is replacing a regular local file,
+  // that local mode is the only trustworthy signal we have — retaining it is
+  // strictly safer than replacing (for example) a 0755 hook with the receiver
+  // umask's usual 0644. Never inspect a symlink or infer intent from content.
+  let existingLocalMode: number | undefined;
+  try {
+    const existing = fs.lstatSync(localPath);
+    if (existing.isFile()) existingLocalMode = existing.mode & 0o777;
+  } catch {
+    // Fresh destination / inaccessible prior path: no local fallback.
+  }
   let tempReady = true;
   let streamed: { hash: string; size: number };
+  const modeWarnings: DownloadModeWarning[] = [];
   try {
     streamed = await streamRegularFileToTemp(tempPath, initialChunks, iterator);
 
     // Bug #5 — apply source-side mode after the byte write. See
-    // FILE_MODE_META_KEY for the metadata contract. Parses defensively:
-    // a malformed value falls through with no chmod so the umask default
-    // applies, matching the legacy back-compat path. The staged path is a
+    // FILE_MODE_META_KEY for the metadata contract. The staged path is a
     // regular file, then it is atomically renamed over the destination.
     //
     // Codex P2 (PR #24 round 3): strict octal-only regex BEFORE parseInt.
@@ -886,17 +905,33 @@ export async function downloadFile(
     // the upload side stamps (`(mode & 0o777).toString(8)` → at most
     // three digits, all 0–7) and rejects everything else.
     const modeOctal = metadata?.[FILE_MODE_META_KEY];
+    let modeToApply: number | undefined;
     if (typeof modeOctal === "string" && /^[0-7]{1,4}$/.test(modeOctal)) {
       const parsed = parseInt(modeOctal, 8);
       if (Number.isFinite(parsed) && parsed >= 0 && parsed <= 0o777) {
-        try {
-          fs.chmodSync(tempPath, parsed);
-        } catch {
-          // chmod failure (read-only FS, EPERM) is non-fatal — the file
-          // is materialized, just with the umask default. Surface via
-          // S3-side metadata being present but the file not matching;
-          // a future operator-side audit can reconcile.
-        }
+        modeToApply = parsed;
+      }
+    } else if (modeOctal === undefined) {
+      modeToApply = existingLocalMode;
+      modeWarnings.push({
+        reason: "missing-hq-mode",
+        fallback:
+          existingLocalMode === undefined
+            ? "receiver-default"
+            : "preserved-local-mode",
+      });
+    } else {
+      modeWarnings.push({ reason: "invalid-hq-mode", fallback: "receiver-default" });
+    }
+
+    if (modeToApply !== undefined) {
+      try {
+        fs.chmodSync(tempPath, modeToApply);
+      } catch {
+        // chmod failure (read-only FS, EPERM) is non-fatal — the file is
+        // materialized, but callers must receive a telemetry signal instead
+        // of silently believing the guardrail held.
+        modeWarnings.push({ reason: "chmod-failed" });
       }
     }
 
@@ -953,7 +988,21 @@ export async function downloadFile(
   // distinct creation time, so a future receiver upgrade picks it up
   // automatically without a server-side data migration.
 
-  return { metadata, contentHash: streamed.hash, contentSize: streamed.size };
+  if (modeWarnings.length > 0) {
+    for (const warning of modeWarnings) {
+      console.warn(
+        `[hq-sync] mode warning for ${key}: ${warning.reason}` +
+          (warning.fallback ? ` (${warning.fallback})` : ""),
+      );
+    }
+  }
+
+  return {
+    metadata,
+    contentHash: streamed.hash,
+    contentSize: streamed.size,
+    ...(modeWarnings.length > 0 ? { modeWarnings } : {}),
+  };
 }
 
 export interface RemoteFile {

package/src/scope-shrink.ts

@@ -40,6 +40,7 @@ import type {
   SyncJournal,
 } from "./types.js";
 import { hashFile, tombstoneEntry } from "./journal.js";
+import { localPathForVaultKey } from "./local-path-codec.js";
 import {
   isCoveredByAny,
   type ScopePrefixInput,
@@ -168,7 +169,7 @@ function classifyOrphan(
   entry: JournalEntry,
   hqRoot: string,
 ): OrphanClassification {
-  const absPath = path.join(hqRoot, relPath);
+  const absPath = localPathForVaultKey(hqRoot, relPath);
   let stat: fs.Stats;
   try {
     stat = fs.lstatSync(absPath);
@@ -436,9 +437,9 @@ export function applyScopeShrink(
   const dirtyKeptPaths: string[] = [];
 
   for (const orphan of plan.clean) {
-    const absPath = path.join(hqRoot, orphan.path);
+    const absPath = localPathForVaultKey(hqRoot, orphan.path);
     if (quarantining) {
-      const destAbs = path.join(input.quarantineRoot!, orphan.path);
+      const destAbs = localPathForVaultKey(input.quarantineRoot!, orphan.path);
       quarantineOrphan(absPath, destAbs);
       tombstoneEntry(journal, orphan.path, reason);
       cleanQuarantined++;