pushwork 1.1.8 → 1.2.2

package/src/utils/network-sync.ts

@@ -21,13 +21,11 @@ function debug(...args: any[]) {
  *
  * @param repo - The Automerge repository
  * @param rootDirectoryUrl - The root directory URL to start traversal from
- * @param syncServerStorageId - The sync server storage ID
  * @param options - Configuration options
  */
 export async function waitForBidirectionalSync(
   repo: Repo,
   rootDirectoryUrl: AutomergeUrl | undefined,
-  syncServerStorageId: StorageId | undefined,
   options: {
     timeoutMs?: number;
     pollIntervalMs?: number;
@@ -42,7 +40,7 @@ export async function waitForBidirectionalSync(
     handles,
   } = options;
 
-  if (!syncServerStorageId || !rootDirectoryUrl) {
+  if (!rootDirectoryUrl) {
     return;
   }
 
@@ -295,16 +293,20 @@ export async function waitForSync(
 ): Promise<SyncWaitResult> {
   const startTime = Date.now();
 
-  if (!syncServerStorageId) {
-    debug("waitForSync: no sync server storage ID, skipping");
-    return { failed: [] };
-  }
-
   if (handlesToWaitOn.length === 0) {
     debug("waitForSync: no documents to sync");
     return { failed: [] };
   }
 
+  // When no StorageId is available (Subduction mode), use head-stability
+  // polling. The SubductionSource handles sync internally — we just wait
+  // for each handle's heads to stop changing.
+  if (!syncServerStorageId) {
+    debug(`waitForSync: no storage ID, using head-stability polling for ${handlesToWaitOn.length} documents`);
+    out.taskLine(`Waiting for ${handlesToWaitOn.length} documents to sync`);
+    return waitForSyncViaHeadStability(handlesToWaitOn, timeoutMs, startTime);
+  }
+
   debug(`waitForSync: waiting for ${handlesToWaitOn.length} documents (timeout=${timeoutMs}ms, batchSize=${SYNC_BATCH_SIZE})`);
 
   // Separate already-synced from needs-sync
@@ -370,3 +372,85 @@ export async function waitForSync(
 
   return { failed };
 }
+
+/**
+ * Wait for sync by polling head stability (Subduction mode).
+ * Each handle's heads are polled until they remain unchanged for
+ * several consecutive checks, indicating the SubductionSource has
+ * finished syncing.
+ */
+async function waitForSyncViaHeadStability(
+  handles: DocHandle<unknown>[],
+  timeoutMs: number,
+  startTime: number,
+): Promise<SyncWaitResult> {
+  const failed: DocHandle<unknown>[] = [];
+  let synced = 0;
+
+  // Process in batches
+  for (let i = 0; i < handles.length; i += SYNC_BATCH_SIZE) {
+    const batch = handles.slice(i, i + SYNC_BATCH_SIZE);
+
+    const results = await Promise.allSettled(
+      batch.map(handle => waitForHandleHeadStability(handle, timeoutMs, startTime))
+    );
+
+    for (const result of results) {
+      if (result.status === "rejected") {
+        failed.push(result.reason as DocHandle<unknown>);
+      } else {
+        synced++;
+      }
+    }
+  }
+
+  const elapsed = Date.now() - startTime;
+  if (failed.length > 0) {
+    debug(`waitForSync(heads): ${failed.length} documents failed after ${elapsed}ms`);
+    out.taskLine(`Sync: ${synced} synced, ${failed.length} timed out after ${(elapsed / 1000).toFixed(1)}s`, true);
+  } else {
+    debug(`waitForSync(heads): all ${handles.length} documents synced in ${elapsed}ms`);
+    out.taskLine(`All ${handles.length} documents synced (${(elapsed / 1000).toFixed(1)}s)`);
+  }
+
+  return { failed };
+}
+
+/**
+ * Wait for a single handle's heads to stabilize.
+ * Polls heads at 100ms intervals; resolves after 3 consecutive stable
+ * checks, rejects on timeout.
+ */
+function waitForHandleHeadStability(
+  handle: DocHandle<unknown>,
+  timeoutMs: number,
+  startTime: number,
+): Promise<DocHandle<unknown>> {
+  return new Promise<DocHandle<unknown>>((resolve, reject) => {
+    let lastHeads = JSON.stringify(handle.heads());
+    let stableCount = 0;
+    const stableRequired = 3;
+
+    const pollInterval = setInterval(() => {
+      const currentHeads = JSON.stringify(handle.heads());
+      if (currentHeads === lastHeads) {
+        stableCount++;
+        if (stableCount >= stableRequired) {
+          clearInterval(pollInterval);
+          clearTimeout(timeout);
+          debug(`waitForSync(heads): ${handle.url}... converged in ${Date.now() - startTime}ms`);
+          resolve(handle);
+        }
+      } else {
+        stableCount = 0;
+        lastHeads = currentHeads;
+      }
+    }, 100);
+
+    const timeout = setTimeout(() => {
+      clearInterval(pollInterval);
+      debug(`waitForSync(heads): ${handle.url}... timed out after ${timeoutMs}ms`);
+      reject(handle);
+    }, timeoutMs);
+  });
+}

package/src/utils/output.ts

@@ -345,7 +345,7 @@ export class Output {
       this.taskOriginalMessage = null;
       this.taskCurrentMessage = null;
     }
-    console.log(
+    console.error(
       chalk.red(
         message instanceof Error
           ? message.message
@@ -367,7 +367,7 @@ export class Output {
       this.taskOriginalMessage = null;
       this.taskCurrentMessage = null;
     }
-    console.log(
+    console.error(
       `\n${chalk.bgRed.white(` ${label} `)}${message && ` ${message}`}`
     );
   }
@@ -400,19 +400,19 @@ export class Output {
 
     if (error instanceof Error) {
       // Error type and message
-      console.log(chalk.red(`${error.name}: ${error.message}`));
+      console.error(chalk.red(`${error.name}: ${error.message}`));
 
       // Stack trace
       if (error.stack) {
-        console.log("");
-        console.log(chalk.dim("Stack trace:"));
+        console.error("");
+        console.error(chalk.dim("Stack trace:"));
         const stackLines = error.stack.split("\n").slice(1); // Skip first line (error message)
         stackLines.forEach((line) =>
-          console.log(chalk.dim(`  ${line.trim()}`))
+          console.error(chalk.dim(`  ${line.trim()}`))
         );
       }
     } else {
-      console.log(chalk.red(String(error)));
+      console.error(chalk.red(String(error)));
     }
 
     process.exit(exitCode);

package/src/utils/repo-factory.ts

@@ -1,28 +1,142 @@
-import { Repo } from "@automerge/automerge-repo";
+import { type Repo, type RepoConfig, type NetworkAdapterInterface } from "@automerge/automerge-repo";
 import { NodeFSStorageAdapter } from "@automerge/automerge-repo-storage-nodefs";
-import { BrowserWebSocketClientAdapter } from "@automerge/automerge-repo-network-websocket";
+import * as fs from "fs/promises";
 import * as path from "path";
 import { DirectoryConfig } from "../types";
 
 /**
- * Create an Automerge repository with configuration-based setup
+ * Perform a real ESM dynamic import that tsc won't rewrite to require().
+ *
+ * TypeScript with `"module": "commonjs"` compiles `await import("x")` to
+ * `require("x")`, which resolves CJS entries instead of ESM entries. The
+ * Wasm module instance is different between the CJS and ESM module graphs,
+ * so initializing via CJS require() doesn't help the ESM /slim imports
+ * inside automerge-repo.
+ *
+ * This helper uses `new Function` to create a real `import()` expression
+ * that Node.js evaluates as ESM, sharing the same module graph as the
+ * Repo's internal imports.
+ */
+const dynamicImport = new Function("specifier", "return import(specifier)") as (
+  specifier: string,
+) => Promise<any>;
+
+/**
+ * Initialize the Subduction Wasm module and return the Repo constructor.
+ *
+ * The Repo constructor calls set_subduction_logger() and new MemorySigner()
+ * from @automerge/automerge-subduction/slim, which require the Wasm module
+ * to be initialized first. automerge-repo exports initSubduction() to
+ * handle this — it dynamically imports the non-/slim entry (which
+ * auto-initializes the Wasm as a side effect).
+ *
+ * Both the Repo and initSubduction must be loaded via ESM dynamic import()
+ * so they share the same module graph as the Repo's internal /slim imports.
+ */
+let cachedRepoClass: typeof Repo | undefined;
+
+async function getRepoClass(): Promise<typeof Repo> {
+  if (cachedRepoClass) return cachedRepoClass;
+
+  // Import Repo and initialize Subduction Wasm via automerge-repo's
+  // initSubduction() helper. This must happen before new Repo() because
+  // the constructor calls set_subduction_logger() and new MemorySigner()
+  // which require the Wasm module to be ready.
+  //
+  // Both imports use the ESM dynamic import wrapper so they share the
+  // same module graph as the Repo's internal /slim imports.
+  const repoMod = await dynamicImport("@automerge/automerge-repo");
+  await repoMod.initSubduction();
+  cachedRepoClass = repoMod.Repo as typeof Repo;
+  return cachedRepoClass;
+}
+
+/**
+ * Scan a directory tree for 0-byte files, which indicate incomplete writes
+ * from a previous run (process exited before storage flushed). Returns true
+ * if any are found.
+ */
+async function hasCorruptStorage(dir: string): Promise<boolean> {
+  try {
+    await fs.access(dir);
+  } catch {
+    return false;
+  }
+
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (await hasCorruptStorage(fullPath)) return true;
+    } else if (entry.isFile()) {
+      const stat = await fs.stat(fullPath);
+      if (stat.size === 0) return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Create an Automerge repository with configuration-based setup.
+ *
+ * When `sub` is true, uses the Subduction sync backend built into
+ * automerge-repo. The Repo manages its own SubductionSource internally —
+ * we just pass `subductionWebsocketEndpoints` and the Repo handles
+ * connection management, sync, and retries.
+ *
+ * When `sub` is false (default), uses the traditional WebSocket network
+ * adapter for sync via the automerge sync server.
  */
 export async function createRepo(
   workingDir: string,
-  config: DirectoryConfig
+  config: DirectoryConfig,
+  sub: boolean = false
 ): Promise<Repo> {
+  const RepoClass = await getRepoClass();
+
   const syncToolDir = path.join(workingDir, ".pushwork");
-  const storage = new NodeFSStorageAdapter(path.join(syncToolDir, "automerge"));
+  const automergeDir = path.join(syncToolDir, "automerge");
+
+  // Detect and recover from corrupt local storage (0-byte files left by
+  // incomplete writes from a previous run). Wipe the cache so the Repo
+  // hydrates cleanly from the sync server.
+  if (await hasCorruptStorage(automergeDir)) {
+    console.warn("[pushwork] Corrupt local storage detected, clearing cache...");
+    await fs.rm(automergeDir, { recursive: true, force: true });
+    await fs.mkdir(automergeDir, { recursive: true });
+  }
+
+  const storage = new NodeFSStorageAdapter(automergeDir);
+
+  if (sub) {
+    const endpoints: string[] = [];
+    if (config.sync_enabled && config.sync_server) {
+      endpoints.push(config.sync_server);
+    }
+
+    return new RepoClass({
+      storage,
+      subductionWebsocketEndpoints: endpoints,
+    });
+  }
 
-  const repoConfig: any = { storage };
+  // Default: WebSocket sync adapter
+  const repoConfig: RepoConfig = { storage };
 
-  // Add network adapter only if sync is enabled and server is configured
   if (config.sync_enabled && config.sync_server) {
-    const networkAdapter = new BrowserWebSocketClientAdapter(
+    // Load the WebSocket adapter via ESM dynamic import to stay in the
+    // same module graph as the Repo.
+    const wsMod = await dynamicImport("@automerge/automerge-repo-network-websocket");
+    // The websocket adapter package (subduction.8) hasn't updated its
+    // NetworkAdapter base-class types to match the repo's new
+    // NetworkAdapterInterface (which added state() and stricter
+    // EventEmitter generics). At runtime the adapter has all required
+    // methods; this is purely a declaration mismatch.
+    const networkAdapter = new wsMod.BrowserWebSocketClientAdapter(
       config.sync_server
-    );
+    ) as unknown as NetworkAdapterInterface;
     repoConfig.network = [networkAdapter];
   }
 
-  return new Repo(repoConfig);
+  return new RepoClass(repoConfig);
 }

package/test/integration/sub-flag.test.ts

@@ -0,0 +1,187 @@
+import * as fs from "fs/promises";
+import * as path from "path";
+import * as tmp from "tmp";
+import { execSync, execFile as execFileCb } from "child_process";
+import { promisify } from "util";
+import { SnapshotManager } from "../../src/core";
+
+const execFile = promisify(execFileCb);
+
+describe("--sub flag integration", () => {
+  let tmpDir: string;
+  let cleanup: () => void;
+  const cliPath = path.join(__dirname, "../../dist/cli.js");
+
+  beforeAll(() => {
+    execSync("pnpm build", { cwd: path.join(__dirname, "../.."), stdio: "pipe" });
+  });
+
+  beforeEach(() => {
+    const tmpObj = tmp.dirSync({ unsafeCleanup: true });
+    tmpDir = tmpObj.name;
+    cleanup = tmpObj.removeCallback;
+  });
+
+  afterEach(() => {
+    cleanup();
+  });
+
+  /**
+   * Run pushwork CLI command and return stdout.
+   * Throws on non-zero exit code.
+   */
+  async function pushwork(args: string[], timeoutMs = 30000): Promise<string> {
+    const { stdout } = await execFile("node", [cliPath, ...args], {
+      timeout: timeoutMs,
+      env: { ...process.env, NO_COLOR: "1" },
+    });
+    return stdout;
+  }
+
+  describe("init --sub", () => {
+    it("should initialize a directory with --sub flag", async () => {
+      await fs.writeFile(path.join(tmpDir, "hello.txt"), "Hello from sub!");
+
+      await pushwork(["init", "--sub", tmpDir]);
+
+      // Verify .pushwork was created
+      const pushworkDir = path.join(tmpDir, ".pushwork");
+      const stat = await fs.stat(pushworkDir);
+      expect(stat.isDirectory()).toBe(true);
+
+      // Verify snapshot exists and tracks the file
+      const snapshotManager = new SnapshotManager(tmpDir);
+      const snapshot = await snapshotManager.load();
+      expect(snapshot).not.toBeNull();
+      expect(snapshot!.rootDirectoryUrl).toBeDefined();
+      expect(snapshot!.rootDirectoryUrl).toMatch(/^automerge:/);
+      expect(snapshot!.files.has("hello.txt")).toBe(true);
+    }, 60000);
+
+    it("should track files in subdirectories", async () => {
+      await fs.mkdir(path.join(tmpDir, "src"), { recursive: true });
+      await fs.writeFile(path.join(tmpDir, "src", "index.ts"), "export default {}");
+      await fs.writeFile(path.join(tmpDir, "package.json"), '{"name": "test"}');
+
+      await pushwork(["init", "--sub", tmpDir]);
+
+      const snapshotManager = new SnapshotManager(tmpDir);
+      const snapshot = await snapshotManager.load();
+      expect(snapshot).not.toBeNull();
+      expect(snapshot!.files.has("src/index.ts")).toBe(true);
+      expect(snapshot!.files.has("package.json")).toBe(true);
+    }, 60000);
+
+    it("should respect default exclude patterns with --sub", async () => {
+      await fs.writeFile(path.join(tmpDir, "included.txt"), "keep me");
+      await fs.mkdir(path.join(tmpDir, "node_modules"));
+      await fs.writeFile(path.join(tmpDir, "node_modules", "dep.js"), "module");
+      await fs.mkdir(path.join(tmpDir, ".git"));
+      await fs.writeFile(path.join(tmpDir, ".git", "HEAD"), "ref: refs/heads/main");
+
+      await pushwork(["init", "--sub", tmpDir]);
+
+      const snapshotManager = new SnapshotManager(tmpDir);
+      const snapshot = await snapshotManager.load();
+      expect(snapshot).not.toBeNull();
+      expect(snapshot!.files.has("included.txt")).toBe(true);
+      expect(snapshot!.files.has("node_modules/dep.js")).toBe(false);
+      expect(snapshot!.files.has(".git/HEAD")).toBe(false);
+    }, 60000);
+  });
+
+  describe("sync --sub", () => {
+    it("should sync after init --sub", async () => {
+      await fs.writeFile(path.join(tmpDir, "file1.txt"), "initial content");
+
+      // Init with --sub
+      await pushwork(["init", "--sub", tmpDir]);
+
+      // Add a new file
+      await fs.writeFile(path.join(tmpDir, "file2.txt"), "new file");
+
+      // Sync with --sub
+      await pushwork(["sync", "--sub", tmpDir]);
+
+      // Verify the new file is now tracked
+      const snapshotManager = new SnapshotManager(tmpDir);
+      const snapshot = await snapshotManager.load();
+      expect(snapshot).not.toBeNull();
+      expect(snapshot!.files.has("file1.txt")).toBe(true);
+      expect(snapshot!.files.has("file2.txt")).toBe(true);
+    }, 60000);
+
+    it("should detect file modifications on sync --sub", async () => {
+      await fs.writeFile(path.join(tmpDir, "mutable.txt"), "version 1");
+
+      await pushwork(["init", "--sub", tmpDir]);
+
+      // Record initial heads
+      const snapshotManager = new SnapshotManager(tmpDir);
+      const snapshot1 = await snapshotManager.load();
+      const initialHead = snapshot1!.files.get("mutable.txt")!.head;
+
+      // Modify the file
+      await fs.writeFile(path.join(tmpDir, "mutable.txt"), "version 2");
+
+      // Sync
+      await pushwork(["sync", "--sub", tmpDir]);
+
+      // Heads should have changed
+      const snapshot2 = await snapshotManager.load();
+      const updatedHead = snapshot2!.files.get("mutable.txt")!.head;
+      expect(updatedHead).not.toEqual(initialHead);
+    }, 60000);
+
+    it("should handle file deletions on sync --sub", async () => {
+      await fs.writeFile(path.join(tmpDir, "ephemeral.txt"), "delete me");
+      await fs.writeFile(path.join(tmpDir, "keeper.txt"), "keep me");
+
+      await pushwork(["init", "--sub", tmpDir]);
+
+      // Delete a file
+      await fs.unlink(path.join(tmpDir, "ephemeral.txt"));
+
+      // Sync
+      await pushwork(["sync", "--sub", tmpDir]);
+
+      // Deleted file should be gone from snapshot
+      const snapshotManager = new SnapshotManager(tmpDir);
+      const snapshot = await snapshotManager.load();
+      expect(snapshot).not.toBeNull();
+      expect(snapshot!.files.has("ephemeral.txt")).toBe(false);
+      expect(snapshot!.files.has("keeper.txt")).toBe(true);
+    }, 60000);
+  });
+
+  describe("url after init --sub", () => {
+    it("should print a valid automerge URL", async () => {
+      await pushwork(["init", "--sub", tmpDir]);
+
+      const stdout = await pushwork(["url", tmpDir]);
+      expect(stdout.trim()).toMatch(/^automerge:/);
+    }, 60000);
+  });
+
+  describe("status after init --sub", () => {
+    it("should report status without errors", async () => {
+      await fs.writeFile(path.join(tmpDir, "test.txt"), "status check");
+      await pushwork(["init", "--sub", tmpDir]);
+
+      // status should not throw
+      const stdout = await pushwork(["status", tmpDir]);
+      expect(stdout).toBeDefined();
+    }, 60000);
+  });
+
+  describe("diff after init --sub", () => {
+    it("should show no changes immediately after init", async () => {
+      await fs.writeFile(path.join(tmpDir, "stable.txt"), "no changes");
+      await pushwork(["init", "--sub", tmpDir]);
+
+      const stdout = await pushwork(["diff", tmpDir]);
+      // After a fresh init+sync, there should be no pending changes
+      expect(stdout).not.toContain("modified");
+    }, 60000);
+  });
+});

package/test/unit/network-sync-sub.test.ts

@@ -0,0 +1,144 @@
+import { waitForSync } from "../../src/utils/network-sync";
+import { DocHandle, StorageId } from "@automerge/automerge-repo";
+
+/**
+ * Create a mock DocHandle with controllable heads.
+ *
+ * @param headSequence - An array of head values the handle returns on
+ *   successive calls to heads(). Once exhausted, the last value repeats.
+ *   This lets us simulate heads that change (sync in progress) and then
+ *   stabilize (sync complete).
+ */
+function mockHandle(headSequence: string[][]): DocHandle<unknown> {
+  let callCount = 0;
+
+  return {
+    url: `automerge:mock-${Math.random().toString(36).slice(2)}`,
+    heads: () => {
+      const idx = Math.min(callCount++, headSequence.length - 1);
+      return headSequence[idx];
+    },
+    // getSyncInfo is only called in the StorageId path, not the head-stability path
+    getSyncInfo: jest.fn(),
+    on: jest.fn(),
+    off: jest.fn(),
+  } as unknown as DocHandle<unknown>;
+}
+
+describe("waitForSync (Subduction / head-stability mode)", () => {
+  // When syncServerStorageId is undefined, waitForSync should use the
+  // head-stability polling path instead of the getSyncInfo-based path.
+
+  it("should return immediately for empty handle list", async () => {
+    const result = await waitForSync([], undefined);
+    expect(result.failed).toHaveLength(0);
+  });
+
+  it("should resolve when handle heads are already stable", async () => {
+    // Heads never change — stable from the start
+    const handle = mockHandle([["head-a", "head-b"]]);
+    const result = await waitForSync([handle], undefined, 5000);
+
+    expect(result.failed).toHaveLength(0);
+    // getSyncInfo should never be called in head-stability mode
+    expect(handle.getSyncInfo).not.toHaveBeenCalled();
+  });
+
+  it("should resolve after heads stabilize", async () => {
+    // Heads change for the first few polls, then stabilize
+    const handle = mockHandle([
+      ["head-1"],   // poll 1: initial
+      ["head-2"],   // poll 2: changed (reset stable count)
+      ["head-3"],   // poll 3: changed again
+      ["head-3"],   // poll 4: stable check 1
+      ["head-3"],   // poll 5: stable check 2
+      ["head-3"],   // poll 6: stable check 3 → converged
+    ]);
+
+    const result = await waitForSync([handle], undefined, 10000);
+    expect(result.failed).toHaveLength(0);
+  });
+
+  it("should report handle as failed on timeout", async () => {
+    // Heads keep changing — never stabilize
+    let counter = 0;
+    const neverStable = {
+      url: "automerge:never-stable",
+      heads: () => [`head-${counter++}`],
+      getSyncInfo: jest.fn(),
+      on: jest.fn(),
+      off: jest.fn(),
+    } as unknown as DocHandle<unknown>;
+
+    const result = await waitForSync([neverStable], undefined, 500);
+    expect(result.failed).toHaveLength(1);
+    expect(result.failed[0]).toBe(neverStable);
+  });
+
+  it("should handle a mix of stable and unstable handles", async () => {
+    const stable = mockHandle([["stable-head"]]);
+
+    let counter = 0;
+    const unstable = {
+      url: "automerge:unstable",
+      heads: () => [`changing-${counter++}`],
+      getSyncInfo: jest.fn(),
+      on: jest.fn(),
+      off: jest.fn(),
+    } as unknown as DocHandle<unknown>;
+
+    const result = await waitForSync([stable, unstable], undefined, 500);
+
+    // The stable handle should succeed, the unstable one should fail
+    expect(result.failed).toHaveLength(1);
+    expect(result.failed[0]).toBe(unstable);
+  });
+
+  it("should not use getSyncInfo when no StorageId is provided", async () => {
+    const handle = mockHandle([["head-a"]]);
+    await waitForSync([handle], undefined, 5000);
+
+    // The head-stability path does not call getSyncInfo at all
+    expect(handle.getSyncInfo).not.toHaveBeenCalled();
+  });
+});
+
+describe("waitForSync (WebSocket / StorageId mode)", () => {
+  // When a StorageId IS provided, waitForSync should use getSyncInfo-based
+  // verification instead of head-stability polling.
+
+  it("should use getSyncInfo when StorageId is provided", async () => {
+    const storageId = "test-storage-id" as StorageId;
+    const heads = ["head-a"];
+
+    const handle = {
+      url: "automerge:ws-handle",
+      heads: () => heads,
+      getSyncInfo: jest.fn().mockReturnValue({ lastHeads: heads }),
+      on: jest.fn(),
+      off: jest.fn(),
+    } as unknown as DocHandle<unknown>;
+
+    const result = await waitForSync([handle], storageId, 5000);
+
+    expect(result.failed).toHaveLength(0);
+    expect(handle.getSyncInfo).toHaveBeenCalledWith(storageId);
+  });
+
+  it("should detect already-synced handles via getSyncInfo", async () => {
+    const storageId = "test-storage-id" as StorageId;
+    const heads = ["same-head"];
+
+    const handle = {
+      url: "automerge:already-synced",
+      heads: () => heads,
+      // getSyncInfo returns matching heads → already synced
+      getSyncInfo: jest.fn().mockReturnValue({ lastHeads: heads }),
+      on: jest.fn(),
+      off: jest.fn(),
+    } as unknown as DocHandle<unknown>;
+
+    const result = await waitForSync([handle], storageId, 5000);
+    expect(result.failed).toHaveLength(0);
+  });
+});