tether-sync 0.1.0 → 0.2.0

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

@@ -1,13 +1,21 @@
 import {
+  GIT_MODES,
+  VERSION,
   files,
+  findRepo,
+  gitBusy,
+  installHooks,
   ipcEndpoint,
+  isNewer,
   isWindows,
+  latestVersion,
   listen,
+  removeHooks,
   tetherHome
-} from "./chunk-MGMU33LE.js";
+} from "./chunk-NDKBAHAG.js";
 
 // packages/client/src/daemon.js
-import fs7 from "node:fs";
+import fs8 from "node:fs";
 import path5 from "node:path";
 import http from "node:http";
 import crypto4 from "node:crypto";
@@ -21,7 +29,9 @@ var DEFAULTS = {
   // defaults to the server URL
   tickSeconds: 30,
   graceMs: 2e3,
-  scanRoots: [os.homedir()]
+  scanRoots: [os.homedir()],
+  notifications: "all"
+  // all | errors | off
 };
 var NUMERIC = /* @__PURE__ */ new Set(["tickSeconds", "graceMs"]);
 var Config = class {
@@ -43,6 +53,7 @@ var Config = class {
       value = Number(value);
       if (!Number.isFinite(value) || value <= 0) throw new Error(`${key} must be a positive number`);
     }
+    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);
     this.values[key] = value;
     fs.writeFileSync(this.file, JSON.stringify(this.values, null, 2));
@@ -93,11 +104,20 @@ var COLUMNS = {
   needsRestore: "INTEGER DEFAULT 0",
   // write a fresh copy at the expected path on the next tick
   orphanReason: "TEXT",
+  realtime: "INTEGER DEFAULT 0",
+  // this client holds a realtime session and pushes every save
+  remoteRealtime: "TEXT",
+  // JSON { email, since } when someone else edits this file in realtime
+  gitMode: "TEXT",
+  // inside a git repo: keep (Tether reverts git's changes) | follow (git's changes are published)
+  gitRoot: "TEXT",
+  gitDir: "TEXT",
+  gitHooks: "TEXT",
   lastError: "TEXT",
   createdAt: "REAL",
   updatedAt: "REAL"
 };
-var BOOL = /* @__PURE__ */ new Set(["hasBom", "exec", "canDelete", "detached", "needsRestore"]);
+var BOOL = /* @__PURE__ */ new Set(["realtime", "hasBom", "exec", "canDelete", "detached", "needsRestore"]);
 var LocalDb = class {
   constructor(file) {
     this.db = new DatabaseSync(file);
@@ -753,13 +773,19 @@ var UserError = class extends Error {
 var ACTIVE = (i) => i.mode !== "orphaned";
 var Engine = class {
   constructor({ db, api, cache, tracker, config, log = () => {
-  } }) {
+  }, notify = () => {
+  }, home = null, cliPath = null }) {
     this.db = db;
     this.api = api;
     this.cache = cache;
     this.tracker = tracker;
     this.config = config;
     this.log = log;
+    this.notify = notify;
+    this.home = home;
+    this.cliPath = cliPath;
+    this.gitState = /* @__PURE__ */ new Map();
+    this.busyCache = null;
     this.offline = null;
     this.lastTick = null;
     this.graceDue = null;
@@ -804,11 +830,212 @@ var Engine = class {
   }
   // ---------- tick ----------
   async tick({ remote = true } = {}) {
+    this.busyCache = /* @__PURE__ */ new Map();
     await this.locateAll();
-    if (remote) await this.checkRemote();
+    if (remote) await this.gitTransitions();
+    if (remote) {
+      await this.checkRemote();
+      await this.syncRealtime();
+    }
     await this.enforceLocal();
     this.lastTick = Date.now();
   }
+  // ---------- git integration ----------
+  isGitBusy(inst) {
+    if (!inst.gitDir) return false;
+    this.busyCache ??= /* @__PURE__ */ new Map();
+    if (!this.busyCache.has(inst.gitDir)) this.busyCache.set(inst.gitDir, gitBusy(inst.gitDir));
+    return !!this.busyCache.get(inst.gitDir);
+  }
+  /** 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");
+    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();
+  }
+  /** `tether git <path> [--mode]`: show or change the git mode of managed files. */
+  gitMode({ path: p, mode }) {
+    const ts = this.targets(p);
+    const folders = new Set(ts.filter((i) => i.kind === "folder").map((i) => i.instanceId));
+    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]);
+  }
+  /** 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);
+    }
+  }
+  /**
+   * 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`.
+   */
+  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)`);
+      }
+    }
+    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 {
+      }
+    }
+    if (!changed.length) return { published: 0 };
+    let results;
+    try {
+      ({ results } = await this.api.call("POST", "/sync/check", { items: changed.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 };
+    }
+    let published = 0;
+    for (const [k, { inst, local }] of changed.entries()) {
+      const r = results[k];
+      const name = path4.basename(inst.path);
+      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" });
+        continue;
+      }
+      const conflict = () => {
+        this.db.update(inst.instanceId, { mode: "editing", lastError: "conflict: git changed this file and Tether has a newer version; run `tether done` to resolve" });
+        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 });
+      };
+      if (r.status === "changed") {
+        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}`);
+        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) {
+          this.db.update(inst.instanceId, { mode: "editing", lastError: `could not publish git's version: ${e.message}` });
+          this.notify({ kind: "push-failed", level: "error", title: "Push failed", body: `${name}: ${e.message}. Git's version is kept in editing mode.`, short: name, artifactId: inst.artifactId });
+        } else throw e;
+      }
+    }
+    return { published };
+  }
+  // ---------- realtime editing ----------
+  /** Files this client is editing live (every save is pushed). */
+  realtimeInstances() {
+    return this.db.all().filter((i) => i.realtime && i.mode === "editing" && i.kind === "file");
+  }
+  /** True while anything held here is being edited live, so the daemon checks more often. */
+  get realtimeActive() {
+    return this.db.all().some((i) => i.realtime && i.mode === "editing" || i.remoteRealtime && i.mode !== "orphaned");
+  }
+  async releaseRealtime(inst) {
+    this.db.update(inst.instanceId, { realtime: false });
+    await this.api.call("POST", `/artifacts/${inst.artifactId}/realtime`, { action: "stop" }).catch(() => {
+    });
+  }
+  /**
+   * Pushes live edits: renews the session, applies incoming versions when there is no local
+   * change, pushes local changes when the server has not moved, and pauses on a conflict.
+   */
+  async syncRealtime() {
+    const rts = this.realtimeInstances().filter((i) => !i.detached);
+    if (!rts.length) return;
+    let results;
+    try {
+      ({ results } = await this.api.call("POST", "/sync/check", { items: rts.map((i) => ({ artifactId: i.artifactId, version: i.baseVersion, realtime: true })) }));
+    } catch (e) {
+      if (e instanceof OfflineError) return this.offline = e.message;
+      throw e;
+    }
+    for (const [k, inst] of rts.entries()) {
+      const r = results[k];
+      const cur = this.db.get(inst.instanceId);
+      if (!cur || cur.mode !== "editing" || !cur.realtime) continue;
+      if (r.status === "gone" || r.state?.deleted || r.folderDeleted) {
+        this.orphan(cur, r.reason ?? "deleted");
+        continue;
+      }
+      if (!r.realtime?.mine) {
+        const why = r.role === "viewer" ? "you are no longer an editor" : r.realtime ? `taken over by ${r.realtime.email}` : "it ended";
+        this.db.update(cur.instanceId, { realtime: false, lastError: r.role === "viewer" ? null : `realtime session lost (${why}); still editing, run \`tether done\` to push` });
+        this.log(`${cur.path}: realtime session lost (${why})`);
+        this.notify({ kind: "realtime-lost", level: "warn", title: "Live editing stopped", body: `${path4.basename(cur.path)}: your realtime session ${why}. Your changes are kept; run "tether done" to push them.`, short: path4.basename(cur.path), artifactId: cur.artifactId });
+        continue;
+      }
+      try {
+        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 }]);
+            this.applyIncoming(cur, r.state);
+          } else {
+            if (!cur.lastError?.startsWith("conflict")) {
+              this.log(`${cur.path}: someone else pushed while you were editing live; live pushing paused, run \`tether done\` to resolve`);
+              this.notify({ kind: "conflict", level: "warn", title: "Merge conflict", body: `${path4.basename(cur.path)}: someone else pushed while you were editing live. Live pushing is paused; run "tether done" to choose what to keep.`, short: path4.basename(cur.path), artifactId: cur.artifactId });
+            }
+            this.db.update(cur.instanceId, { lastError: "conflict: the server changed; run `tether done` to resolve" });
+          }
+          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);
+        try {
+          const c = await this.api.call("POST", `/artifacts/${cur.artifactId}/commit`, { baseVersion: cur.baseVersion, change: { blob: local.hash, size: local.canonical.length } });
+          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)`);
+        } 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" });
+        }
+      } catch (e) {
+        if (!(e instanceof LockedError)) throw e;
+        this.db.update(cur.instanceId, { lastError: e.message });
+      }
+    }
+  }
   /** Refresh path and file ID of every tracked instance (DESIGN §5). */
   async locateAll() {
     const graceMs = this.config.get("graceMs");
@@ -871,7 +1098,10 @@ var Engine = class {
       this.log(`${inst.path}: folder deleted locally; no longer managed here`);
       return;
     }
-    if (inst.mode === "editing") {
+    if (inst.gitMode === "follow" && inst.mode === "normal" && !inst.folderInstanceId) {
+      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") {
       this.db.update(inst.instanceId, { detached: true, missingSince: null });
       this.log(`${inst.path}: deleted while editing; resolve with \`tether done\``);
     } else if (inst.folderInstanceId) {
@@ -885,7 +1115,9 @@ 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 });
-    this.log(`${inst.path}: ${reason === "revoked" ? "access revoked" : reason === "deleted" ? "deleted on the server" : "removed from the server"}; file kept, no longer tracked`);
+    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) });
   }
   /** One batched call for all instances (DESIGN §6.1 step 2). */
   async checkRemote() {
@@ -901,6 +1133,7 @@ var Engine = class {
     } catch (e) {
       if (e instanceof OfflineError || e instanceof ApiError && e.status === 401) {
         this.offline = e.message;
+        if (e instanceof ApiError) this.notify({ kind: "auth", level: "error", key: "auth", cooldownMs: 6 * 3600 * 1e3, title: "Tether needs you to sign in", body: `${e.message}. Until then nothing syncs.` });
         return;
       }
       throw e;
@@ -913,10 +1146,21 @@ var Engine = class {
       if (!cur || cur.mode === "orphaned") return;
       if (r.status === "gone") return this.orphan(cur, r.reason);
       if (r.folderDeleted || r.state?.deleted) return this.orphan(cur, "deleted");
-      const patch = { role: r.role, canDelete: r.canDelete, remoteVersion: r.version };
+      const patch = {
+        role: r.role,
+        canDelete: r.canDelete,
+        remoteVersion: r.version,
+        remoteRealtime: r.realtime && !r.realtime.mine ? JSON.stringify({ email: r.realtime.email, since: r.realtime.since }) : null
+      };
       if (cur.role && cur.role !== "viewer" && r.role === "viewer" && cur.mode === "editing") {
         patch.mode = "normal";
+        patch.realtime = false;
         this.log(`${cur.path}: you are now a viewer; editing ended and local changes will be reverted`);
+        this.notify({ kind: "demoted", level: "warn", title: "You are now a viewer", body: `${path4.basename(cur.path)}: your editor access was removed, so your unpushed changes are being reverted.`, short: path4.basename(cur.path), artifactId: cur.artifactId });
+      }
+      if (cur.gitMode === "follow" && r.role === "viewer") {
+        patch.gitMode = "keep";
+        this.notify({ kind: "demoted", level: "warn", title: "Git follow mode turned off", body: `${path4.basename(cur.path)}: you are no longer an editor, so git's changes to it will be reverted.`, short: path4.basename(cur.path), artifactId: cur.artifactId });
       }
       const now = this.db.update(cur.instanceId, patch);
       if (r.status !== "changed") return;
@@ -938,7 +1182,7 @@ var Engine = class {
       if (e instanceof OfflineError) return this.offline = e.message;
       throw e;
     }
-    for (const { inst, state } of incoming) this.applyIncoming(inst, state);
+    for (const { inst, state } of incoming) if (!this.isGitBusy(inst)) this.applyIncoming(inst, state);
     for (const { folder, child } of newChildren) {
       this.db.insert({
         instanceId: newInstanceId(),
@@ -976,16 +1220,32 @@ var Engine = class {
         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 };
-      if (state.blob !== inst.baseHash || !this.matchesBase(inst, p)) {
+      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}`);
+        this.log(`${p}: updated to version ${state.version}${localEdit ? " (local change replaced)" : ""}`);
+        if (localEdit) {
+          const name = path4.basename(p);
+          this.notify({
+            kind: "revert",
+            level: "info",
+            short: name,
+            artifactId: inst.artifactId,
+            title: inst.gitMode === "keep" ? "Tether undid a git change" : "Tether undid your change",
+            body: `${name} is managed by Tether, so your local change was replaced with the shared version (v${state.version}). Run "tether edit ${name}" to change it.`
+          });
+        }
       }
       this.db.update(inst.instanceId, patch);
     } catch (e) {
       if (!(e instanceof LockedError)) throw e;
-      this.db.update(inst.instanceId, { lastError: e.message });
+      this.lockedNotice(inst, e);
     }
   }
+  lockedNotice(inst, e) {
+    if (!inst.lastError) this.notify({ kind: "locked", level: "warn", key: `locked:${inst.instanceId}`, cooldownMs: 3600 * 1e3, title: "File in use", body: `${path4.basename(inst.path)} is open in another program, so Tether cannot update it yet. It will retry automatically.`, short: path4.basename(inst.path) });
+    this.db.update(inst.instanceId, { lastError: e.message });
+  }
   /** If `to` is occupied by something that isn't this instance, move it aside (keep both). */
   makeRoom(to, inst) {
     const st = statOrNull(to);
@@ -1014,6 +1274,7 @@ var Engine = class {
     }
     for (const inst of this.db.all()) {
       if (inst.mode !== "normal" || inst.kind !== "file" || inst.detached) continue;
+      if (this.isGitBusy(inst)) continue;
       try {
         if (inst.needsRestore) {
           if (this.cache.has(inst.baseHash)) this.restore(inst);
@@ -1034,9 +1295,18 @@ var Engine = class {
         if (!this.cache.has(cur.baseHash)) 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";
+        this.notify({
+          kind: "revert",
+          level: "info",
+          short: path4.basename(cur.path),
+          artifactId: cur.artifactId,
+          title: byGit ? "Tether undid a git change" : "Tether undid your change",
+          body: `${path4.basename(cur.path)} is managed by Tether, so it was put back to the shared version. Run "tether edit ${path4.basename(cur.path)}" to change it${byGit ? ', or "tether git <path> --mode follow" to accept git updates' : ""}.`
+        });
       } catch (e) {
         if (!(e instanceof LockedError)) throw e;
-        this.db.update(inst.instanceId, { lastError: e.message });
+        this.lockedNotice(inst, e);
       }
     }
   }
@@ -1094,7 +1364,13 @@ var Engine = class {
     return { abs, bytes: canonical, sha256: sha256(canonical), size: canonical.length, eol: eolMode, exec: process.platform !== "win32" && !!(st.mode & 73), stat: st };
   }
   /** `tether manage <path> --repo <repo>`: upload; the caller becomes the owner. */
-  async manage({ path: target, repo: repoRef, eol }) {
+  /** `tether manage`, then apply the git mode chosen for a path inside a git repository. */
+  async manage({ gitMode, ...opts }) {
+    const r = await this.manageCore(opts);
+    if (gitMode) this.applyGitMode(this.instanceAt(r.path), gitMode);
+    return r;
+  }
+  async manageCore({ path: target, repo: repoRef, eol }) {
     const abs = canonicalPath(path4.resolve(target));
     const st = statOrNull(abs);
     if (!st) throw new UserError(`${abs} does not exist`);
@@ -1234,11 +1510,25 @@ var Engine = class {
     return { artifactId: child.artifactId, relPath: rel, folder: folder.path };
   }
   /** `tether pull <shareId> [dest]`. Never overwrites existing user files. */
-  async pull({ shareId, dest, cwd }) {
+  /** `tether pull`; with peek, only report where it would go and the caller's role. */
+  async pull({ gitMode, peek, ...opts }) {
+    if (peek) {
+      const r2 = await this.api.call("POST", "/pull", { shareId: opts.shareId, peek: true });
+      return { role: r2.role, kind: r2.artifact.kind, path: this.pullTarget(r2.artifact, opts) };
+    }
+    const r = await this.pullCore(opts, gitMode);
+    if (gitMode) this.applyGitMode(this.instanceAt(r.path), gitMode);
+    return r;
+  }
+  pullTarget(a, { dest, cwd }) {
+    const target = path4.resolve(cwd, dest ?? a.name);
+    return dest && statOrNull(target)?.isDirectory() && a.kind === "file" ? path4.join(target, a.name) : target;
+  }
+  async pullCore({ shareId, dest, cwd }, gitMode) {
     const r = await this.api.call("POST", "/pull", { shareId });
     const a = r.artifact;
-    let target = path4.resolve(cwd, dest ?? a.name);
-    if (dest && statOrNull(target)?.isDirectory() && a.kind === "file") target = path4.join(target, a.name);
+    if (gitMode === "follow" && r.role === "viewer") throw new UserError("git follow mode needs editor access; you are a viewer (use --git keep)");
+    const target = this.pullTarget(a, { dest, cwd });
     if (this.instanceAt(target)) throw new UserError(`${target} is already a managed copy`);
     const base = { repoId: a.repoId, role: r.role, canDelete: r.canDelete };
     if (a.kind === "file") {
@@ -1331,13 +1621,54 @@ var Engine = class {
     }
     return changed;
   }
-  edit({ path: p }) {
+  /**
+   * `tether edit [--realtime]`. Realtime claims a live session per file (editors only, one
+   * holder per file). A plain edit warns about files someone else is editing live.
+   */
+  async edit({ path: p, realtime = false }) {
     const ts = this.targets(p);
     const unmanaged = ts.filter((i) => i.mode === "unmanaged" && !i.detached);
     if (unmanaged.length === ts.length) throw new UserError("these files are unmanaged; use `tether track` first");
-    return { changed: this.setMode(p, "editing", ["normal"]) };
+    const files2 = ts.filter((i) => i.kind === "file" && ["normal", "editing"].includes(i.mode) && !i.detached);
+    if (realtime) {
+      if (!files2.length) throw new UserError("nothing here to edit");
+      const viewerOf = files2.find((i) => i.role === "viewer");
+      if (viewerOf) throw new UserError(`realtime editing needs editor access; you are a viewer of ${viewerOf.path}`);
+      const claimed = [];
+      for (const f of files2) {
+        try {
+          await this.api.call("POST", `/artifacts/${f.artifactId}/realtime`, { action: "start" });
+          claimed.push(f);
+        } catch (e) {
+          for (const c of claimed) await this.releaseRealtime(c);
+          if (e instanceof ApiError && e.status === 409 && e.body?.realtime) {
+            const s = e.body.realtime;
+            throw new UserError(`${f.path} is already being edited in realtime by ${s.email} (since ${new Date(s.since).toLocaleTimeString()}).
+You can still run \`tether edit\` without --realtime, but expect merge conflicts.`);
+          }
+          throw e;
+        }
+      }
+      this.setMode(p, "editing", ["normal", "editing"]);
+      for (const f of files2) this.db.update(f.instanceId, { mode: "editing", realtime: true, lastError: null });
+      return { changed: files2.map((f) => f.path), realtime: true };
+    }
+    const changed = this.setMode(p, "editing", ["normal"]);
+    const warnings = [];
+    if (files2.length) {
+      try {
+        const { results } = await this.api.call("POST", "/sync/check", { items: files2.map((i) => ({ artifactId: i.artifactId, version: i.baseVersion })) });
+        results.forEach((r, k) => {
+          if (r.realtime && !r.realtime.mine) warnings.push({ path: files2[k].path, email: r.realtime.email, since: r.realtime.since });
+        });
+      } catch (e) {
+        if (!(e instanceof OfflineError)) throw e;
+      }
+    }
+    return { changed, warnings };
   }
-  unmanage({ path: p }) {
+  async unmanage({ path: p }) {
+    for (const i of this.targets(p).filter((x) => x.realtime)) await this.releaseRealtime(i);
     return { changed: this.setMode(p, "unmanaged", ["normal", "editing"]) };
   }
   /**
@@ -1420,6 +1751,7 @@ var Engine = class {
     for (const f of this.targets(p).filter((i) => i.kind === "folder" && i.mode === from)) {
       if (!this.db.childrenOf(f.instanceId).some((c) => c.mode === from && !c.detached)) this.db.update(f.instanceId, { mode: "normal" });
     }
+    for (const i of this.db.all().filter((x) => x.realtime && x.mode !== "editing")) await this.releaseRealtime(i);
     await this.tick();
     return { results: out };
   }
@@ -1544,6 +1876,9 @@ var Engine = class {
         }
       }
       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.remoteRealtime && i.mode !== "orphaned") flags.push(`realtime edits by ${JSON.parse(i.remoteRealtime).email}`);
       return {
         instanceId: i.instanceId,
         artifactId: i.artifactId,
@@ -1592,15 +1927,94 @@ var Engine = class {
   }
 };
 
+// packages/client/src/notifier.js
+import fs7 from "node:fs";
+import { spawn } from "node:child_process";
+var AUMID = "Tether.Sync";
+var FLUSH_MS = 3e3;
+var LEVELS = { info: 0, warn: 1, error: 2 };
+var Notifier = class {
+  /** setting: 'all' | 'errors' | 'off' (config key `notifications`). */
+  constructor({ setting = () => "all", consoleUrl = () => "", log = () => {
+  } } = {}) {
+    this.setting = setting;
+    this.consoleUrl = consoleUrl;
+    this.log = log;
+    this.pending = /* @__PURE__ */ new Map();
+    this.cooldown = /* @__PURE__ */ new Map();
+    this.timer = null;
+    this.registered = false;
+  }
+  /**
+   * event: { kind, level: 'info'|'warn'|'error', title, body, path?, artifactId?, key?, cooldownMs? }
+   * Events sharing `key` are suppressed for cooldownMs (default: no cooldown).
+   */
+  notify(event) {
+    const s = this.setting();
+    if (s === "off" || s === "errors" && LEVELS[event.level] < LEVELS.warn) return;
+    if (event.key) {
+      if ((this.cooldown.get(event.key) ?? 0) > Date.now()) return;
+      if (event.cooldownMs) this.cooldown.set(event.key, Date.now() + event.cooldownMs);
+    }
+    if (!this.pending.has(event.kind)) this.pending.set(event.kind, []);
+    this.pending.get(event.kind).push(event);
+    this.timer ??= setTimeout(() => this.flush(), FLUSH_MS);
+  }
+  flush() {
+    this.timer = null;
+    for (const events of this.pending.values()) {
+      const first = events[0];
+      const more = events.length - 1;
+      const title = more ? `${first.title} (+${more} more)` : first.title;
+      const body = more ? `${first.body}
+Also: ${events.slice(1, 4).map((e) => e.short ?? e.title).join("; ")}${more > 3 ? "\u2026" : ""}` : first.body;
+      const base = this.consoleUrl().replace(/\/$/, "");
+      const url = base ? first.artifactId && !more ? `${base}/artifacts/${first.artifactId}` : base : "";
+      this.show({ title, body, url, level: first.level });
+    }
+    this.pending.clear();
+  }
+  show(n) {
+    this.log(`notify [${n.level}] ${n.title}: ${n.body.replace(/\n/g, " ")}`);
+    if (process.env.TETHER_NOTIFY_LOG) {
+      fs7.appendFileSync(process.env.TETHER_NOTIFY_LOG, JSON.stringify(n) + "\n");
+      return;
+    }
+    try {
+      if (isWindows) this.toast(n);
+      else spawn("notify-send", ["--app-name=Tether", n.level === "info" ? "--urgency=low" : "--urgency=normal", n.title, n.body], { stdio: "ignore" }).on("error", () => {
+      });
+    } catch (e) {
+      this.log(`notification failed: ${e.message}`);
+    }
+  }
+  toast({ title, body, url }) {
+    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';`;
+    this.registered = true;
+    const script = `${register}
+[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] | Out-Null
+[Windows.Data.Xml.Dom.XmlDocument, Windows.Data.Xml.Dom.XmlDocument, ContentType = WindowsRuntime] | Out-Null
+$x = New-Object Windows.Data.Xml.Dom.XmlDocument; $x.LoadXml('${xml.replace(/'/g, "''")}')
+[Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier('${AUMID}').Show((New-Object Windows.UI.Notifications.ToastNotification $x))`;
+    const child = spawn("powershell.exe", ["-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-EncodedCommand", Buffer.from(script, "utf16le").toString("base64")], { stdio: "ignore", windowsHide: true });
+    child.on("error", (e) => this.log(`notification failed: ${e.message}`));
+  }
+};
+
 // packages/client/src/daemon.js
-var VERSION = "0.1.0";
+import { fileURLToPath } from "node:url";
+var REALTIME_TICK_SECONDS = 3;
+var UPDATE_CHECK_MS = 24 * 60 * 60 * 1e3;
 async function runDaemon() {
   const home = tetherHome();
-  fs7.mkdirSync(home, { recursive: true });
+  fs8.mkdirSync(home, { recursive: true });
   process.chdir(home);
   const f = files(home);
   const recent = [];
-  const logStream = fs7.createWriteStream(f.log, { flags: "a" });
+  const logStream = fs8.createWriteStream(f.log, { flags: "a" });
   const log = (msg) => {
     const line = `${(/* @__PURE__ */ new Date()).toISOString()} ${msg}`;
     recent.push(line);
@@ -1613,26 +2027,62 @@ async function runDaemon() {
   const api = new Api({ config, credentials });
   const cache = new BlobCache(f.blobs);
   const tracker = await createTracker(config);
-  const engine = new Engine({ db, api, cache, tracker, config, log });
+  const notifier = new Notifier({ setting: () => config.get("notifications"), consoleUrl: () => config.consoleUrl, log });
+  const engine = new Engine({
+    db,
+    api,
+    cache,
+    tracker,
+    config,
+    log,
+    home,
+    notify: (e) => notifier.notify(e),
+    cliPath: fileURLToPath(new URL("../bin/tether.js", import.meta.url))
+  });
   let timer = null;
   let quickTimer = null;
+  let realtimeTimer = null;
   let stopping = false;
+  let latest = null;
   async function runTick(opts) {
     try {
       await engine.locked(() => engine.tick(opts));
     } 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.` });
     }
     refreshWatchers();
     scheduleGrace();
+    schedule();
   }
   function schedule() {
     clearTimeout(timer);
     if (stopping) return;
-    timer = setTimeout(async () => {
-      await runTick();
-      schedule();
-    }, config.get("tickSeconds") * 1e3);
+    const seconds = engine.realtimeActive ? Math.min(config.get("tickSeconds"), REALTIME_TICK_SECONDS) : config.get("tickSeconds");
+    timer = setTimeout(() => runTick(), seconds * 1e3);
+  }
+  function realtimePass(delay = 1e3) {
+    if (stopping || !engine.realtimeInstances().length) return;
+    clearTimeout(realtimeTimer);
+    realtimeTimer = setTimeout(async () => {
+      realtimeTimer = null;
+      try {
+        await engine.locked(async () => {
+          await engine.locateAll();
+          await engine.syncRealtime();
+        });
+      } catch (e) {
+        log(`realtime push failed: ${e.message}`);
+      }
+    }, delay);
+  }
+  let notifiedVersion = null;
+  async function checkForUpdate() {
+    latest = await latestVersion() ?? latest;
+    if (isNewer(latest, VERSION) && notifiedVersion !== latest) {
+      notifiedVersion = latest;
+      notifier.notify({ kind: "update", level: "info", title: "Tether update available", body: `Version ${latest} is available (you have ${VERSION}). Run "tether update".` });
+    }
   }
   function quickPass(delay) {
     if (quickTimer || stopping) return;
@@ -1667,7 +2117,10 @@ async function runDaemon() {
     for (const [dir, recursive] of want) {
       if (watchers.has(dir)) continue;
       try {
-        const w = fs7.watch(dir, { recursive, persistent: false }, () => quickPass(250));
+        const w = fs8.watch(dir, { recursive, persistent: false }, () => {
+          quickPass(250);
+          realtimePass();
+        });
         w.on("error", () => {
           w.close();
           watchers.delete(dir);
@@ -1714,7 +2167,15 @@ async function runDaemon() {
     ping: () => ({ pid: process.pid, version: VERSION, home, tracker: tracker.name, server: config.get("server") }),
     async status(p) {
       const creds = await credentials.load();
-      return { user: creds?.user ?? null, server: config.get("server"), offline: engine.offline, lastTick: engine.lastTick, instances: await L((x) => engine.status(x))(p) };
+      return {
+        user: creds?.user ?? null,
+        server: config.get("server"),
+        offline: engine.offline,
+        lastTick: engine.lastTick,
+        version: VERSION,
+        latest,
+        instances: await L((x) => engine.status(x))(p)
+      };
     },
     sync: async () => {
       await runTick();
@@ -1742,8 +2203,18 @@ async function runDaemon() {
     manage: L((p) => engine.manage(p)),
     add: L((p) => engine.add(p)),
     pull: L((p) => engine.pull(p)),
-    edit: L((p) => engine.edit(p)),
+    edit: async (p) => {
+      const r = await L((x) => engine.edit(x))(p);
+      schedule();
+      return r;
+    },
     unmanage: L((p) => engine.unmanage(p)),
+    "git.mode": L((p) => engine.gitMode(p)),
+    // Called by git hooks: answer at once so git is not held up; reconcile in the background.
+    "git.sync": ({ repo }) => {
+      engine.locked(() => engine.gitReconcile(path5.resolve(repo))).catch((e) => log(`git sync failed: ${e.message}`));
+      return { queued: true };
+    },
     plan: L((p) => engine.plan(p)),
     resolve: L((p) => engine.resolve(p)),
     diff: L((p) => engine.diff(p)),
@@ -1809,25 +2280,29 @@ async function runDaemon() {
     }
   }
   const server = await listen(ipcEndpoint(home), handle);
-  fs7.writeFileSync(f.pid, String(process.pid));
+  fs8.writeFileSync(f.pid, String(process.pid));
   log(`tetherd ${VERSION} started (pid ${process.pid}, tracker ${tracker.name}, server ${config.get("server")})`);
   function shutdown(code) {
     if (stopping) return;
     stopping = true;
     clearTimeout(timer);
     clearTimeout(quickTimer);
+    clearTimeout(realtimeTimer);
+    clearInterval(updateTimer);
     for (const w of watchers.values()) w.close();
     server.close();
     engine.locked(() => db.close()).finally(() => {
-      fs7.rmSync(f.pid, { force: true });
+      fs8.rmSync(f.pid, { force: true });
       log("tetherd stopped");
       logStream.end(() => process.exit(code));
     });
   }
   process.on("SIGINT", () => shutdown(0));
   process.on("SIGTERM", () => shutdown(0));
+  await engine.locked(() => engine.syncGitHooks()).catch((e) => log(`git hooks: ${e.message}`));
+  const updateTimer = setInterval(checkForUpdate, UPDATE_CHECK_MS);
+  setTimeout(checkForUpdate, 5e3);
   await runTick();
-  schedule();
 }
 export {
   VERSION,