@indigoai-us/hq-cloud 5.35.0 → 5.36.0

package/src/cli/share.ts

@@ -213,6 +213,42 @@ function computePushPlan(
       continue;
     }
 
+    // Fast-path (5.36.0): before SHA256-ing the file, lstat it and compare
+    // (size, mtimeMs) against the journal entry. When both match, treat the
+    // file as unchanged without reading its bytes. This is the same
+    // industry-standard "is it changed?" cheap-check rsync and gitignore
+    // use. Trade-off: a same-length edit that doesn't bump mtime will be
+    // missed — vanishingly rare in practice. The big win is on no-op syncs
+    // (most syncs): a 5000-file tree of mostly-unchanged content used to
+    // SHA256 every file on every walk. Now it lstats once and short-
+    // circuits in O(file count) instead of O(file bytes).
+    //
+    // Only applies when `skipUnchanged` is on AND the journal carries an
+    // `mtimeMs` for this path AND the path is a regular file (symlinks
+    // already hash via the cheap hashSymlinkTarget path above). Entries
+    // without `mtimeMs` (pre-5.36 journal) fall through to the hash path;
+    // the next upload stamps the field so subsequent syncs use the fast-
+    // path. Back-compat is automatic.
+    if (skipUnchanged) {
+      const existing = journal.files[relativePath];
+      if (existing && existing.mtimeMs !== undefined && existing.hash) {
+        try {
+          const lstat = fs.lstatSync(absolutePath);
+          if (
+            lstat.isFile() &&
+            lstat.size === existing.size &&
+            lstat.mtimeMs === existing.mtimeMs
+          ) {
+            items.push({ action: "skip-unchanged", absolutePath, relativePath });
+            continue;
+          }
+        } catch {
+          // Fall through to hashFile, which will surface the I/O error in
+          // its own readFileSync.
+        }
+      }
+    }
+
     const localHash = hashFile(absolutePath);
 
     if (skipUnchanged) {
@@ -682,6 +718,41 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
 
   // Stage 2: execute. Skip items pre-classified as no-ops, then for each
   // upload candidate run the HEAD + 3-way conflict check + actual PUT.
+  //
+  // 5.36.0: upload candidates go through a bounded-concurrent pool
+  // (`TRANSFER_CONCURRENCY`, default 16, tunable via
+  // `HQ_SYNC_TRANSFER_CONCURRENCY`) for 4-8x speedup on transfer-heavy
+  // syncs. Skip-size-limit and skip-unchanged are handled inline first
+  // (pure local-state mutation). Upload candidates are collected into
+  // `uploadItems[]` and processed in parallel via the pool below.
+  //
+  // Abort handling: when any item's conflict resolution is "abort", we
+  // set `aborted = true` so the pool stops queueing new items, drain
+  // in-flight cleanly, and short-circuit to the abort return. In-flight
+  // PUTs that already issued will complete (S3 doesn't have client-side
+  // cancellation in this code path); their results are still recorded on
+  // the journal so the next sync's planner doesn't re-fire them.
+  // Interactive-mode guard (Codex P1, 5.36.x): when onConflict is unset
+  // the per-item conflict path falls into resolveConflict()'s readline
+  // prompt on process.stdin. Multiple pool workers prompting at once
+  // would race for the same terminal input and interleave answers
+  // nondeterministically. Force concurrency=1 for interactive sessions —
+  // the operator is at the keyboard anyway, the throughput penalty only
+  // applies when conflicts actually exist, and Option A (whole-pool
+  // serialization) has the smallest blast radius vs. a per-prompt mutex.
+  // Non-interactive (onConflict set) keeps the env-tunable default.
+  const isInteractiveConflictMode = onConflict === undefined;
+  const TRANSFER_CONCURRENCY = (() => {
+    if (isInteractiveConflictMode) return 1;
+    const raw = process.env.HQ_SYNC_TRANSFER_CONCURRENCY;
+    if (raw === undefined || raw === "") return 16;
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : 16;
+  })();
+
+  // Phase A: serial classification pass — handle skips inline, collect
+  // upload candidates for the parallel pool.
+  const uploadItems: Array<typeof plan.items[number] & { action: "upload" }> = [];
   for (const item of plan.items) {
     if (item.action === "skip-size-limit") {
       emit({
@@ -696,7 +767,20 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
       filesSkipped++;
       continue;
     }
+    uploadItems.push(item);
+  }
 
+  // Phase B: parallel upload pool. Each task runs the full per-item flow
+  // (HEAD + conflict + PUT + journal stamp + emit). Aborts flip the
+  // shared `aborted` flag and the pool stops draining the queue; tasks
+  // already in flight complete normally.
+  let aborted = false;
+  let abortFlightConflictPaths: string[] = [];
+
+  const processUploadItem = async (
+    item: typeof uploadItems[number],
+  ): Promise<void> => {
+    if (aborted) return;
     const { absolutePath, relativePath, localHash } = item;
 
     // Auto-refresh context if credentials expiring. Only available on the
@@ -788,29 +872,13 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
         });
 
         if (resolution === "abort") {
-          return {
-            filesUploaded,
-            bytesUploaded,
-            filesSkipped,
-            filesDeleted,
-            // Abort path: delete stage never runs, so tombstone + refused-
-            // stale counts are necessarily zero. Explicit fields keep the
-            // ShareResult shape stable for consumers that destructure.
-            filesTombstoned,
-            filesRefusedStale,
-            // Always present so consumers can destructure without a
-            // defaulting fallback. Empty on the abort path because the
-            // delete-plan execution loop is short-circuited.
-            filesRefusedStalePaths,
-            // Exclusions are computed during the upload walk which has
-            // already completed by the time we hit a per-file conflict-
-            // abort, so the count is meaningful here. No event emit on
-            // abort (matches the existing convention: abort short-circuits
-            // before the end-of-run telemetry emits).
-            filesExcludedByPolicy: excludedSet.size,
-            conflictPaths,
-            aborted: true,
-          };
+          // Flip the shared aborted flag — the pool drainer below sees this
+          // and stops queueing new items. In-flight tasks complete normally
+          // (S3 PUTs have no client-side cancel here). The outer abort
+          // return is built after the pool drains.
+          aborted = true;
+          abortFlightConflictPaths = [...conflictPaths];
+          return;
         }
         if (resolution === "keep" || resolution === "skip") {
           // Bug #7 mirror branch: when the resolution is keep/skip on a
@@ -853,19 +921,33 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
             }
           }
           filesSkipped++;
-          continue;
+          return;
         }
         // "overwrite" falls through to upload
       }
     }
 
+    // Re-check abort flag right before the PUT — if a peer task aborted
+    // while we were waiting on HEAD, skip the PUT entirely. This is
+    // belt-and-suspenders alongside the queue-drain check; without it,
+    // up to TRANSFER_CONCURRENCY in-flight uploads could still issue PUTs
+    // after the user signaled abort.
+    if (aborted) return;
+
     // Upload — symlinks go through uploadSymlink (zero-byte body + target
     // metadata), regular files through uploadFile (file contents). The
     // discriminator is item.kind set by computePushPlan; both branches
     // converge on the same journal/event update path below.
     try {
       const isSymlinkUpload = item.kind === "symlink";
-      const size = isSymlinkUpload ? 0 : fs.statSync(absolutePath).size;
+      // Capture lstat post-upload so size + mtimeMs stamped into the
+      // journal reflect the bytes we actually shipped. lstat (not stat)
+      // so a symlink stamps the link's own mtime, not the target's —
+      // matches the fast-path's lstat comparison so the next sync can
+      // skip without dereferencing.
+      const lstat = fs.lstatSync(absolutePath);
+      const size = isSymlinkUpload ? 0 : lstat.size;
+      const mtimeMs = lstat.mtimeMs;
 
       const { etag } = isSymlinkUpload
         ? options.author
@@ -877,8 +959,9 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
 
       // Update journal with optional message; capture the post-upload ETag
       // so the next sync can distinguish "remote moved since we last wrote"
-      // from "user edited locally" without conflating the two.
-      updateEntry(journal, relativePath, localHash, size, "up", etag);
+      // from "user edited locally" without conflating the two. mtimeMs
+      // feeds the 5.36.0 lstat fast-path on the next push.
+      updateEntry(journal, relativePath, localHash, size, "up", etag, mtimeMs);
       if (message) {
         journal.files[relativePath] = {
           ...journal.files[relativePath],
@@ -901,6 +984,80 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
         message: err instanceof Error ? err.message : String(err),
       });
     }
+  };
+
+  // Drain the upload queue with bounded concurrency. Per-file progress
+  // events fire from inside processUploadItem at file-settle time, so
+  // cross-file event ordering is settle-order, not plan-walk-order — the
+  // menubar's stream parser already tolerates per-company interleave so
+  // this is shape-compatible. allSettled-style waiting (via Promise.race
+  // on the in-flight set) keeps the pool topped up without idling on slow
+  // members.
+  //
+  // Codex P1 (5.36.x): each worker promise is wrapped in a .catch that
+  // records the error to `workerErrors` and resolves normally — so
+  // `Promise.race(inFlight)` can never reject and unwind the drain loop
+  // mid-flight. Without the wrap, an unhandled rejection inside
+  // processUploadItem (e.g. headRemoteFile or refreshEntityContext, both
+  // of which sit outside the per-item PUT try/catch) bubbled out of the
+  // race, abandoned still-in-flight uploads that kept mutating remote
+  // state, and skipped writeJournal — leaving remote and journal
+  // permanently out of sync for the next run. After the pool fully
+  // drains we throw an aggregated error so the caller still surfaces the
+  // failure (and the journal reflects the writes that actually landed).
+  const workerErrors: Error[] = [];
+  {
+    const queue = [...uploadItems];
+    const inFlight: Set<Promise<unknown>> = new Set();
+    while (queue.length > 0 || inFlight.size > 0) {
+      while (!aborted && inFlight.size < TRANSFER_CONCURRENCY && queue.length > 0) {
+        const item = queue.shift()!;
+        const p: Promise<void> = processUploadItem(item)
+          .catch((err: unknown) => {
+            workerErrors.push(err instanceof Error ? err : new Error(String(err)));
+          })
+          .finally(() => {
+            inFlight.delete(p);
+          });
+        inFlight.add(p);
+      }
+      if (inFlight.size > 0) {
+        await Promise.race(Array.from(inFlight));
+      } else {
+        // Aborted with nothing in flight → exit the drain loop.
+        break;
+      }
+    }
+  }
+
+  if (aborted) {
+    return {
+      filesUploaded,
+      bytesUploaded,
+      filesSkipped,
+      filesDeleted,
+      // Abort path: delete stage never runs, so tombstone + refused-
+      // stale counts are necessarily zero. Explicit fields keep the
+      // ShareResult shape stable for consumers that destructure.
+      filesTombstoned,
+      filesRefusedStale,
+      // Always present so consumers can destructure without a
+      // defaulting fallback. Empty on the abort path because the
+      // delete-plan execution loop is short-circuited.
+      filesRefusedStalePaths,
+      // Exclusions are computed during the upload walk which has
+      // already completed by the time we hit a per-file conflict-
+      // abort, so the count is meaningful here. No event emit on
+      // abort (matches the existing convention: abort short-circuits
+      // before the end-of-run telemetry emits).
+      filesExcludedByPolicy: excludedSet.size,
+      // Use the snapshot of conflictPaths taken at the moment the abort
+      // fired — additional in-flight items may have appended to the
+      // shared array after the abort signal, and those should not show
+      // up in the abort result.
+      conflictPaths: abortFlightConflictPaths,
+      aborted: true,
+    };
   }
 
   // Stage 3: propagate deletes. Three buckets, three actions:
@@ -1009,6 +1166,23 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
     });
   }
 
+  // Codex P1 (5.36.x): if any worker rejected (unhandled error in
+  // headRemoteFile / refreshEntityContext / resolveConflict — paths
+  // outside the per-item PUT try/catch), we deliberately let the pool
+  // drain AND let post-pool stages (deletes, tombstones, journal write,
+  // personal-vault summary) run to completion so journal + remote stay
+  // converged on what actually landed. NOW surface the failure to the
+  // caller — preserving the first error's stack so debugging works.
+  // Aggregate count is reported in the message for visibility when
+  // multiple workers failed.
+  if (workerErrors.length > 0) {
+    const first = workerErrors[0]!;
+    if (workerErrors.length > 1) {
+      first.message = `${first.message} (and ${workerErrors.length - 1} more upload-worker errors)`;
+    }
+    throw first;
+  }
+
   return {
     filesUploaded,
     bytesUploaded,

package/src/cli/sync.ts

@@ -335,7 +335,39 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
   // Stage 2: execute the plan. Per-item branching mirrors the pre-refactor
   // inline loop; the only structural change is that classification has
   // already happened (so `localHash` is reused instead of re-hashing).
+  //
+  // 5.36.0: download items go through a bounded-concurrent pool
+  // (`TRANSFER_CONCURRENCY`, default 16, tunable via
+  // `HQ_SYNC_TRANSFER_CONCURRENCY`) for 4-8x speedup on transfer-heavy
+  // syncs. Conflict items stay serial — they may prompt the operator
+  // and the abort path must short-circuit before any further work. We
+  // partition the plan items into "conflict (serial)" and "download
+  // (parallel)" buckets and run the serial pass first; the parallel pass
+  // only runs if no conflict aborted.
+  //
+  // Per-file `progress` events fire at the moment each individual download
+  // settles (inside the pool wrapper), NOT in plan-walk order. The cross-
+  // file interleave is acceptable: the menubar stream parser already
+  // handles per-company interleave, and the same shape applies within a
+  // single company's pool. Per-file event-count correctness is preserved
+  // (one progress per download, one error per failure).
+  const TRANSFER_CONCURRENCY = (() => {
+    const raw = process.env.HQ_SYNC_TRANSFER_CONCURRENCY;
+    if (raw === undefined || raw === "") return 16;
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : 16;
+  })();
+
+  // First pass: serial walk for non-download outcomes (skips + conflicts).
+  // Conflicts may set `aborted = true` and short-circuit the whole pull;
+  // we detect that and skip the parallel pass. Download items are
+  // collected into `downloadItems[]` for the pool pass below.
+  const downloadItems: Array<typeof plan.items[number] & { action: "download" }> = [];
+  let aborted = false;
+  let abortResult: SyncResult | null = null;
+
   for (const item of plan.items) {
+    if (aborted) break;
     if (
       item.action === "skip-ignored" ||
       item.action === "skip-personal-mode" ||
@@ -353,6 +385,11 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
       continue;
     }
 
+    if (item.action === "download") {
+      downloadItems.push(item);
+      continue;
+    }
+
     const { remoteFile, localPath } = item;
 
     // Auto-refresh context if credentials expiring (kept in execute phase
@@ -428,7 +465,8 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
       if (resolution === "abort") {
         emit({ type: "new-files", files: [] });
         writeJournal(journalSlug, journal);
-        return {
+        aborted = true;
+        abortResult = {
           filesDownloaded,
           bytesDownloaded,
           filesSkipped,
@@ -443,6 +481,7 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
           // destructure it.
           filesTombstoned: 0,
         };
+        break;
       }
       if (resolution === "keep" || resolution === "skip") {
         filesSkipped++;
@@ -467,63 +506,157 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
           item.localSize,
           "down",
           remoteFile.etag,
+          item.localMtime.getTime(),
         );
         continue;
       }
-      // "overwrite" falls through to download
+      // "overwrite" falls through to download — re-route through the pool
+      // so it benefits from parallelism too. Synthesize a download item
+      // pointing at the same remoteFile/localPath; isNew=false because
+      // there was a conflict-eligible local file present.
+      downloadItems.push({
+        action: "download",
+        remoteFile,
+        localPath,
+        isNew: false,
+      });
+      continue;
     }
+  }
 
-    // Download (action === "download" or conflict resolved to "overwrite")
-    try {
-      const { metadata } = await downloadFile(ctx, remoteFile.key, localPath);
-      const author = metadata?.["created-by"] ?? null;
+  // Early-return on conflict abort BEFORE running the parallel download
+  // pool — the abort intent is "stop the pull now", not "stop new work but
+  // finish what's in flight". Since the pool hasn't started yet, this is
+  // a clean drain (zero items in flight) by construction.
+  if (aborted && abortResult) {
+    return abortResult;
+  }
 
-      // Symlink records materialize as real symlinks on disk. lstat
-      // (does not follow) lets us detect that case so the journal stamp
-      // mirrors what the push side would emit on the next tick:
-      //   hash = sha256(readlink target string)
-      //   size = 0
-      // Without this check, hashFile would follow the link and stamp the
-      // target file's contents — a value the next push would never
-      // produce — which makes skipUnchanged perpetually re-upload every
-      // symlink, defeating the point of the gate.
-      const localLstat = fs.lstatSync(localPath);
-      const isLocalSymlink = localLstat.isSymbolicLink();
-      const hash = isLocalSymlink
-        ? hashSymlinkTarget(fs.readlinkSync(localPath))
-        : hashFile(localPath);
-      const size = isLocalSymlink ? 0 : fs.statSync(localPath).size;
-      // Capture the listing's ETag so subsequent syncs can detect remote
-      // drift independently of mtime drift.
-      updateEntry(journal, remoteFile.key, hash, size, "down", remoteFile.etag);
+  // ── Parallel download pool (5.36.0) ───────────────────────────────────
+  // Bounded concurrency: TRANSFER_CONCURRENCY simultaneous downloads. Same
+  // race-based shape as the HEAD-verify pool above but applied to the body
+  // of each download. Per-item progress events fire at file-settle time
+  // (inside the wrapper), so cross-file interleave is expected and the
+  // menubar's stream parser already handles it.
+  if (downloadItems.length > 0) {
+    const queue = [...downloadItems];
+    const inFlight: Set<Promise<unknown>> = new Set();
 
-      // Attach message from the prior journal entry if present (set by a
-      // previous `share` operation that included a --message).
-      const priorEntry = getEntry(journal, remoteFile.key);
-      const remoteJournalMessage = (priorEntry as { message?: string } | undefined)?.message;
-      emit({
-        type: "progress",
-        path: remoteFile.key,
-        bytes: size,
-        ...(remoteJournalMessage ? { message: remoteJournalMessage } : {}),
-        ...(author ? { author } : {}),
-      });
+    const downloadOne = async (
+      downloadItem: typeof downloadItems[number],
+    ): Promise<void> => {
+      const { remoteFile, localPath } = downloadItem;
 
-      filesDownloaded++;
-      bytesDownloaded += size;
-    } catch (err) {
-      // STS session policy may deny access to some paths — this is expected
-      // for guest members with allowedPrefixes
-      if (isAccessDenied(err)) {
-        filesSkipped++;
-      } else {
+      // Auto-refresh context if credentials expiring. Each task checks
+      // independently — refresh is idempotent on the same context object.
+      if (isExpiringSoon(ctx.expiresAt)) {
+        ctx = await refreshEntityContext(companyRef, vaultConfig);
+      }
+
+      try {
+        const { metadata } = await downloadFile(ctx, remoteFile.key, localPath);
+        const author = metadata?.["created-by"] ?? null;
+
+        // Symlink records materialize as real symlinks on disk. lstat
+        // (does not follow) lets us detect that case so the journal stamp
+        // mirrors what the push side would emit on the next tick:
+        //   hash = sha256(readlink target string)
+        //   size = 0
+        // Without this check, hashFile would follow the link and stamp the
+        // target file's contents — a value the next push would never
+        // produce — which makes skipUnchanged perpetually re-upload every
+        // symlink, defeating the point of the gate.
+        const localLstat = fs.lstatSync(localPath);
+        const isLocalSymlink = localLstat.isSymbolicLink();
+        const hash = isLocalSymlink
+          ? hashSymlinkTarget(fs.readlinkSync(localPath))
+          : hashFile(localPath);
+        const size = isLocalSymlink ? 0 : fs.statSync(localPath).size;
+        // Capture the listing's ETag so subsequent syncs can detect remote
+        // drift independently of mtime drift. Stamp mtimeMs from localLstat
+        // (5.36.0) so the next push planner's lstat fast-path can skip the
+        // SHA256 for this file without reading its bytes.
+        updateEntry(
+          journal,
+          remoteFile.key,
+          hash,
+          size,
+          "down",
+          remoteFile.etag,
+          localLstat.mtimeMs,
+        );
+
+        // Attach message from the prior journal entry if present (set by a
+        // previous `share` operation that included a --message).
+        const priorEntry = getEntry(journal, remoteFile.key);
+        const remoteJournalMessage = (priorEntry as { message?: string } | undefined)?.message;
         emit({
-          type: "error",
+          type: "progress",
           path: remoteFile.key,
-          message: err instanceof Error ? err.message : String(err),
+          bytes: size,
+          ...(remoteJournalMessage ? { message: remoteJournalMessage } : {}),
+          ...(author ? { author } : {}),
         });
+
+        filesDownloaded++;
+        bytesDownloaded += size;
+      } catch (err) {
+        // STS session policy may deny access to some paths — this is expected
+        // for guest members with allowedPrefixes
+        if (isAccessDenied(err)) {
+          filesSkipped++;
+        } else {
+          emit({
+            type: "error",
+            path: remoteFile.key,
+            message: err instanceof Error ? err.message : String(err),
+          });
+        }
+      }
+    };
+
+    // Codex P1 (5.36.x): worker promises wrapped in .catch so an
+    // unhandled rejection inside downloadOne (e.g. refreshEntityContext
+    // before the per-item try/catch, or lstatSync after the download
+    // succeeded but before journal stamping) cannot escape
+    // `Promise.race(inFlight)` and unwind the drain mid-flight. Without
+    // this wrap, sibling downloads kept running after share()/sync()
+    // had already failed, their files materialized on disk without
+    // matching journal entries, and the next sync re-downloaded
+    // everything. Errors are collected and surfaced after the pool
+    // fully drains — see workerErrors throw below.
+    const workerErrors: Error[] = [];
+    while (queue.length > 0 || inFlight.size > 0) {
+      while (inFlight.size < TRANSFER_CONCURRENCY && queue.length > 0) {
+        const downloadItem = queue.shift()!;
+        const p: Promise<void> = downloadOne(downloadItem)
+          .catch((err: unknown) => {
+            workerErrors.push(err instanceof Error ? err : new Error(String(err)));
+          })
+          .finally(() => {
+            inFlight.delete(p);
+          });
+        inFlight.add(p);
+      }
+      if (inFlight.size > 0) {
+        // Wait for at least one in-flight task to settle before topping up
+        // the pool. allSettled-style semantics via Promise.race — the
+        // .catch wrap above guarantees no worker promise can reject.
+        await Promise.race(Array.from(inFlight));
       }
     }
+
+    // Pool drained. If any worker rejected, write the journal first
+    // (so the lstat fast-path stamps for successfully-downloaded files
+    // persist) then throw the first error, preserving its stack.
+    if (workerErrors.length > 0) {
+      writeJournal(journalSlug, journal);
+      const first = workerErrors[0]!;
+      if (workerErrors.length > 1) {
+        first.message = `${first.message} (and ${workerErrors.length - 1} more download-worker errors)`;
+      }
+      throw first;
+    }
   }
 
   // ── New-files attribution (US-002) ─────────────────────────────────────
@@ -928,9 +1061,28 @@ function computePullPlan(
         items.push({ action: "skip-local-only", remoteFile, localPath });
         continue;
       }
-      const localHash = isLocalSymlink
-        ? hashSymlinkTarget(fs.readlinkSync(localPath))
-        : hashFile(localPath);
+      // Fast-path (5.36.0): when the journal entry has an mtimeMs and the
+      // local lstat matches both size and mtimeMs, the file hasn't been
+      // touched locally since the last sync, so we can reuse the journal's
+      // recorded hash without re-reading the file's bytes. Same shape as
+      // the share-side fast-path; only kicks in for regular files (symlink
+      // hashing through hashSymlinkTarget is already cheap — it hashes a
+      // short target string, not file bytes).
+      let localHash: string;
+      if (
+        !isLocalSymlink &&
+        journalEntry &&
+        journalEntry.mtimeMs !== undefined &&
+        journalEntry.hash &&
+        localLstat!.size === journalEntry.size &&
+        localLstat!.mtimeMs === journalEntry.mtimeMs
+      ) {
+        localHash = journalEntry.hash;
+      } else {
+        localHash = isLocalSymlink
+          ? hashSymlinkTarget(fs.readlinkSync(localPath))
+          : hashFile(localPath);
+      }
       const localChanged = !!journalEntry && journalEntry.hash !== localHash;
       const remoteChanged =
         !!journalEntry && hasRemoteChanged(remoteFile, journalEntry);

package/src/journal.ts

@@ -210,6 +210,7 @@ export function updateEntry(
   size: number,
   direction: "up" | "down",
   remoteEtag?: string,
+  mtimeMs?: number,
 ): void {
   const entry: JournalEntry = {
     hash,
@@ -220,6 +221,9 @@ export function updateEntry(
   if (remoteEtag !== undefined && remoteEtag !== "") {
     entry.remoteEtag = normalizeEtag(remoteEtag);
   }
+  if (mtimeMs !== undefined) {
+    entry.mtimeMs = mtimeMs;
+  }
   journal.files[relativePath] = entry;
   journal.lastSync = new Date().toISOString();
 }

package/src/types.ts

@@ -34,6 +34,22 @@ export interface JournalEntry {
    * against `syncedAt`.
    */
   remoteEtag?: string;
+  /**
+   * Local mtime (epoch ms) of the file at the moment we last synced it. Used
+   * by the push planner as the fast-path "is this file unchanged?" check:
+   * when `lstat.size === entry.size && lstat.mtimeMs === entry.mtimeMs`,
+   * the SHA256 is skipped and the file is classified `unchanged` without
+   * reading its bytes. Same trade-off rsync/gitignore use — a same-length
+   * edit that doesn't bump mtime will be missed, but that's vanishingly
+   * rare in practice and the speedup on no-op syncs (~5–10×) is the goal.
+   *
+   * Optional for backwards compatibility: entries written before this field
+   * existed (or symlink entries, where lstat.mtimeMs is the link's own
+   * mtime and the prefixed-hash check is already cheap) fall through to
+   * `hashFile()` on the first post-upgrade sync; the next `updateEntry`
+   * stamps the field so subsequent syncs use the fast-path.
+   */
+  mtimeMs?: number;
   /**
    * Tombstone marker (Journal v2, US-005). When set, this entry represents
    * a file that was pruned by a scope shrink — either implicitly (next pull