tether-sync 0.2.0 → 0.6.0

package/bin/{daemon-KQ4ZTBYG.js → daemon-Z2NE3MNG.js}

@@ -1,18 +1,29 @@
 import {
   GIT_MODES,
   VERSION,
+  blobAt,
+  changeFromGit,
+  changesBetween,
+  fileBlob,
   files,
   findRepo,
+  gitBinary,
   gitBusy,
-  installHooks,
+  head,
+  indexBlob,
   ipcEndpoint,
+  isAncestor,
+  isKept,
   isNewer,
+  isTracked,
   isWindows,
   latestVersion,
   listen,
   removeHooks,
+  restage,
+  setKeep,
   tetherHome
-} from "./chunk-NDKBAHAG.js";
+} from "./chunk-KG4OTE34.js";
 
 // packages/client/src/daemon.js
 import fs8 from "node:fs";
@@ -34,6 +45,7 @@ var DEFAULTS = {
   // all | errors | off
 };
 var NUMERIC = /* @__PURE__ */ new Set(["tickSeconds", "graceMs"]);
+var MIN_TICK_SECONDS = Number(process.env.TETHER_MIN_TICK_SECONDS) || 10;
 var Config = class {
   constructor(file) {
     this.file = file;
@@ -52,6 +64,7 @@ var Config = class {
     if (NUMERIC.has(key)) {
       value = Number(value);
       if (!Number.isFinite(value) || value <= 0) throw new Error(`${key} must be a positive number`);
+      if (key === "tickSeconds" && value < MIN_TICK_SECONDS) throw new Error(`tickSeconds must be at least ${MIN_TICK_SECONDS}`);
     }
     if (key === "notifications" && !["all", "errors", "off"].includes(value)) throw new Error("notifications must be all, errors or off");
     if (key === "scanRoots" && typeof value === "string") value = value.split(/[;,]/).map((s) => s.trim()).filter(Boolean);
@@ -113,11 +126,16 @@ var COLUMNS = {
   gitRoot: "TEXT",
   gitDir: "TEXT",
   gitHooks: "TEXT",
+  // unused since 0.2.1 (hooks were replaced by watching the git directory)
+  gitWaiting: "INTEGER DEFAULT 0",
+  // follow: a newer Tether version came from a git commit not pulled here yet
+  gitOverlay: "INTEGER DEFAULT 0",
+  // follow: holds a Tether-only version that git does not have (hidden from git)
   lastError: "TEXT",
   createdAt: "REAL",
   updatedAt: "REAL"
 };
-var BOOL = /* @__PURE__ */ new Set(["realtime", "hasBom", "exec", "canDelete", "detached", "needsRestore"]);
+var BOOL = /* @__PURE__ */ new Set(["gitOverlay", "gitWaiting", "realtime", "hasBom", "exec", "canDelete", "detached", "needsRestore"]);
 var LocalDb = class {
   constructor(file) {
     this.db = new DatabaseSync(file);
@@ -342,7 +360,73 @@ function randomString(len) {
 }
 var newInstanceId = () => "i_" + randomString(10);
 
+// packages/shared/src/chunks.js
+var CHUNK_MIN = 2 * 1024;
+var CHUNK_AVG = 8 * 1024;
+var CHUNK_MAX = 64 * 1024;
+var MASK_HARD = 4294836224;
+var MASK_EASY = 4292870144;
+var GEAR = (() => {
+  let a = 2122219134;
+  const t = new Uint32Array(256);
+  for (let i = 0; i < 256; i++) {
+    a = a + 1831565813 | 0;
+    let x = Math.imul(a ^ a >>> 15, 1 | a);
+    x = x + Math.imul(x ^ x >>> 7, 61 | x) ^ x;
+    t[i] = (x ^ x >>> 14) >>> 0;
+  }
+  return t;
+})();
+function chunkBoundaries(buf) {
+  const out = [];
+  const n = buf.length;
+  let start = 0;
+  while (start < n) {
+    if (n - start <= CHUNK_MIN) {
+      out.push({ o: start, s: n - start });
+      break;
+    }
+    const end = Math.min(n, start + CHUNK_MAX);
+    const normal = Math.min(end, start + CHUNK_AVG);
+    let h = 0;
+    let cut = end;
+    let i = start + CHUNK_MIN;
+    for (; i < normal; i++) {
+      h = (h << 1) + GEAR[buf[i]] >>> 0;
+      if ((h & MASK_HARD) === 0) {
+        cut = i + 1;
+        break;
+      }
+    }
+    if (cut === end) {
+      for (; i < end; i++) {
+        h = (h << 1) + GEAR[buf[i]] >>> 0;
+        if ((h & MASK_EASY) === 0) {
+          cut = i + 1;
+          break;
+        }
+      }
+    }
+    out.push({ o: start, s: cut - start });
+    start = cut;
+  }
+  return out;
+}
+function chunkContent(buf) {
+  return chunkBoundaries(buf).map(({ o, s }) => {
+    const bytes = buf.subarray(o, o + s);
+    return { h: sha256(bytes), s, bytes };
+  });
+}
+
 // packages/client/src/api.js
+var PUT_BATCH_BYTES = 1024 * 1024;
+var PUT_PARALLEL = 4;
+var PUT_BATCH_CHUNKS = 100;
+var FETCH_BATCH_BYTES = 1024 * 1024;
+var FETCH_PARALLEL = 4;
+var kb = (n) => n < 1024 ? `${n} B` : n < 1048576 ? `${Math.round(n / 1024)} KB` : `${(n / 1048576).toFixed(1)} MB`;
+var describeTransfer = (t, verb) => t ? `${verb} ${t.moved} of ${t.total} chunk${t.total === 1 ? "" : "s"}, ${kb(t.bytes)}` : "";
 var ApiError = class extends Error {
   constructor(status, body) {
     super(body?.message ?? `HTTP ${status}`);
@@ -375,6 +459,39 @@ var Api = class {
     this.config = config;
     this.credentials = credentials;
     this.accessToken = null;
+    this.manifests = /* @__PURE__ */ new Map();
+    this.transfers = /* @__PURE__ */ new Map();
+  }
+  /** Authenticated POST with a binary body or a binary response; refreshes the token once on 401. */
+  async binary(p, { json, body, headers = {} }) {
+    const send = async (token) => {
+      let res;
+      try {
+        res = await fetch(this.base + "/v1" + p, {
+          method: "POST",
+          headers: { authorization: `Bearer ${token}`, "content-type": json ? "application/json" : "application/octet-stream", ...headers },
+          body: json ? JSON.stringify(json) : body,
+          signal: AbortSignal.timeout(18e4)
+        });
+      } catch (e) {
+        throw new OfflineError(`cannot reach the Tether server at ${this.base} (${e.cause?.code ?? e.message})`);
+      }
+      if (!res.ok) throw new ApiError(res.status, (await res.json().catch(() => ({}))).error);
+      return Buffer.from(await res.arrayBuffer());
+    };
+    try {
+      return await send(await this.token());
+    } catch (e) {
+      if (e instanceof ApiError && e.status === 401 && this.accessToken) {
+        this.accessToken = null;
+        return send(await this.token());
+      }
+      throw e;
+    }
+  }
+  /** The chunk list to commit for content uploaded by uploadBlobs (undefined on old servers). */
+  manifestFor(sha) {
+    return this.manifests.get(sha);
   }
   get base() {
     return this.config.get("server").replace(/\/$/, "");
@@ -485,10 +602,58 @@ var Api = class {
     this.credentials.clear();
     this.accessToken = null;
   }
-  /** Uploads canonical blobs the server doesn't have yet. blobs: [{ sha256, bytes }] */
-  async uploadBlobs(blobs) {
-    const unique = [...new Map(blobs.map((b) => [b.sha256, b])).values()];
-    if (!unique.length) return;
+  /**
+   * Uploads content as chunks (delta sync): every file is split into content-defined chunks and
+   * only the chunks the server does not have are sent. blobs: [{ sha256, bytes }] (canonical).
+   * Afterwards manifestFor(sha) gives each file's chunk list for the commit.
+   */
+  async uploadBlobs(blobs, { artifactId } = {}) {
+    const files2 = [...new Map(blobs.map((b) => [b.sha256, b])).values()];
+    if (!files2.length) return;
+    const all = /* @__PURE__ */ new Map();
+    for (const f of files2) {
+      const parts = chunkContent(f.bytes);
+      this.manifests.set(f.sha256, parts.map(({ h, s }) => ({ h, s })));
+      for (const c of parts) all.set(c.h, c.bytes);
+    }
+    let missing;
+    try {
+      ({ missing } = await this.call("POST", "/chunks/missing", { hashes: [...all.keys()], artifactId }));
+    } catch (e) {
+      if (!(e instanceof ApiError && e.status === 404)) throw e;
+      for (const f of files2) this.manifests.delete(f.sha256);
+      return this.uploadWhole(files2);
+    }
+    const batches = [];
+    let batch = [];
+    let size = 0;
+    for (const h of missing) {
+      const bytes = all.get(h);
+      if (batch.length && (batch.length >= PUT_BATCH_CHUNKS || size + bytes.length > PUT_BATCH_BYTES)) {
+        batches.push(batch);
+        batch = [];
+        size = 0;
+      }
+      batch.push({ h, bytes });
+      size += bytes.length;
+    }
+    if (batch.length) batches.push(batch);
+    let next = 0;
+    await Promise.all(Array.from({ length: Math.min(PUT_PARALLEL, batches.length) }, async () => {
+      while (next < batches.length) {
+        const b = batches[next++];
+        await this.binary("/chunks/put", { body: Buffer.concat(b.map((c) => c.bytes)), headers: { "x-tether-chunks": b.map((c) => `${c.h}:${c.bytes.length}`).join(",") } });
+      }
+    }));
+    const sent = new Set(missing);
+    for (const f of files2) {
+      const m = this.manifests.get(f.sha256);
+      const moved = m.filter((c) => sent.has(c.h));
+      this.transfers.set(f.sha256, { moved: moved.length, total: m.length, bytes: moved.reduce((a, c) => a + c.s, 0) });
+    }
+  }
+  /** Whole-file upload through signed URLs, for servers without delta sync. */
+  async uploadWhole(unique) {
     const { upload } = await this.call("POST", "/blobs/upload", { blobs: unique.map((b) => ({ sha256: b.sha256, size: b.bytes.length })) });
     const bySha = new Map(unique.map((b) => [b.sha256, b]));
     for (const u of upload) {
@@ -496,10 +661,63 @@ var Api = class {
       if (!res.ok && res.status !== 412) throw new ApiError(res.status, { message: `upload failed (${res.status}): ${(await res.text().catch(() => "")).slice(0, 200)}` });
     }
   }
-  /** Downloads blobs for [{ artifactId, version? }] into the cache; skips blobs already cached. */
+  /**
+   * Downloads content into the cache, by chunks (delta sync). items: [{ artifactId, version, sha,
+   * base? }] where base is content already cached (usually the version on disk): its chunks are
+   * reused, so only chunks that changed are downloaded.
+   */
   async fetchBlobs(cache, items) {
-    if (!items.length) return [];
-    const { downloads } = await this.call("POST", "/blobs/download", { items });
+    const need = [...new Map(items.filter((i) => !i.sha || !cache.has(i.sha)).map((i) => [`${i.artifactId}@${i.version}`, i])).values()];
+    if (!need.length) return;
+    let manifests;
+    try {
+      ({ manifests } = await this.call("POST", "/chunks/manifest", { items: need.map(({ artifactId, version }) => ({ artifactId, version })) }));
+    } catch (e) {
+      if (!(e instanceof ApiError && e.status === 404)) throw e;
+      return this.fetchWhole(cache, need);
+    }
+    for (const [k, m] of manifests.entries()) {
+      if (cache.has(m.blob)) continue;
+      const local = /* @__PURE__ */ new Map();
+      const base = need[k].base;
+      if (base && cache.has(base)) for (const c of chunkContent(cache.get(base))) local.set(c.h, c.bytes);
+      const size = new Map(m.chunks.map((c) => [c.h, c.s]));
+      const want = [...size.keys()].filter((h) => !local.has(h));
+      let bytesIn = 0;
+      const batches = [];
+      for (let i = 0; i < want.length; ) {
+        const batch = [];
+        let total = 0;
+        while (i < want.length && (!batch.length || total + size.get(want[i]) <= FETCH_BATCH_BYTES)) {
+          batch.push(want[i]);
+          total += size.get(want[i++]);
+        }
+        batches.push(batch);
+        bytesIn += total;
+      }
+      let next = 0;
+      await Promise.all(Array.from({ length: Math.min(FETCH_PARALLEL, batches.length) }, async () => {
+        while (next < batches.length) {
+          const batch = batches[next++];
+          const buf = await this.binary("/chunks/fetch", { json: { artifactId: m.artifactId, version: m.version, hashes: batch } });
+          let off = 0;
+          for (const h of batch) {
+            const bytes = buf.subarray(off, off + size.get(h));
+            off += size.get(h);
+            if (sha256(bytes) !== h) throw new Error("downloaded chunk does not match its hash");
+            local.set(h, Buffer.from(bytes));
+          }
+        }
+      }));
+      const content = Buffer.concat(m.chunks.map((c) => local.get(c.h)));
+      if (sha256(content) !== m.blob) throw new Error("downloaded content does not match its hash");
+      cache.put(m.blob, content);
+      this.transfers.set(m.blob, { moved: want.length, total: size.size, bytes: bytesIn });
+    }
+  }
+  /** Whole-file downloads through signed URLs, for servers without delta sync. */
+  async fetchWhole(cache, items) {
+    const { downloads } = await this.call("POST", "/blobs/download", { items: items.map(({ artifactId, version }) => ({ artifactId, version })) });
     for (const d of downloads) {
       if (cache.has(d.sha256)) continue;
       const res = await fetch(d.url);
@@ -771,6 +989,7 @@ function walkFiles(root) {
 var UserError = class extends Error {
 };
 var ACTIVE = (i) => i.mode !== "orphaned";
+var FULL_CHECK_MS = 60 * 60 * 1e3;
 var Engine = class {
   constructor({ db, api, cache, tracker, config, log = () => {
   }, notify = () => {
@@ -819,20 +1038,38 @@ var Engine = class {
     if (!this.cache.has(sha)) throw new Error(`content ${sha.slice(0, 12)} is not in the local cache`);
     return this.cache.get(sha);
   }
+  /** Downloads content not yet cached; `base` (content already here) lets only changed chunks travel. */
   async ensureBlobs(pairs) {
     const missing = pairs.filter((p) => p.sha && !this.cache.has(p.sha));
-    if (missing.length) await this.api.fetchBlobs(this.cache, missing.map(({ artifactId, version }) => ({ artifactId, version })));
+    if (missing.length) await this.api.fetchBlobs(this.cache, missing);
+  }
+  /** Uploads content (only chunks the server lacks) and returns the commit fields for it. */
+  async uploadContent(local, artifactId) {
+    await this.api.uploadBlobs([{ sha256: local.hash, bytes: local.canonical }], { artifactId });
+    this.cache.put(local.hash, local.canonical);
+    return { blob: local.hash, size: local.canonical.length, chunks: this.api.manifestFor(local.hash) };
+  }
+  /** ", sent 2 of 540 chunks, 17 KB" for log lines (empty when nothing is known). */
+  sentNote(sha) {
+    const t = describeTransfer(this.api.transfers.get(sha), "sent");
+    return t ? `; ${t}` : "";
   }
   /** Writes content for an instance at `p`; records the result for the quick change check. */
   writeInstance(inst, p, sha, eolMode = inst.eolMode, exec = inst.exec) {
     const style = inst.eolStyle ? { eol: inst.eolStyle, bom: !!inst.hasBom } : null;
-    return writeLocal(p, this.blobFor(sha), eolMode, { exec, style });
+    const st = writeLocal(p, this.blobFor(sha), eolMode, { exec, style });
+    if (inst.gitMode === "keep" && inst.gitRoot) {
+      restage(inst.gitRoot, p);
+      const after = statOrNull(p);
+      if (after) Object.assign(st, { size: after.size, mtimeMs: after.mtimeMs });
+    }
+    return st;
   }
   // ---------- tick ----------
   async tick({ remote = true } = {}) {
     this.busyCache = /* @__PURE__ */ new Map();
     await this.locateAll();
-    if (remote) await this.gitTransitions();
+    await this.gitPass();
     if (remote) {
       await this.checkRemote();
       await this.syncRealtime();
@@ -847,16 +1084,26 @@ var Engine = class {
     if (!this.busyCache.has(inst.gitDir)) this.busyCache.set(inst.gitDir, gitBusy(inst.gitDir));
     return !!this.busyCache.get(inst.gitDir);
   }
+  gitInstances() {
+    return this.db.all().filter((i) => i.gitMode && i.gitRoot && i.mode !== "orphaned");
+  }
   /** Sets the git mode on an instance (and a folder's files). Throws if follow is not allowed. */
   applyGitMode(root, mode) {
     if (!root) return;
     if (!GIT_MODES.includes(mode)) throw new UserError(`git mode must be one of ${GIT_MODES.join(", ")}`);
     if (mode === "follow" && root.role === "viewer") throw new UserError("git follow mode needs editor access");
+    if (mode === "follow" && !gitBinary()) throw new UserError("git follow mode needs git to be installed");
     const repo = findRepo(root.path);
     if (!repo) throw new UserError(`${root.path} is not inside a git repository`);
-    const fields = { gitMode: mode, gitRoot: repo.root, gitDir: repo.gitDir, gitHooks: repo.hooksDir };
-    for (const i of [root, ...root.kind === "folder" ? this.db.childrenOf(root.instanceId) : []]) this.db.update(i.instanceId, fields);
-    this.syncGitHooks();
+    const fields = { gitMode: mode, gitRoot: repo.root, gitDir: repo.gitDir, gitWaiting: false };
+    for (const i of [root, ...root.kind === "folder" ? this.db.childrenOf(root.instanceId) : []]) {
+      this.db.update(i.instanceId, fields);
+      if (i.kind === "file") setKeep(repo.root, i.path, mode === "keep");
+    }
+  }
+  /** Lets git see the file normally again (after unmanage, orphaning, or leaving keep mode). */
+  releaseGit(inst) {
+    if (inst.gitMode === "keep" && inst.kind === "file" && inst.gitRoot) setKeep(inst.gitRoot, inst.path, false);
   }
   /** `tether git <path> [--mode]`: show or change the git mode of managed files. */
   gitMode({ path: p, mode }) {
@@ -865,73 +1112,135 @@ var Engine = class {
     if (mode) for (const i of ts.filter((x) => !x.folderInstanceId || !folders.has(x.folderInstanceId))) this.applyGitMode(i.folderInstanceId ? this.db.get(i.folderInstanceId) : i, mode);
     return this.targets(p).map((i) => ({ path: i.path, kind: i.kind, role: i.role, gitMode: this.db.get(i.instanceId)?.gitMode ?? null, gitRoot: this.db.get(i.instanceId)?.gitRoot ?? findRepo(i.path)?.root ?? null }));
   }
-  /** Installs hooks in repositories with follow-mode files and removes them where none remain. */
-  syncGitHooks() {
-    if (!this.home || !this.cliPath) return;
-    const want = new Set(this.db.all().filter((i) => i.gitMode === "follow" && i.mode !== "orphaned" && i.gitHooks).map((i) => i.gitHooks));
-    const had = new Set(this.db.getMeta("gitHooks") ?? []);
-    for (const dir of want) {
-      try {
-        installHooks(dir, { home: this.home, node: process.execPath, cli: this.cliPath });
-      } catch (e) {
-        this.log(`could not install git hooks in ${dir}: ${e.message}`);
-      }
-    }
-    for (const dir of had) if (!want.has(dir)) removeHooks(dir, this.home);
-    this.db.setMeta("gitHooks", [...want]);
+  /** Tether 0.2.0 used git hooks; they are no longer needed. */
+  cleanupLegacyHooks() {
+    const dirs = this.db.getMeta("gitHooks") ?? [];
+    for (const dir of dirs) if (this.home) removeHooks(dir, this.home);
+    if (dirs.length) this.db.setMeta("gitHooks", null);
   }
-  /** Repositories that just finished a git operation (merge resolved, rebase done) get reconciled. */
-  async gitTransitions() {
-    const dirs = /* @__PURE__ */ new Map();
-    for (const i of this.db.all()) if (i.gitMode === "follow" && i.gitDir && i.mode !== "orphaned") dirs.set(i.gitDir, i.gitRoot);
-    for (const [gitDir, root] of dirs) {
-      const busy = gitBusy(gitDir);
-      const was = this.gitState.get(gitDir);
-      this.gitState.set(gitDir, busy);
-      if (was && !busy) await this.gitReconcile(root);
+  /** Managed files that ended up inside a git repository later (git init, moved into one) get keep mode. */
+  detectNewRepos() {
+    for (const i of this.db.all().filter((x) => !x.gitMode && !x.folderInstanceId && x.mode !== "orphaned" && !x.detached)) {
+      const repo = findRepo(i.path);
+      if (!repo) continue;
+      this.applyGitMode(i, "keep");
+      this.log(`${i.path}: now inside the git repository ${repo.root}; using keep mode`);
+      this.notify({ kind: "git-new", level: "info", short: path4.basename(i.path), title: "Managed file is now in a git repository", body: `${path4.basename(i.path)} is inside ${repo.root}. Tether keeps it as the shared version and git ignores Tether's copy. Run "tether git ${path4.basename(i.path)} --mode follow" to publish git's changes instead.` });
     }
   }
   /**
-   * After git changed files (hook, or the end of a merge/rebase): publish git's version of
-   * follow-mode files. If Tether also moved on, the file stays in editing mode for `tether done`.
+   * Runs after git may have changed files (watcher on the git directory, and every tick):
+   * follows renames git made, brings back files git restored, keeps keep-mode files hidden from
+   * git, and publishes follow-mode files whose content now matches git's committed or staged state.
    */
-  async gitReconcile(root) {
-    if (gitBusy(findRepo(root)?.gitDir)) return { busy: true };
-    const mine = () => this.db.all().filter((i) => i.gitMode === "follow" && i.kind === "file" && i.mode === "normal" && i.gitRoot && samePath(i.gitRoot, root));
-    for (const i of mine().filter((x) => x.detached)) {
-      if (statOrNull(i.path)?.isFile()) {
-        this.db.update(i.instanceId, { ...this.identity(i.path), detached: false, missingSince: null, size: null, mtimeMs: null });
-        this.log(`${i.path}: back (restored by git)`);
+  async gitPass({ only } = {}) {
+    const repos = /* @__PURE__ */ new Map();
+    for (const i of this.gitInstances()) if (!only || samePath(i.gitRoot, only)) repos.set(i.gitDir, i.gitRoot);
+    if (!repos.size) return;
+    const heads = this.db.getMeta("gitHeads") ?? {};
+    const publish = [];
+    for (const [gitDir, root] of repos) {
+      if (gitBusy(gitDir)) continue;
+      const h = gitBinary() ? head(root) : null;
+      const prev = heads[gitDir];
+      const headMoved = !!h && h !== prev;
+      if (h && prev && h !== prev) await this.followGitHistory(root, prev, h);
+      if (h) heads[gitDir] = h;
+      for (const i of this.gitInstances().filter((x) => x.gitDir === gitDir)) {
+        if (i.kind !== "file") continue;
+        if (i.detached) {
+          if (statOrNull(i.path)?.isFile()) {
+            this.db.update(i.instanceId, { ...this.identity(i.path), detached: false, missingSince: null, size: null, mtimeMs: null });
+            if (i.gitMode === "keep") setKeep(root, i.path, true);
+            this.log(`${i.path}: back (restored by git)`);
+          }
+          continue;
+        }
+        if (i.mode !== "normal") continue;
+        if (i.gitMode === "keep") {
+          if ((headMoved || !prev) && gitBinary() && !isKept(root, i.path)) setKeep(root, i.path, true);
+          continue;
+        }
+        if (!gitBinary()) continue;
+        let local;
+        try {
+          local = readLocal(i.path, i.eolMode);
+        } catch {
+          continue;
+        }
+        if (i.gitOverlay) {
+          if (fileBlob(root, i.path) !== blobAt(root, "HEAD", i.path)) continue;
+          setKeep(root, i.path, false);
+          this.db.update(i.instanceId, { gitOverlay: false });
+          i.gitOverlay = false;
+        }
+        const folder = i.folderInstanceId ? this.folderOf(i) : null;
+        const rel = folder ? this.localRel(i, folder) : null;
+        const moved = folder && rel && rel !== i.relPath;
+        const changed = local && local.hash !== i.baseHash;
+        if (!changed && !moved) continue;
+        const { fromGit, commit } = changed ? changeFromGit(root, i.path) : { fromGit: true, commit: null };
+        if (fromGit) publish.push({ inst: i, local: changed ? local : null, commit, relPath: moved ? rel : void 0 });
       }
     }
-    await this.locateAll();
-    const changed = [];
-    for (const i of mine().filter((x) => !x.detached)) {
-      try {
-        const local = readLocal(i.path, i.eolMode);
-        if (local && local.hash !== i.baseHash) changed.push({ inst: i, local });
-      } catch {
+    this.db.setMeta("gitHeads", heads);
+    if (publish.length) await this.publishGitChanges(publish);
+  }
+  /** Renames and new files git brought in between two commits. */
+  async followGitHistory(root, from, to) {
+    for (const c of changesBetween(root, from, to)) {
+      if (c.status === "R") {
+        const inst = this.gitInstances().find((i) => i.kind === "file" && samePath(i.path, c.from));
+        if (inst && !statOrNull(c.from) && statOrNull(c.to)?.isFile()) {
+          this.db.update(inst.instanceId, { path: canonicalPath(c.to), ...this.identity(c.to), detached: false, missingSince: null, size: null, mtimeMs: null });
+          if (inst.gitMode === "keep") {
+            setKeep(root, c.from, false);
+            setKeep(root, c.to, true);
+          }
+          this.log(`${c.from} -> ${c.to}: followed a rename made in git`);
+        }
+      } else if (c.status === "A" && !this.instanceAt(c.to) && statOrNull(c.to)?.isFile()) {
+        const folder = this.gitInstances().find((i) => i.kind === "folder" && i.gitMode === "follow" && isUnder(c.to, i.path) && !samePath(c.to, i.path));
+        if (!folder) continue;
+        const name = path4.basename(c.to);
+        if (folder.role === "owner") {
+          try {
+            const r = await this.add({ path: c.to, gitCommit: to });
+            this.log(`${c.to}: added to ${folder.path} (new in git)`);
+            this.notify({ kind: "git-published", level: "info", short: name, title: "Published git's changes", body: `${r.relPath} is new in git and was added to ${path4.basename(folder.path)} for everyone.` });
+          } catch (e) {
+            this.log(`${c.to}: could not add (${e.message})`);
+          }
+        } else {
+          this.notify({ kind: "git-new-file", level: "info", short: name, title: "New file in a managed folder", body: `git added ${name} inside ${path4.basename(folder.path)}. Only the owner can add files to it, so it is not shared through Tether.` });
+        }
       }
     }
-    if (!changed.length) return { published: 0 };
+  }
+  /**
+   * Publishes git's version of follow-mode files. If Tether already has exactly that content it is
+   * adopted; if Tether moved on to something else, the file stays in editing mode for `tether done`.
+   */
+  async publishGitChanges(list) {
     let results;
     try {
-      ({ results } = await this.api.call("POST", "/sync/check", { items: changed.map(({ inst }) => ({ artifactId: inst.artifactId, version: inst.baseVersion })) }));
+      ({ results } = await this.api.call("POST", "/sync/check", { items: list.map(({ inst }) => ({ artifactId: inst.artifactId, version: inst.baseVersion })) }));
     } catch (e) {
       if (!(e instanceof OfflineError)) throw e;
-      for (const { inst } of changed) this.db.update(inst.instanceId, { mode: "editing", lastError: "git changed this file while offline; run `tether done` to publish it" });
-      return { published: 0, offline: true };
+      for (const { inst } of list) this.db.update(inst.instanceId, { mode: "editing", lastError: "git changed this file while offline; run `tether done` to publish it" });
+      return;
     }
-    let published = 0;
-    for (const [k, { inst, local }] of changed.entries()) {
+    for (const [k, { inst, local, commit, relPath }] of list.entries()) {
       const r = results[k];
       const name = path4.basename(inst.path);
+      const hash = local?.hash ?? inst.baseHash;
       if (r.status === "gone" || r.state?.deleted || r.folderDeleted) {
         this.orphan(inst, r.reason ?? "deleted");
         continue;
       }
       if (r.role === "viewer") {
         this.db.update(inst.instanceId, { gitMode: "keep", role: "viewer" });
+        setKeep(inst.gitRoot, inst.path, true);
         continue;
       }
       const conflict = () => {
@@ -939,18 +1248,32 @@ var Engine = class {
         this.log(`${inst.path}: git changed it but Tether also has a newer version; left in editing mode`);
         this.notify({ kind: "conflict", level: "warn", title: "Merge conflict (git and Tether)", body: `${name}: git changed it, but someone also pushed a newer version to Tether. Git's version is kept and the file is in editing mode; run "tether done" to choose.`, short: name, artifactId: inst.artifactId });
       };
+      const adopt = (state) => {
+        this.db.update(inst.instanceId, { baseVersion: state.version, remoteVersion: state.version, baseHash: state.blob, relPath: state.relPath ?? inst.relPath, gitWaiting: false, lastError: null, ...local ? { size: local.size, mtimeMs: local.mtimeMs, ...styleOf(local) } : {} });
+        this.log(`${inst.path}: git's version is already on Tether (v${state.version})`);
+      };
       if (r.status === "changed") {
-        conflict();
+        if (r.state.blob === hash && (relPath === void 0 || r.state.relPath === relPath)) adopt(r.state);
+        else conflict();
         continue;
       }
       try {
-        await this.api.uploadBlobs([{ sha256: local.hash, bytes: local.canonical }]);
-        this.cache.put(local.hash, local.canonical);
-        const c = await this.api.call("POST", `/artifacts/${inst.artifactId}/commit`, { baseVersion: inst.baseVersion, change: { blob: local.hash, size: local.canonical.length } });
-        this.db.update(inst.instanceId, { baseVersion: c.version, remoteVersion: c.version, baseHash: local.hash, size: local.size, mtimeMs: local.mtimeMs, ...styleOf(local), lastError: null });
-        this.log(`${inst.path}: published git's version as v${c.version}`);
+        const change = { gitCommit: commit ?? null };
+        if (local) Object.assign(change, await this.uploadContent(local, inst.artifactId));
+        if (relPath !== void 0) change.relPath = relPath;
+        const c = await this.api.call("POST", `/artifacts/${inst.artifactId}/commit`, { baseVersion: inst.baseVersion, change });
+        this.db.update(inst.instanceId, {
+          baseVersion: c.version,
+          remoteVersion: c.version,
+          baseHash: hash,
+          relPath: relPath ?? inst.relPath,
+          gitWaiting: false,
+          lastError: null,
+          ...local ? { size: local.size, mtimeMs: local.mtimeMs, ...styleOf(local) } : {}
+        });
+        const sent = local ? describeTransfer(this.api.transfers.get(local.hash), "sent") : "";
+        this.log(`${inst.path}: published git's version as v${c.version}${sent ? ` (${sent})` : ""}`);
         this.notify({ kind: "git-published", level: "info", title: "Published git's changes", body: `${name} is now v${c.version} for everyone who has it.`, short: name, artifactId: inst.artifactId });
-        published++;
       } catch (e) {
         if (e instanceof ApiError && e.status === 409) conflict();
         else if (e instanceof ApiError) {
@@ -959,7 +1282,11 @@ var Engine = class {
         } else throw e;
       }
     }
-    return { published };
+  }
+  /** Hook calls from Tether 0.2.0 installs, and explicit syncs. */
+  async gitReconcile(root) {
+    await this.locateAll();
+    await this.gitPass({ only: root });
   }
   // ---------- realtime editing ----------
   /** Files this client is editing live (every save is pushed). */
@@ -1008,7 +1335,7 @@ var Engine = class {
         const local = readLocal(cur.path, cur.eolMode);
         if (r.status === "changed") {
           if (!local || local.hash === cur.baseHash) {
-            await this.ensureBlobs([{ artifactId: cur.artifactId, version: r.state.version, sha: r.state.blob }]);
+            await this.ensureBlobs([{ artifactId: cur.artifactId, version: r.state.version, sha: r.state.blob, base: cur.baseHash }]);
             this.applyIncoming(cur, r.state);
           } else {
             if (!cur.lastError?.startsWith("conflict")) {
@@ -1020,12 +1347,11 @@ var Engine = class {
           continue;
         }
         if (!local || local.hash === cur.baseHash) continue;
-        await this.api.uploadBlobs([{ sha256: local.hash, bytes: local.canonical }]);
-        this.cache.put(local.hash, local.canonical);
+        const content = await this.uploadContent(local, cur.artifactId);
         try {
-          const c = await this.api.call("POST", `/artifacts/${cur.artifactId}/commit`, { baseVersion: cur.baseVersion, change: { blob: local.hash, size: local.canonical.length } });
+          const c = await this.api.call("POST", `/artifacts/${cur.artifactId}/commit`, { baseVersion: cur.baseVersion, change: content });
           this.db.update(cur.instanceId, { baseVersion: c.version, remoteVersion: c.version, baseHash: local.hash, size: local.size, mtimeMs: local.mtimeMs, ...styleOf(local), lastError: null });
-          this.log(`${cur.path}: pushed v${c.version} (realtime)`);
+          this.log(`${cur.path}: pushed v${c.version} (realtime${this.sentNote(local.hash)})`);
         } catch (e) {
           if (!(e instanceof ApiError && e.status === 409)) throw e;
           this.db.update(cur.instanceId, { lastError: "conflict: the server changed; run `tether done` to resolve" });
@@ -1098,7 +1424,7 @@ var Engine = class {
       this.log(`${inst.path}: folder deleted locally; no longer managed here`);
       return;
     }
-    if (inst.gitMode === "follow" && inst.mode === "normal" && !inst.folderInstanceId) {
+    if (inst.gitMode && inst.mode === "normal") {
       this.db.update(inst.instanceId, { detached: true, missingSince: null });
       this.log(`${inst.path}: removed (by git?); waiting for git to bring it back`);
     } else if (inst.mode === "editing") {
@@ -1114,11 +1440,36 @@ var Engine = class {
   }
   orphan(inst, reason) {
     const targets = inst.kind === "folder" ? [inst, ...this.db.childrenOf(inst.instanceId)] : [inst];
-    for (const t of targets) this.db.update(t.instanceId, { mode: "orphaned", orphanReason: reason });
+    for (const t of targets) {
+      this.releaseGit(t);
+      this.db.update(t.instanceId, { mode: "orphaned", orphanReason: reason });
+    }
     const what = reason === "revoked" ? "access revoked" : reason === "deleted" ? "deleted on the server" : "removed from the server";
     this.log(`${inst.path}: ${what}; file kept, no longer tracked`);
     this.notify({ kind: "orphaned", level: "warn", title: "No longer synced", body: `${path4.basename(inst.path)}: ${what}. Your copy stays on disk but Tether no longer keeps it up to date.`, short: path4.basename(inst.path) });
   }
+  /** What a check asks about; a change cursor is only valid for the same question. */
+  checkKey(insts) {
+    return insts.map((i) => `${i.artifactId}@${i.baseVersion}:${i.mode}`).join(",");
+  }
+  /**
+   * The change cursor from the last full check, if it can be reused: same instances, nothing
+   * pending, no live sessions, and a full check at least every FULL_CHECK_MS as a safety net.
+   */
+  reusableCursor(insts) {
+    const f = this.feed;
+    if (!f || this.realtimeActive || Date.now() - f.at > FULL_CHECK_MS) return void 0;
+    return f.key === this.checkKey(insts) ? f.cursor : void 0;
+  }
+  /**
+   * Keeps the server's cursor only when nothing is pending here: an incoming version held back
+   * (editing, unmanaged, waiting for git) must be offered again by a full check once it can apply.
+   */
+  rememberCursor(cursor) {
+    const insts = this.db.all().filter(ACTIVE);
+    const settled = insts.every((i) => i.remoteVersion == null || i.remoteVersion === i.baseVersion);
+    this.feed = cursor !== void 0 && settled ? { cursor, key: this.checkKey(insts), at: Date.now() } : null;
+  }
   /** One batched call for all instances (DESIGN §6.1 step 2). */
   async checkRemote() {
     const insts = this.db.all().filter(ACTIVE);
@@ -1126,10 +1477,15 @@ var Engine = class {
       this.offline = null;
       return;
     }
-    let results;
+    let results, cursor;
     try {
-      ({ results } = await this.api.call("POST", "/sync/check", { items: insts.map((i) => ({ artifactId: i.artifactId, version: i.baseVersion })) }));
+      const rootOf = (i) => i.folderInstanceId ? this.db.get(i.folderInstanceId)?.artifactId : void 0;
+      const items = insts.map((i) => ({ artifactId: i.artifactId, version: i.baseVersion, root: rootOf(i) }));
+      const body = { items, cursor: this.reusableCursor(insts) };
+      const res = await this.api.call("POST", "/sync/check", body);
       this.offline = null;
+      if (res.unchanged) return;
+      ({ results, cursor } = res);
     } catch (e) {
       if (e instanceof OfflineError || e instanceof ApiError && e.status === 401) {
         this.offline = e.message;
@@ -1142,6 +1498,7 @@ var Engine = class {
     const folders = [];
     insts.forEach((inst, idx) => {
       const r = results[idx];
+      if (!r) return;
       const cur = this.db.get(inst.instanceId);
       if (!cur || cur.mode === "orphaned") return;
       if (r.status === "gone") return this.orphan(cur, r.reason);
@@ -1169,20 +1526,36 @@ var Engine = class {
       else if (!now.detached) incoming.push({ inst: now, state: r.state });
     });
     const newChildren = [];
+    const waiting = /* @__PURE__ */ new Set();
     for (const f of folders) {
       const have = new Set(this.db.childrenOf(f.inst.instanceId).map((c) => c.artifactId));
-      for (const c of f.children) if (!c.deleted && !have.has(c.artifactId)) newChildren.push({ folder: f.inst, child: c });
+      for (const c of f.children) {
+        if (c.deleted || have.has(c.artifactId)) continue;
+        if (f.inst.gitMode === "follow" && c.gitCommit && !isAncestor(f.inst.gitRoot, c.gitCommit)) {
+          waiting.add(f.inst.instanceId);
+          continue;
+        }
+        newChildren.push({ folder: f.inst, child: c });
+      }
     }
     try {
       await this.ensureBlobs([
-        ...incoming.map(({ state }) => ({ artifactId: state.artifactId, version: state.version, sha: state.blob })),
+        ...incoming.map(({ inst, state }) => ({ artifactId: state.artifactId, version: state.version, sha: state.blob, base: inst.baseHash })),
         ...newChildren.map(({ child }) => ({ artifactId: child.artifactId, version: child.version, sha: child.blob }))
       ]);
     } catch (e) {
       if (e instanceof OfflineError) return this.offline = e.message;
       throw e;
     }
-    for (const { inst, state } of incoming) if (!this.isGitBusy(inst)) this.applyIncoming(inst, state);
+    for (const { inst, state } of incoming) {
+      if (this.isGitBusy(inst)) continue;
+      if (inst.gitMode === "follow" && state.gitCommit && !isAncestor(inst.gitRoot, state.gitCommit)) {
+        if (!inst.gitWaiting) this.log(`${inst.path}: v${state.version} came from git commit ${state.gitCommit.slice(0, 8)}; it will arrive with your next git pull`);
+        this.db.update(inst.instanceId, { gitWaiting: true });
+        continue;
+      }
+      this.applyIncoming(inst, state);
+    }
     for (const { folder, child } of newChildren) {
       this.db.insert({
         instanceId: newInstanceId(),
@@ -1204,10 +1577,13 @@ var Engine = class {
       });
       this.log(`${folder.path}: new file ${child.relPath}`);
     }
-    for (const f of folders) this.db.update(f.inst.instanceId, { baseVersion: f.state.version });
+    for (const f of folders) if (!waiting.has(f.inst.instanceId)) this.db.update(f.inst.instanceId, { baseVersion: f.state.version });
+    if (results.some((r) => r && r.status !== "ok")) this.activityAt = Date.now();
+    this.rememberCursor(cursor);
   }
   /** Normal mode: write an incoming version (content and/or layout). */
   applyIncoming(inst, state) {
+    if (!statOrNull(inst.path)) return;
     try {
       let p = inst.path;
       if (inst.folderInstanceId && state.relPath !== inst.relPath) {
@@ -1219,11 +1595,18 @@ var Engine = class {
         p = to;
         this.log(`${inst.path} -> ${to}: moved by the server`);
       }
-      const patch = { path: p, relPath: state.relPath, baseVersion: state.version, baseHash: state.blob, eolMode: state.eol, exec: state.exec, lastError: null };
+      const patch = { path: p, relPath: state.relPath, baseVersion: state.version, baseHash: state.blob, eolMode: state.eol, exec: state.exec, lastError: null, gitWaiting: false };
       const localEdit = !this.matchesBase(inst, p) && readLocal(p, inst.eolMode)?.hash !== state.blob;
       if (state.blob !== inst.baseHash || localEdit) {
         Object.assign(patch, this.writeInstance(inst, p, state.blob, state.eol, state.exec));
-        this.log(`${p}: updated to version ${state.version}${localEdit ? " (local change replaced)" : ""}`);
+        const got = describeTransfer(this.api.transfers.get(state.blob), "received");
+        this.api.transfers.delete(state.blob);
+        this.log(`${p}: updated to version ${state.version}${localEdit ? " (local change replaced)" : ""}${got ? ` (${got})` : ""}`);
+        if (inst.gitMode === "follow" && inst.gitRoot && !state.gitCommit && blobAt(inst.gitRoot, "HEAD", p) !== fileBlob(inst.gitRoot, p)) {
+          setKeep(inst.gitRoot, p, true);
+          patch.gitOverlay = true;
+          this.notify({ kind: "git-overlay", level: "info", short: path4.basename(p), artifactId: inst.artifactId, title: "Changed through Tether", body: `${path4.basename(p)} now has Tether's v${state.version}, which is not in git. Git does not see this change; the next change to the file in git replaces it.` });
+        }
         if (localEdit) {
           const name = path4.basename(p);
           this.notify({
@@ -1263,6 +1646,22 @@ var Engine = class {
     const local = readLocal(p, inst.eolMode);
     return local?.hash === inst.baseHash;
   }
+  /**
+   * Follow mode, just before a revert: is this content git's own (a git operation that started
+   * after this pass checked, e.g. a cherry-pick between writing the file and moving HEAD)? Asks git
+   * afresh, since the pass's busy check may be stale by now.
+   */
+  gitWroteIt(inst) {
+    if (inst.gitMode !== "follow" || !inst.gitRoot) return false;
+    if (gitBusy(inst.gitDir)) return true;
+    const blob = fileBlob(inst.gitRoot, inst.path);
+    if (!blob) return false;
+    if (blob === indexBlob(inst.gitRoot, inst.path) || blob === blobAt(inst.gitRoot, "HEAD", inst.path)) {
+      this.gitPassDue = true;
+      return true;
+    }
+    return false;
+  }
   /** Normal mode: restore missing files, put moved files back, revert local edits. */
   async enforceLocal() {
     const restores = this.db.all().filter((i) => ACTIVE(i) && i.needsRestore && i.mode === "normal");
@@ -1293,6 +1692,7 @@ var Engine = class {
           continue;
         }
         if (!this.cache.has(cur.baseHash)) continue;
+        if (this.gitWroteIt(cur)) continue;
         this.db.update(cur.instanceId, { ...this.writeInstance(cur, cur.path, cur.baseHash), lastError: null });
         this.log(`${cur.path}: local change reverted (use \`tether edit\` to change it)`);
         const byGit = cur.gitMode === "keep";
@@ -1383,7 +1783,7 @@ var Engine = class {
     if (st.isFile()) {
       const f = this.prepareFile(abs, name, rules, eol);
       await this.api.uploadBlobs([f]);
-      const r2 = await this.api.call("POST", "/artifacts", { repoId: repo.repoId, kind: "file", name, blob: f.sha256, size: f.size, eol: f.eol, exec: f.exec });
+      const r2 = await this.api.call("POST", "/artifacts", { repoId: repo.repoId, kind: "file", name, blob: f.sha256, size: f.size, chunks: this.api.manifestFor(f.sha256), eol: f.eol, exec: f.exec });
       this.cache.put(f.sha256, f.bytes);
       const local = readLocal(abs, f.eol);
       this.db.insert({
@@ -1422,7 +1822,7 @@ var Engine = class {
       repoId: repo.repoId,
       kind: "folder",
       name,
-      files: prepared.map((f) => ({ relPath: f.rel, blob: f.sha256, size: f.size, eol: f.eol, exec: f.exec }))
+      files: prepared.map((f) => ({ relPath: f.rel, blob: f.sha256, size: f.size, chunks: this.api.manifestFor(f.sha256), eol: f.eol, exec: f.exec }))
     });
     const folderInst = this.db.insert({
       instanceId: newInstanceId(),
@@ -1469,7 +1869,7 @@ var Engine = class {
     return { artifactId: r.artifact.artifactId, shareId: r.artifact.shareId, kind: "folder", path: abs, files: files2.length, skippedSymlinks: symlinks };
   }
   /** `tether add <path>`: owner adds a new file inside a managed folder. */
-  async add({ path: target }) {
+  async add({ path: target, gitCommit }) {
     const abs = canonicalPath(path4.resolve(target));
     if (!statOrNull(abs)?.isFile()) throw new UserError(`${abs} is not a file`);
     if (this.instanceAt(abs)) throw new UserError(`${abs} is already managed`);
@@ -1482,7 +1882,7 @@ var Engine = class {
     const repo = (await this.api.call("GET", "/repos")).find((r) => r.repoId === folder.repoId);
     const f = this.prepareFile(abs, rel, repo?.eolDefaults ?? {});
     await this.api.uploadBlobs([f]);
-    const child = await this.api.call("POST", `/artifacts/${folder.artifactId}/children`, { relPath: rel, blob: f.sha256, size: f.size, eol: f.eol, exec: f.exec });
+    const child = await this.api.call("POST", `/artifacts/${folder.artifactId}/children`, { relPath: rel, blob: f.sha256, size: f.size, chunks: this.api.manifestFor(f.sha256), eol: f.eol, exec: f.exec, gitCommit });
     this.cache.put(f.sha256, f.bytes);
     const local = readLocal(abs, f.eol);
     this.db.insert({
@@ -1533,8 +1933,21 @@ var Engine = class {
     const base = { repoId: a.repoId, role: r.role, canDelete: r.canDelete };
     if (a.kind === "file") {
       await this.ensureBlobs([{ artifactId: a.artifactId, version: a.version, sha: a.blob }]);
-      const existing = readLocal(target, a.eol);
-      if (existing && existing.hash !== a.blob) throw new UserError(`${target} already exists with different content; choose another destination`);
+      let existing = readLocal(target, a.eol);
+      let mode = "normal";
+      let lastError = null;
+      let note;
+      if (existing && existing.hash !== a.blob) {
+        const clash = this.gitClash(target, gitMode, a.relPath ?? a.name);
+        if (clash === "replace") {
+          existing = null;
+          note = "replaced git's version with Tether's (git still has it)";
+        } else {
+          mode = "editing";
+          lastError = "git's version differs from Tether's; run `tether done` to publish it or accept Tether's";
+          note = "kept git's version; run `tether done` to publish it or accept Tether's";
+        }
+      }
       const st2 = existing ? { size: existing.size, mtimeMs: existing.mtimeMs, ...styleOf(existing) } : writeLocal(target, this.blobFor(a.blob), a.eol, { exec: a.exec });
       this.db.insert({
         ...base,
@@ -1544,7 +1957,8 @@ var Engine = class {
         name: a.name,
         path: canonicalPath(target),
         ...this.identity(target),
-        mode: "normal",
+        mode,
+        lastError,
         baseVersion: a.version,
         baseHash: a.blob,
         ...st2,
@@ -1552,18 +1966,17 @@ var Engine = class {
         exec: a.exec,
         remoteVersion: a.version
       });
-      return { kind: "file", path: canonicalPath(target), role: r.role, version: a.version };
+      return { kind: "file", path: canonicalPath(target), role: r.role, version: a.version, note };
     }
     const st = statOrNull(target);
     if (st && !st.isDirectory()) throw new UserError(`${target} exists and is not a folder`);
     await this.ensureBlobs(r.children.map((c) => ({ artifactId: c.artifactId, version: c.version, sha: c.blob })));
-    const clashes = [];
+    const clashes = /* @__PURE__ */ new Map();
     for (const c of r.children) {
       const p = path4.join(target, ...c.relPath.split("/"));
       const ex = readLocal(p, c.eol);
-      if (ex && ex.hash !== c.blob) clashes.push(c.relPath);
+      if (ex && ex.hash !== c.blob) clashes.set(c.relPath, this.gitClash(p, gitMode, c.relPath));
     }
-    if (clashes.length) throw new UserError(`${target} already has different files: ${clashes.join(", ")}; choose another destination`);
     fs6.mkdirSync(target, { recursive: true });
     const folderInst = this.db.insert({
       ...base,
@@ -1579,7 +1992,8 @@ var Engine = class {
     });
     for (const c of r.children) {
       const p = path4.join(folderInst.path, ...c.relPath.split("/"));
-      const ex = readLocal(p, c.eol);
+      const clash = clashes.get(c.relPath);
+      const ex = clash === "replace" ? null : readLocal(p, c.eol);
       const cst = ex ? { size: ex.size, mtimeMs: ex.mtimeMs, ...styleOf(ex) } : writeLocal(p, this.blobFor(c.blob), c.eol, { exec: c.exec });
       this.db.insert({
         ...base,
@@ -1591,10 +2005,11 @@ var Engine = class {
         relPath: c.relPath,
         path: canonicalPath(p),
         ...this.identity(p),
-        mode: "normal",
         baseVersion: c.version,
         baseHash: c.blob,
         ...cst,
+        mode: clash === "keep-git" ? "editing" : "normal",
+        lastError: clash === "keep-git" ? "git's version differs from Tether's; run `tether done`" : null,
         eolMode: c.eol,
         exec: c.exec,
         remoteVersion: c.version
@@ -1602,6 +2017,21 @@ var Engine = class {
     }
     return { kind: "folder", path: folderInst.path, role: r.role, files: r.children.length, version: a.version };
   }
+  /**
+   * A pulled file already exists with different content. Only allowed when git holds that
+   * content safely (tracked, no uncommitted changes): keep mode replaces it with Tether's version,
+   * follow mode keeps git's version in editing mode. Otherwise the pull is refused.
+   */
+  gitClash(p, gitMode, label) {
+    const repo = gitMode && findRepo(p);
+    if (repo && gitBinary() && isTracked(repo.root, p)) {
+      const blob = fileBlob(repo.root, p);
+      const clean = blob && (blob === blobAt(repo.root, "HEAD", p) || blob === indexBlob(repo.root, p));
+      if (clean) return gitMode === "keep" ? "replace" : "keep-git";
+      throw new UserError(`${label} differs from Tether's version and has uncommitted git changes; commit or stash them first`);
+    }
+    throw new UserError(`${p} already exists with different content; choose another destination`);
+  }
   /** Instances addressed by a path: a file, a managed folder (with its files), or any directory. */
   targets(p) {
     const abs = canonicalPath(path4.resolve(p));
@@ -1669,6 +2099,7 @@ You can still run \`tether edit\` without --realtime, but expect merge conflicts
   }
   async unmanage({ path: p }) {
     for (const i of this.targets(p).filter((x) => x.realtime)) await this.releaseRealtime(i);
+    for (const i of this.targets(p)) this.releaseGit(i);
     return { changed: this.setMode(p, "unmanaged", ["normal", "editing"]) };
   }
   /**
@@ -1796,16 +2227,16 @@ You can still run \`tether edit\` without --realtime, but expect merge conflicts
       case "push": {
         const local = readLocal(inst.path, inst.eolMode);
         const change = {};
-        if (local && local.hash !== inst.baseHash) {
-          await this.api.uploadBlobs([{ sha256: local.hash, bytes: local.canonical }]);
-          this.cache.put(local.hash, local.canonical);
-          Object.assign(change, { blob: local.hash, size: local.canonical.length });
-        }
+        if (local && local.hash !== inst.baseHash) Object.assign(change, await this.uploadContent(local, inst.artifactId));
         if (folder) {
           const rel = this.localRel(inst, folder);
           if (rel && rel !== inst.relPath) change.relPath = rel;
         }
         const baseVersion = item.incoming ? item.serverVersion : inst.baseVersion;
+        if (inst.gitMode === "follow" && inst.gitRoot && change.blob) {
+          const g = changeFromGit(inst.gitRoot, inst.path);
+          if (g.fromGit && g.commit) change.gitCommit = g.commit;
+        }
         const r = await this.api.call("POST", `/artifacts/${inst.artifactId}/commit`, { baseVersion, change });
         const state = r.state;
         this.db.update(inst.instanceId, {
@@ -1818,7 +2249,7 @@ You can still run \`tether edit\` without --realtime, but expect merge conflicts
           mtimeMs: local?.mtimeMs ?? null,
           ...local ? styleOf(local) : {}
         });
-        return { version: r.version };
+        return { version: r.version, sent: change.blob ? describeTransfer(this.api.transfers.get(change.blob), "sent") : "" };
       }
       case "delete": {
         await this.api.call("POST", `/artifacts/${inst.artifactId}/commit`, { baseVersion: item.serverVersion, change: { deleted: true } });
@@ -1844,7 +2275,7 @@ You can still run \`tether edit\` without --realtime, but expect merge conflicts
     if (!inst || inst.kind !== "file") throw new UserError("diff needs a managed file");
     const { artifact } = await this.api.call("GET", `/artifacts/${inst.artifactId}`);
     if (artifact.deleted) throw new UserError("the artifact has been deleted on the server");
-    await this.ensureBlobs([{ artifactId: inst.artifactId, version: artifact.version, sha: artifact.blob }]);
+    await this.ensureBlobs([{ artifactId: inst.artifactId, version: artifact.version, sha: artifact.blob, base: inst.baseHash }]);
     const server = this.cache.get(artifact.blob);
     const local = inst.detached ? null : readLocal(inst.path, inst.eolMode);
     const label = path4.basename(inst.path);
@@ -1878,6 +2309,8 @@ You can still run \`tether edit\` without --realtime, but expect merge conflicts
       if (i.orphanReason) flags.push(i.orphanReason);
       if (i.realtime && i.mode === "editing") flags.push("realtime: your saves are pushed live");
       if (i.gitMode) flags.push(`git: ${i.gitMode}`);
+      if (i.gitWaiting) flags.push("newer version arrives with your next git pull");
+      if (i.gitOverlay) flags.push("Tether-only version (hidden from git)");
       if (i.remoteRealtime && i.mode !== "orphaned") flags.push(`realtime edits by ${JSON.parse(i.remoteRealtime).email}`);
       return {
         instanceId: i.instanceId,
@@ -1933,6 +2366,68 @@ import { spawn } from "node:child_process";
 var AUMID = "Tether.Sync";
 var FLUSH_MS = 3e3;
 var LEVELS = { info: 0, warn: 1, error: 2 };
+var SHORTCUT_SCRIPT = String.raw`Add-Type -TypeDefinition @'
+using System;
+using System.Text;
+using System.Runtime.InteropServices;
+using System.Runtime.InteropServices.ComTypes;
+
+namespace TetherShortcut {
+  [ComImport, Guid("00021401-0000-0000-C000-000000000046")] class CShellLink {}
+
+  [ComImport, InterfaceType(ComInterfaceType.InterfaceIsIUnknown), Guid("000214F9-0000-0000-C000-000000000046")]
+  interface IShellLinkW {
+    void GetPath([Out, MarshalAs(UnmanagedType.LPWStr)] StringBuilder f, int cch, IntPtr fd, uint flags);
+    void GetIDList(out IntPtr pidl);
+    void SetIDList(IntPtr pidl);
+    void GetDescription([Out, MarshalAs(UnmanagedType.LPWStr)] StringBuilder s, int cch);
+    void SetDescription([MarshalAs(UnmanagedType.LPWStr)] string s);
+    void GetWorkingDirectory([Out, MarshalAs(UnmanagedType.LPWStr)] StringBuilder s, int cch);
+    void SetWorkingDirectory([MarshalAs(UnmanagedType.LPWStr)] string s);
+    void GetArguments([Out, MarshalAs(UnmanagedType.LPWStr)] StringBuilder s, int cch);
+    void SetArguments([MarshalAs(UnmanagedType.LPWStr)] string s);
+    void GetHotkey(out short k);
+    void SetHotkey(short k);
+    void GetShowCmd(out int c);
+    void SetShowCmd(int c);
+    void GetIconLocation([Out, MarshalAs(UnmanagedType.LPWStr)] StringBuilder s, int cch, out int i);
+    void SetIconLocation([MarshalAs(UnmanagedType.LPWStr)] string s, int i);
+    void SetRelativePath([MarshalAs(UnmanagedType.LPWStr)] string s, uint r);
+    void Resolve(IntPtr hwnd, uint flags);
+    void SetPath([MarshalAs(UnmanagedType.LPWStr)] string s);
+  }
+
+  [StructLayout(LayoutKind.Sequential, Pack = 4)] public struct PropertyKey { public Guid fmtid; public uint pid; }
+  [StructLayout(LayoutKind.Explicit)] public struct PropVariant { [FieldOffset(0)] public ushort vt; [FieldOffset(8)] public IntPtr p; }
+
+  [ComImport, InterfaceType(ComInterfaceType.InterfaceIsIUnknown), Guid("886D8EEB-8CF2-4446-8D02-CDBA1DBDCF99")]
+  interface IPropertyStore {
+    void GetCount(out uint c);
+    void GetAt(uint i, out PropertyKey k);
+    void GetValue(ref PropertyKey k, out PropVariant v);
+    void SetValue(ref PropertyKey k, ref PropVariant v);
+    void Commit();
+  }
+
+  public static class Maker {
+    public static void Create(string lnk, string aumid, string url) {
+      var link = (IShellLinkW)new CShellLink();
+      link.SetPath(Environment.ExpandEnvironmentVariables("%SystemRoot%\\explorer.exe"));
+      link.SetArguments(url);
+      link.SetDescription("Tether");
+      link.SetIconLocation(Environment.ExpandEnvironmentVariables("%SystemRoot%\\System32\\imageres.dll"), 228);
+      var store = (IPropertyStore)link;
+      var key = new PropertyKey { fmtid = new Guid("9F4C2855-9F79-4B39-A8D0-E1D42DE1D5F3"), pid = 5 };
+      var v = new PropVariant { vt = 31, p = Marshal.StringToCoTaskMemUni(aumid) };
+      store.SetValue(ref key, ref v);
+      store.Commit();
+      ((IPersistFile)link).Save(lnk, true);
+      Marshal.FreeCoTaskMem(v.p);
+    }
+  }
+}
+'@
+`;
 var Notifier = class {
   /** setting: 'all' | 'errors' | 'off' (config key `notifications`). */
   constructor({ setting = () => "all", consoleUrl = () => "", log = () => {
@@ -1992,7 +2487,12 @@ Also: ${events.slice(1, 4).map((e) => e.short ?? e.title).join("; ")}${more > 3
     const esc = (s) => s.replace(/[<>&"']/g, (c) => ({ "<": "&lt;", ">": "&gt;", "&": "&amp;", '"': "&quot;", "'": "&apos;" })[c]);
     const launch = url ? ` activationType="protocol" launch="${esc(url)}"` : "";
     const xml = `<toast${launch}><visual><binding template="ToastGeneric"><text>${esc(title)}</text><text>${esc(body)}</text></binding></visual></toast>`;
-    const register = this.registered ? "" : `$k='HKCU:\\Software\\Classes\\AppUserModelId\\${AUMID}'; if (-not (Test-Path $k)) { New-Item -Path $k -Force | Out-Null }; Set-ItemProperty -Path $k -Name DisplayName -Value 'Tether';`;
+    const consoleUrl = (this.consoleUrl() || "https://tether-b10cf.web.app").replace(/'/g, "''");
+    const register = this.registered ? "" : `$k='HKCU:\\Software\\Classes\\AppUserModelId\\${AUMID}'; if (-not (Test-Path $k)) { New-Item -Path $k -Force | Out-Null }; Set-ItemProperty -Path $k -Name DisplayName -Value 'Tether';
+$lnk = Join-Path $env:APPDATA 'Microsoft\\Windows\\Start Menu\\Programs\\Tether.lnk'
+if (-not (Test-Path $lnk)) { try {
+${SHORTCUT_SCRIPT}
+[TetherShortcut.Maker]::Create($lnk, '${AUMID}', '${consoleUrl}') } catch {} }`;
     this.registered = true;
     const script = `${register}
 [Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] | Out-Null
@@ -2004,9 +2504,90 @@ $x = New-Object Windows.Data.Xml.Dom.XmlDocument; $x.LoadXml('${xml.replace(/'/g
   }
 };
 
+// packages/client/src/feed.js
+var RETRY_MS = 5 * 60 * 1e3;
+var FeedListener = class {
+  /** onChange(seq) is called with the feed counter on every snapshot from the server. */
+  constructor({ api, log, onChange }) {
+    this.api = api;
+    this.log = log;
+    this.onChange = onChange;
+    this.live = false;
+    this.unsupported = false;
+    this.session = 0;
+  }
+  async start() {
+    if (this.unsupported || this.unsub || this.starting) return;
+    this.starting = true;
+    const session = ++this.session;
+    try {
+      const t = await this.api.call("POST", "/feed/token");
+      const [{ initializeApp }, A, F] = await Promise.all([import("firebase/app"), import("firebase/auth"), import("firebase/firestore")]);
+      if (session !== this.session) return;
+      this.app = initializeApp(t.firebase, `tether-feed-${session}-${Date.now()}`);
+      const auth = A.getAuth(this.app);
+      const db = F.getFirestore(this.app);
+      if (t.emulators?.auth) A.connectAuthEmulator(auth, `http://${t.emulators.auth}`, { disableWarnings: true });
+      if (t.emulators?.firestore) {
+        const [host, port] = t.emulators.firestore.split(":");
+        F.connectFirestoreEmulator(db, host, Number(port));
+      }
+      await A.signInWithCustomToken(auth, t.customToken);
+      if (session !== this.session) return this.dispose();
+      this.unsub = F.onSnapshot(F.doc(db, "feeds", t.uid), { includeMetadataChanges: true }, (snap) => {
+        const wasLive = this.live;
+        this.live = !snap.metadata.fromCache;
+        if (this.live && !wasLive) this.log("push channel connected");
+        if (this.live) this.onChange(snap.get("seq") ?? 0);
+      }, (e) => this.fail(e, session));
+    } catch (e) {
+      this.fail(e, session);
+    } finally {
+      this.starting = false;
+    }
+  }
+  fail(e, session) {
+    if (session !== this.session) return;
+    if (e instanceof ApiError && e.status === 404) {
+      this.unsupported = true;
+      this.stop();
+      return;
+    }
+    this.log(`push channel unavailable (${e.message}); polling until it reconnects`);
+    this.stop();
+    clearTimeout(this.retry);
+    this.retry = setTimeout(() => this.start(), RETRY_MS);
+    this.retry.unref?.();
+  }
+  stop() {
+    this.session++;
+    clearTimeout(this.retry);
+    this.unsub?.();
+    this.unsub = null;
+    if (this.live) this.log("push channel closed");
+    this.live = false;
+    this.dispose();
+  }
+  dispose() {
+    const app = this.app;
+    this.app = null;
+    if (app) import("firebase/app").then(({ deleteApp }) => deleteApp(app)).catch(() => {
+    });
+  }
+  /** After a login, logout or server change: start over (or stay off when signed out). */
+  restart() {
+    this.unsupported = false;
+    this.stop();
+    this.start();
+  }
+};
+
 // packages/client/src/daemon.js
 import { fileURLToPath } from "node:url";
 var REALTIME_TICK_SECONDS = 3;
+var IDLE_AFTER_MS = 10 * 60 * 1e3;
+var IDLE_MAX_SECONDS = 180;
+var PUSH_TICK_SECONDS = 15 * 60;
 var UPDATE_CHECK_MS = 24 * 60 * 60 * 1e3;
 async function runDaemon() {
   const home = tetherHome();
@@ -2044,23 +2625,54 @@ async function runDaemon() {
   let realtimeTimer = null;
   let stopping = false;
   let latest = null;
-  async function runTick(opts) {
+  let remoteAt = 0;
+  async function runTick({ remote } = {}) {
+    remote ??= !feed.live || engine.realtimeActive || Date.now() - remoteAt >= PUSH_TICK_SECONDS * 1e3;
+    if (remote) remoteAt = Date.now();
     try {
-      await engine.locked(() => engine.tick(opts));
+      await engine.locked(() => engine.tick({ remote }));
     } catch (e) {
       log(`tick failed: ${e.stack || e.message}`);
       notifier.notify({ kind: "error", level: "error", key: "tick-failed", cooldownMs: 3600 * 1e3, title: "Tether hit an error", body: `${e.message}. Run "tether log" for details.` });
     }
+    if (engine.gitPassDue) {
+      engine.gitPassDue = false;
+      gitPassSoon();
+    }
     refreshWatchers();
     scheduleGrace();
     schedule();
   }
+  let activeAt = Date.now();
+  let timerDue = 0;
+  function interval() {
+    const base = Math.max(MIN_TICK_SECONDS, config.get("tickSeconds"));
+    if (engine.realtimeActive) return Math.min(base, REALTIME_TICK_SECONDS);
+    const idle = Date.now() - Math.max(activeAt, engine.activityAt ?? 0);
+    if (idle < IDLE_AFTER_MS) return base;
+    return Math.max(base, Math.min(IDLE_MAX_SECONDS, base * 2 ** Math.floor(idle / IDLE_AFTER_MS)));
+  }
   function schedule() {
     clearTimeout(timer);
     if (stopping) return;
-    const seconds = engine.realtimeActive ? Math.min(config.get("tickSeconds"), REALTIME_TICK_SECONDS) : config.get("tickSeconds");
+    const seconds = interval();
+    timerDue = Date.now() + seconds * 1e3;
     timer = setTimeout(() => runTick(), seconds * 1e3);
   }
+  const feed = new FeedListener({
+    api,
+    log,
+    onChange: (seq) => {
+      if (stopping || engine.feed?.cursor === seq) return;
+      clearTimeout(timer);
+      timerDue = Date.now() + 300;
+      timer = setTimeout(() => runTick({ remote: true }), 300);
+    }
+  });
+  function markActive() {
+    activeAt = Date.now();
+    if (timer && timerDue - activeAt > interval() * 1e3) schedule();
+  }
   function realtimePass(delay = 1e3) {
     if (stopping || !engine.realtimeInstances().length) return;
     clearTimeout(realtimeTimer);
@@ -2101,10 +2713,29 @@ async function runDaemon() {
     if (engine.graceDue) quickPass(Math.max(50, engine.graceDue - Date.now() + 50));
   }
   const watchers = /* @__PURE__ */ new Map();
+  let gitTimer = null;
+  function gitPassSoon() {
+    clearTimeout(gitTimer);
+    gitTimer = setTimeout(async () => {
+      gitTimer = null;
+      try {
+        await engine.locked(async () => {
+          engine.busyCache = /* @__PURE__ */ new Map();
+          await engine.locateAll();
+          await engine.gitPass();
+          await engine.enforceLocal();
+        });
+      } catch (e) {
+        log(`git pass failed: ${e.message}`);
+      }
+    }, 600);
+  }
   function refreshWatchers() {
     const want = /* @__PURE__ */ new Map();
     for (const i of db.all()) {
-      if (i.mode === "orphaned" || i.detached) continue;
+      if (i.mode === "orphaned") continue;
+      if (i.gitDir && !want.has(i.gitDir)) want.set(i.gitDir, "git");
+      if (i.detached) continue;
       if (i.kind === "folder") want.set(i.path, true);
       else if (!i.folderInstanceId) want.set(path5.dirname(i.path), false);
     }
@@ -2114,10 +2745,11 @@ async function runDaemon() {
         watchers.delete(dir);
       }
     }
-    for (const [dir, recursive] of want) {
+    for (const [dir, kind] of want) {
       if (watchers.has(dir)) continue;
       try {
-        const w = fs8.watch(dir, { recursive, persistent: false }, () => {
+        const w = kind === "git" ? fs8.watch(dir, { persistent: false }, () => gitPassSoon()) : fs8.watch(dir, { recursive: kind, persistent: false }, () => {
+          markActive();
           quickPass(250);
           realtimePass();
         });
@@ -2162,7 +2794,7 @@ async function runDaemon() {
     return { state, url: `${config.consoleUrl.replace(/\/$/, "")}/cli-login?port=${port}&state=${state}` };
   }
   const L = (fn) => (params) => engine.locked(() => fn(params));
-  const soon = () => setTimeout(() => runTick(), 10);
+  const soon = () => setTimeout(() => runTick({ remote: true }), 10);
   const handlers = {
     ping: () => ({ pid: process.pid, version: VERSION, home, tracker: tracker.name, server: config.get("server") }),
     async status(p) {
@@ -2178,11 +2810,13 @@ async function runDaemon() {
       };
     },
     sync: async () => {
-      await runTick();
+      await runTick({ remote: true });
       return { offline: engine.offline };
     },
     async "login.password"({ email, password, signup }) {
       const user = await api.passwordLogin({ email, password, signup });
+      engine.feed = null;
+      feed.restart();
       soon();
       return user;
     },
@@ -2192,13 +2826,19 @@ async function runDaemon() {
       if (!p) throw new UserError("no login in progress");
       try {
         const user = await p;
+        engine.feed = null;
+        feed.restart();
         soon();
         return user;
       } finally {
         logins.delete(state);
       }
     },
-    logout: async () => api.logout(),
+    logout: async () => {
+      engine.feed = null;
+      feed.stop();
+      return api.logout();
+    },
     whoami: () => api.call("GET", "/me"),
     manage: L((p) => engine.manage(p)),
     add: L((p) => engine.add(p)),
@@ -2258,6 +2898,10 @@ async function runDaemon() {
     "config.get": ({ key }) => key ? { [key]: config.get(key) } : config.values,
     "config.set": ({ key, value }) => {
       config.set(key, value);
+      if (key === "server") {
+        engine.feed = null;
+        feed.restart();
+      }
       if (key === "tickSeconds") schedule();
       return { [key]: config.get(key) };
     },
@@ -2267,11 +2911,15 @@ async function runDaemon() {
       return { stopping: true };
     }
   };
+  const CHANGES_WATCHED = /* @__PURE__ */ new Set(["manage", "add", "pull", "edit", "unmanage", "git.mode", "resolve", "locate"]);
   async function handle(method, params) {
     const h = handlers[method];
     if (!h) throw new UserError(`unknown command ${method}`);
+    if (method !== "ping") markActive();
     try {
-      return await h(params);
+      const result = await h(params);
+      if (CHANGES_WATCHED.has(method)) refreshWatchers();
+      return result;
     } catch (e) {
       if (e instanceof ApiError || e instanceof UserError) throw e;
       if (e.name === "OfflineError") throw e;
@@ -2289,6 +2937,9 @@ async function runDaemon() {
     clearTimeout(quickTimer);
     clearTimeout(realtimeTimer);
     clearInterval(updateTimer);
+    clearInterval(repoTimer);
+    clearTimeout(gitTimer);
+    feed.stop();
     for (const w of watchers.values()) w.close();
     server.close();
     engine.locked(() => db.close()).finally(() => {
@@ -2299,10 +2950,16 @@ async function runDaemon() {
   }
   process.on("SIGINT", () => shutdown(0));
   process.on("SIGTERM", () => shutdown(0));
-  await engine.locked(() => engine.syncGitHooks()).catch((e) => log(`git hooks: ${e.message}`));
+  await engine.locked(() => {
+    engine.cleanupLegacyHooks();
+    engine.detectNewRepos();
+  }).catch((e) => log(`git setup: ${e.message}`));
+  const repoTimer = setInterval(() => engine.locked(() => engine.detectNewRepos()).catch(() => {
+  }), 60 * 60 * 1e3);
   const updateTimer = setInterval(checkForUpdate, UPDATE_CHECK_MS);
   setTimeout(checkForUpdate, 5e3);
   await runTick();
+  feed.start();
 }
 export {
   VERSION,