midsummer-sol 0.1.1 → 0.1.3

package/sol.js

@@ -3,9 +3,9 @@
 
 // src/bin/sol.ts
 import { execFileSync as execFileSync2 } from "child_process";
-import { existsSync as existsSync9, mkdirSync as mkdirSync7, mkdtempSync, readdirSync as readdirSync7, readFileSync as readFileSync9, rmSync, unlinkSync as unlinkSync6, watch, writeFileSync as writeFileSync9 } from "fs";
+import { existsSync as existsSync10, mkdirSync as mkdirSync7, mkdtempSync, readdirSync as readdirSync7, readFileSync as readFileSync9, rmSync, unlinkSync as unlinkSync6, watch, writeFileSync as writeFileSync9 } from "fs";
 import { homedir, hostname, platform as platform2, tmpdir } from "os";
-import { basename, dirname as dirname5, join as join9, resolve as resolve3, sep as sep3 } from "path";
+import { basename, dirname as dirname5, join as join10, resolve as resolve4, sep as sep3 } from "path";
 
 // src/attest.ts
 function canonicalOp(op) {
@@ -615,6 +615,49 @@ class FileStore {
   }
 }
 
+class FileOpLog {
+  opsFile;
+  headFile;
+  constructor(solDir) {
+    this.opsFile = join(solDir, "ops.jsonl");
+    this.headFile = join(solDir, "HEAD");
+  }
+  readHead() {
+    return existsSync(this.headFile) ? JSON.parse(readFileSync(this.headFile, "utf8")) : { seq: 0 };
+  }
+  async head() {
+    return this.readHead().head;
+  }
+  async seq() {
+    return this.readHead().seq ?? 0;
+  }
+  async logTip() {
+    return this.readHead().logTip;
+  }
+  async append(entry) {
+    const chained = chainOp(this.readHead().logTip, entry);
+    appendFileSync(this.opsFile, JSON.stringify(chained) + `
+`);
+    writeFileSync(this.headFile, JSON.stringify({ head: chained.rootAfter, seq: chained.seq, logTip: chained.entryHash }));
+  }
+  async history(opts) {
+    if (!existsSync(this.opsFile))
+      return [];
+    const all = [];
+    for (const l of readFileSync(this.opsFile, "utf8").split(`
+`)) {
+      if (!l)
+        continue;
+      try {
+        all.push(JSON.parse(l));
+      } catch {
+        break;
+      }
+    }
+    return pageOps(all, opts);
+  }
+}
+
 // src/crypto.ts
 import { createCipheriv, createDecipheriv, createPublicKey, diffieHellman, generateKeyPairSync, hkdfSync, randomBytes, timingSafeEqual } from "node:crypto";
 var UNREADABLE = "<<unreadable>>";
@@ -785,7 +828,7 @@ class FileStore2 {
   }
 }
 
-class FileOpLog {
+class FileOpLog2 {
   opsFile;
   headFile;
   constructor(solDir) {
@@ -1003,7 +1046,7 @@ function setHead(fdir, head) {
 }
 async function importGitRepo(gitPath, fdir) {
   const store = new FileStore2(fdir);
-  const log = new FileOpLog(fdir);
+  const log = new FileOpLog2(fdir);
   const empty = await emptyRoot2(store);
   const commitList = git(gitPath, "rev-list", "--reverse", "--topo-order", "--all").toString().trim().split(`
 `).filter(Boolean);
@@ -1394,7 +1437,7 @@ function die(msg) {
 function open() {
   if (!existsSync6(solDir2))
     die("not a sol repo — run `sol init` first");
-  return { repo: new AsyncRepo(new FileStore2(solDir2), new FileOpLog(solDir2), actor2), log: new FileOpLog(solDir2) };
+  return { repo: new AsyncRepo(new FileStore2(solDir2), new FileOpLog2(solDir2), actor2), log: new FileOpLog2(solDir2) };
 }
 var DEFAULT_IGNORE2 = [".sol", ".git", "node_modules", "dist", "build", ".next", ".cache", ".DS_Store", "__pycache__", "*.pyc", ".venv", "venv", "target", ".gradle", "*.log"];
 function ignorePatterns2() {
@@ -1630,6 +1673,28 @@ async function resolveRef(log, ref) {
   const op = ops.find((o) => o.rootAfter.startsWith(bare) || (o.entryHash ?? "").startsWith(bare)) || die("unknown ref: " + ref);
   return { head: op.rootAfter, op };
 }
+async function resolveRefSoft(log, ref) {
+  const ops = await log.history();
+  if (!ref || ref === "head" || ref === "HEAD")
+    return { head: await log.head() ?? "", op: ops[ops.length - 1] };
+  if (existsSync6(refsPath())) {
+    const refs = JSON.parse(readFileSync6(refsPath(), "utf8"));
+    if (ref === refs.current) {
+      const h = await log.head() ?? "";
+      return { head: h, op: [...ops].reverse().find((o) => o.rootAfter === h) ?? ops[ops.length - 1] };
+    }
+    const named = refs.branches[ref]?.head ?? refs.tags[ref];
+    if (named !== undefined)
+      return { head: named, op: [...ops].reverse().find((o) => o.rootAfter === named) };
+  }
+  if (/^\d+$/.test(ref)) {
+    const op2 = ops.find((o) => o.seq === Number(ref));
+    return op2 ? { head: op2.rootAfter, op: op2 } : undefined;
+  }
+  const bare = ref.startsWith("h_") ? ref : "h_" + ref;
+  const op = ops.find((o) => o.rootAfter.startsWith(bare) || (o.entryHash ?? "").startsWith(bare));
+  return op ? { head: op.rootAfter, op } : undefined;
+}
 function materialize(store, head, path) {
   const blob = fileAt(store, head, path);
   if (!blob)
@@ -1656,6 +1721,40 @@ function materialize(store, head, path) {
   }
   return true;
 }
+function materializeInto(store, head, target, path) {
+  const blob = fileAt(store, head, path);
+  if (!blob)
+    return false;
+  const abs = resolve2(target, path);
+  if (abs !== target && !abs.startsWith(target + sep2))
+    return false;
+  const mode = modeAt(store, head, path);
+  mkdirSync5(dirname3(abs), { recursive: true });
+  if (mode === SYMLINK_MODE2) {
+    try {
+      unlinkSync4(abs);
+    } catch {}
+    symlinkSync3(blob.content, abs);
+    return true;
+  }
+  writeFileSync6(abs, blob.encoding === "base64" ? Buffer.from(blob.content, "base64") : blob.content);
+  if (mode === EXEC_MODE2) {
+    try {
+      chmodSync3(abs, EXEC_MODE2);
+    } catch {}
+  }
+  return true;
+}
+function writeWorkingIndexAt(targetSolDir, target, files) {
+  const idx = {};
+  for (const f of files) {
+    try {
+      const st = lstatSync3(join6(target, f));
+      idx[f] = [st.mtimeMs, st.size, st.mode & 73 ? 1 : 0];
+    } catch {}
+  }
+  writeFileSync6(join6(targetSolDir, "index.json"), JSON.stringify(idx));
+}
 function materializeTree(store, head) {
   const want = new Set(head ? listAll(store, head) : []);
   let n = 0;
@@ -1809,13 +1908,17 @@ function workingChanges(store, head, index = loadWorkingIndex()) {
   }
   return { added: added.sort(), modified: modified.sort(), removed: removed.sort() };
 }
-function printWorkingDiff(store, base) {
+function printWorkingDiff(store, base, only) {
   const ch = workingChanges(store, base);
-  for (const f of ch.added)
+  const keep = (f) => only === undefined || f === only;
+  const added = ch.added.filter(keep);
+  const removed = ch.removed.filter(keep);
+  const modified = ch.modified.filter(keep);
+  for (const f of added)
     console.log(`+ added    ${f}`);
-  for (const f of ch.removed)
+  for (const f of removed)
     console.log(`- removed  ${f}`);
-  for (const f of ch.modified) {
+  for (const f of modified) {
     console.log(`~ modified ${f}`);
     const abs = join6(cwd2, f);
     if (lstatSync3(abs).isSymbolicLink())
@@ -1827,8 +1930,37 @@ function printWorkingDiff(store, base) {
     if (typeof stored === "string" && stored !== buf.toString("utf8"))
       console.log(indent(lineHunks2(stored, buf.toString("utf8"))));
   }
-  if (!ch.added.length && !ch.removed.length && !ch.modified.length)
-    console.log("no working changes");
+  if (!added.length && !removed.length && !modified.length)
+    console.log(only ? `no working changes in ${only}` : "no working changes");
+}
+function unresolvedConflictPaths() {
+  const out = [];
+  for (const f of walkFiles()) {
+    const abs = join6(cwd2, f);
+    let buf;
+    try {
+      const st = lstatSync3(abs);
+      if (st.isSymbolicLink() || st.isDirectory())
+        continue;
+      buf = readFileSync6(abs);
+    } catch {
+      continue;
+    }
+    if (buf.includes(0))
+      continue;
+    const text = buf.toString("utf8");
+    if (/^<{7}( |$)/m.test(text) && /^>{7}( |$)/m.test(text))
+      out.push(f);
+  }
+  return out;
+}
+function isWorkingPath(store, head, arg) {
+  const rel = repoRel(arg);
+  if (lexists(join6(cwd2, rel)))
+    return rel;
+  if (head && listAll(store, head).includes(rel))
+    return rel;
+  return;
 }
 function blameFile(ops, store, path) {
   let tagged = [];
@@ -1986,10 +2118,275 @@ async function writeBundle(solDir3, bundle, from = 0) {
   return fresh.length;
 }
 
+// src/bin/local-peer.ts
+import { existsSync as existsSync8 } from "node:fs";
+import { join as join8, resolve as resolve3 } from "node:path";
+function localPeerSolDir(arg, base) {
+  if (/^https?:\/\//.test(arg))
+    return;
+  const p = resolve3(base, arg);
+  if (existsSync8(join8(p, ".sol")))
+    return join8(p, ".sol");
+  if (existsSync8(join8(p, "objects")) && existsSync8(join8(p, "HEAD")))
+    return p;
+  return;
+}
+function openPeer(peerSolDir) {
+  return { store: new FileStore2(peerSolDir), log: new FileOpLog2(peerSolDir) };
+}
+async function peerNodes(rep, head) {
+  if (!head)
+    return [];
+  const out = [];
+  const seen = new Set;
+  const stack = [head];
+  while (stack.length) {
+    const h = stack.pop();
+    if (seen.has(h))
+      continue;
+    seen.add(h);
+    const node = await rep.store.get(h);
+    if (!node)
+      continue;
+    out.push(node);
+    if (node.kind === "tree")
+      for (const e of Object.values(node.entries))
+        stack.push(e.hash);
+  }
+  return out;
+}
+
+// src/merge.ts
+function resolvePath2(base, ours, theirs) {
+  const oursChanged = ours !== base;
+  const theirsChanged = theirs !== base;
+  if (!oursChanged && !theirsChanged) {
+    return { content: base };
+  }
+  if (oursChanged && !theirsChanged) {
+    return { content: ours };
+  }
+  if (!oursChanged && theirsChanged) {
+    return { content: theirs };
+  }
+  if (ours === theirs) {
+    return { content: ours };
+  }
+  if (base !== undefined && ours !== undefined && theirs !== undefined) {
+    const m = merge3(base, ours, theirs);
+    if (m.clean)
+      return { content: m.text };
+    return { content: m.text, conflict: { path: "", ours, theirs } };
+  }
+  return {
+    content: ours,
+    conflict: { path: "", ours, theirs }
+  };
+}
+function merge2(repo, baseHead, oursHead, theirsHead) {
+  const store = repo.store;
+  const paths = new Set([
+    ...listAll(store, baseHead),
+    ...listAll(store, oursHead),
+    ...listAll(store, theirsHead)
+  ]);
+  const conflicts = [];
+  let root = emptyRoot(store);
+  for (const path of [...paths].sort()) {
+    const base = readFile(store, baseHead, path);
+    const ours = readFile(store, oursHead, path);
+    const theirs = readFile(store, theirsHead, path);
+    const { content, conflict } = resolvePath2(base, ours, theirs);
+    if (conflict)
+      conflicts.push({ ...conflict, path });
+    if (content !== undefined) {
+      root = writeFile(store, root, path, content);
+    }
+  }
+  return { head: root, conflicts };
+}
+
+// src/converge.ts
+var EMPTY_TREE3 = { kind: "tree", entries: {} };
+function buildAncestry(ops) {
+  const parents = new Map;
+  const add = (child, parent) => {
+    if (!child || !parent || parent === child)
+      return;
+    let s = parents.get(child);
+    if (!s)
+      parents.set(child, s = new Set);
+    s.add(parent);
+  };
+  let prevRoot;
+  for (const op of ops) {
+    if (op.type === "checkpoint") {
+      add(op.rootAfter, op.parent);
+      add(op.rootAfter, op.parent2);
+    } else {
+      add(op.rootAfter, op.parent ?? prevRoot);
+    }
+    prevRoot = op.rootAfter;
+  }
+  return parents;
+}
+function ancestorsOf(head, parents) {
+  const seen = new Set;
+  const stack = [head];
+  while (stack.length) {
+    const h = stack.pop();
+    if (seen.has(h))
+      continue;
+    seen.add(h);
+    for (const p of parents.get(h) ?? [])
+      stack.push(p);
+  }
+  return seen;
+}
+function mergeBase(a, b, parents) {
+  if (a === b)
+    return a;
+  const bAnc = ancestorsOf(b, parents);
+  const seen = new Set;
+  let frontier = [a];
+  while (frontier.length) {
+    const next = [];
+    for (const h of frontier) {
+      if (seen.has(h))
+        continue;
+      seen.add(h);
+      if (bAnc.has(h))
+        return h;
+      for (const p of parents.get(h) ?? [])
+        next.push(p);
+    }
+    frontier = next;
+  }
+  return;
+}
+async function hydrate2(src, dst, root) {
+  if (!root)
+    return dst.put(EMPTY_TREE3);
+  const stack = [root];
+  const seen = new Set;
+  while (stack.length) {
+    const h = stack.pop();
+    if (seen.has(h))
+      continue;
+    seen.add(h);
+    const node = await src.get(h);
+    if (!node)
+      continue;
+    dst.put(node);
+    if (node.kind === "tree")
+      for (const e of Object.values(node.entries))
+        stack.push(e.hash);
+  }
+  return root;
+}
+async function persist(sync, dst, root) {
+  const stack = [root];
+  const seen = new Set;
+  while (stack.length) {
+    const h = stack.pop();
+    if (seen.has(h))
+      continue;
+    seen.add(h);
+    const node = sync.get(h);
+    if (!node)
+      continue;
+    if (!await dst.has(h))
+      await dst.put(node);
+    if (node.kind === "tree")
+      for (const e of Object.values(node.entries))
+        stack.push(e.hash);
+  }
+}
+async function converge(local, input) {
+  const at = input.at ?? Date.now();
+  const actor3 = input.actor ?? "system";
+  for (const node of input.nodes)
+    await local.store.put(node);
+  const priorHead = await local.log.head();
+  const incomingHead = input.incomingHead ?? input.ops[input.ops.length - 1]?.rootAfter;
+  const sinceSeq = await local.log.seq();
+  const existing = await local.log.history();
+  const priorAncestry = buildAncestry(existing);
+  const knownByEntry = new Map(existing.filter((o) => o.entryHash).map((o) => [o.entryHash, o]));
+  const knownByTuple = new Map(existing.map((o) => [`${o.type}\x00${o.path}\x00${o.rootAfter}`, o]));
+  const incoming = [...input.ops].sort((a, b) => a.seq - b.seq);
+  let forkBase = input.base ?? priorHead;
+  if (input.base === undefined) {
+    for (const op of incoming) {
+      const k = op.entryHash ? knownByEntry.get(op.entryHash) : knownByTuple.get(`${op.type}\x00${op.path}\x00${op.rootAfter}`);
+      if (k)
+        forkBase = k.rootAfter;
+    }
+  }
+  let applied = 0;
+  for (const op of incoming) {
+    if (op.entryHash && knownByEntry.has(op.entryHash))
+      continue;
+    if (!op.entryHash && knownByTuple.has(`${op.type}\x00${op.path}\x00${op.rootAfter}`))
+      continue;
+    const stamped = applied === 0 && op.type !== "checkpoint" && op.parent === undefined ? { ...op, parent: forkBase } : { ...op };
+    await local.log.append({ ...stamped, seq: await local.log.seq() + 1 });
+    applied++;
+  }
+  let head = await local.log.head() ?? priorHead ?? await local.store.put(EMPTY_TREE3);
+  let merged = false;
+  let conflicts = [];
+  if (priorHead && incomingHead && priorHead !== incomingHead) {
+    const parents = buildAncestry(await local.log.history());
+    for (const [c, ps] of priorAncestry) {
+      let s = parents.get(c);
+      if (!s)
+        parents.set(c, s = new Set);
+      for (const p of ps)
+        s.add(p);
+    }
+    const priorIsAncestor = ancestorsOf(incomingHead, parents).has(priorHead);
+    const incomingIsAncestor = ancestorsOf(priorHead, parents).has(incomingHead);
+    if (incomingIsAncestor) {
+      if (await local.log.head() !== priorHead)
+        await appendHeadMove(local, priorHead, priorHead, incomingHead, actor3, at, "converge: keep ahead-of-incoming head");
+      head = priorHead;
+    } else if (!priorIsAncestor) {
+      const base = input.base ?? mergeBase(priorHead, incomingHead, parents);
+      const sync = new Store;
+      const baseRoot = await hydrate2(local.store, sync, base);
+      const oursRoot = await hydrate2(local.store, sync, priorHead);
+      const theirsRoot = await hydrate2(local.store, sync, incomingHead);
+      const result = merge2({ store: sync }, baseRoot, oursRoot, theirsRoot);
+      conflicts = result.conflicts;
+      await persist(sync, local.store, result.head);
+      await local.log.append({
+        seq: await local.log.seq() + 1,
+        type: "checkpoint",
+        path: "",
+        rootAfter: result.head,
+        at,
+        by: actor3,
+        message: conflicts.length ? `converge merge (${conflicts.length} conflict(s) kept with markers)` : "converge merge",
+        parent: priorHead,
+        parent2: incomingHead
+      });
+      head = result.head;
+      merged = true;
+    }
+  }
+  const finalOps = await local.log.history();
+  const missingOps = finalOps.filter((o) => o.seq > sinceSeq);
+  return { head, applied, merged, conflicts, missingOps };
+}
+async function appendHeadMove(local, head, parent, parent2, by, at, message) {
+  await local.log.append({ seq: await local.log.seq() + 1, type: "checkpoint", path: "", rootAfter: head, at, by, message, parent, parent2 });
+}
+
 // src/bin/runtime.ts
-import { chmodSync as chmodSync4, existsSync as existsSync8, lstatSync as lstatSync4, mkdirSync as mkdirSync6, readdirSync as readdirSync6, readFileSync as readFileSync8, readlinkSync as readlinkSync4, symlinkSync as symlinkSync4, unlinkSync as unlinkSync5, writeFileSync as writeFileSync8 } from "node:fs";
+import { chmodSync as chmodSync4, existsSync as existsSync9, lstatSync as lstatSync4, mkdirSync as mkdirSync6, readdirSync as readdirSync6, readFileSync as readFileSync8, readlinkSync as readlinkSync4, symlinkSync as symlinkSync4, unlinkSync as unlinkSync5, writeFileSync as writeFileSync8 } from "node:fs";
 import { platform } from "node:os";
-import { dirname as dirname4, join as join8, relative as relative4 } from "node:path";
+import { dirname as dirname4, join as join9, relative as relative4 } from "node:path";
 var SYMLINK_MODE3 = 40960;
 var EXEC_MODE3 = 493;
 function isolateCommand(command, scratch) {
@@ -2005,7 +2402,7 @@ function isolateCommand(command, scratch) {
   }
   throw new Error(`--isolate not yet wired for platform ${platform()} (macOS sandbox-exec only); omit --isolate to run unconfined`);
 }
-function hydrate2(store, head, dir) {
+function hydrate3(store, head, dir) {
   if (!head)
     return 0;
   let n = 0;
@@ -2013,7 +2410,7 @@ function hydrate2(store, head, dir) {
     const blob = fileAt(store, head, p);
     if (!blob)
       continue;
-    const abs = join8(dir, p);
+    const abs = join9(dir, p);
     mkdirSync6(dirname4(abs), { recursive: true });
     const mode = modeAt(store, head, p);
     if (mode === SYMLINK_MODE3) {
@@ -2035,7 +2432,7 @@ function hydrate2(store, head, dir) {
 }
 function walkDir(dir, base, pats, out = []) {
   for (const name of readdirSync6(dir)) {
-    const p = join8(dir, name);
+    const p = join9(dir, name);
     const rel = relative4(base, p);
     if (isIgnored(rel, pats))
       continue;
@@ -2053,11 +2450,11 @@ async function capture(repo, dir, keep = []) {
   const pats = ignorePatterns();
   const files = new Set(walkDir(dir, dir, pats));
   for (const k of keep)
-    if (existsSync8(join8(dir, k)))
+    if (existsSync9(join9(dir, k)))
       files.add(k);
   const written = [];
   for (const f of files) {
-    const abs = join8(dir, f);
+    const abs = join9(dir, f);
     const st = lstatSync4(abs);
     if (st.isSymbolicLink()) {
       const target = readlinkSync4(abs);
@@ -2085,7 +2482,7 @@ async function capture(repo, dir, keep = []) {
   }
   const deleted = [];
   for (const t of await repo.list()) {
-    if (!existsSync8(join8(dir, t))) {
+    if (!existsSync9(join9(dir, t))) {
       await repo.deleteFile(t);
       deleted.push(t);
     }
@@ -2094,7 +2491,7 @@ async function capture(repo, dir, keep = []) {
 }
 
 // src/bin/sol.ts
-var CRED_PATH = join9(homedir(), ".sol", "credentials");
+var CRED_PATH = join10(homedir(), ".sol", "credentials");
 function tokenClaims(token) {
   try {
     return JSON.parse(Buffer.from(token.split(".")[1] ?? "", "base64url").toString());
@@ -2103,7 +2500,7 @@ function tokenClaims(token) {
   }
 }
 async function loadStoredToken() {
-  if (!existsSync9(CRED_PATH))
+  if (!existsSync10(CRED_PATH))
     return;
   let creds;
   try {
@@ -2130,6 +2527,15 @@ async function loadStoredToken() {
   }
   return creds.accessToken;
 }
+function authExpired() {
+  return die("session expired \u2014 run `sol auth login` (or set SOL_TOKEN)");
+}
+function identityFromToken(token) {
+  const c = tokenClaims(token);
+  if (!c.handle && !c.email && !c.userId && !c.sub)
+    return;
+  return { handle: c.handle, email: c.email, userId: c.userId ?? c.sub };
+}
 function authHost() {
   if (process.env.SOL_AUTH)
     return process.env.SOL_AUTH.replace(/\/+$/, "");
@@ -2148,15 +2554,81 @@ function resolveRemote(solDir3) {
     return;
   return cfg.url ? cfg : { ...cfg, url: DEFAULT_REMOTE_URL };
 }
+function cliVersion() {
+  try {
+    return JSON.parse(readFileSync9(new URL("./package.json", import.meta.url), "utf8")).version || "dev";
+  } catch {
+    return "dev";
+  }
+}
 async function main() {
   const argv = process.argv.slice(2);
   if (argv[0] === "--version" || argv[0] === "-v" || argv[0] === "version") {
-    console.log("sol 0.1.0");
+    console.log(`sol ${cliVersion()}`);
     return;
   }
   const args = argv.slice(1);
   const wantsHelp = args.includes("--help") || args.includes("-h");
   const SUBHELP = {
+    commit: `sol commit "<message>"            commit the whole working tree (single author)
+  sol commit -m "<message>" <file>...   commit ONLY those paths (correct attribution for concurrent agents)
+
+flags:
+  -m <message>        message when scoping to files
+  --whole-tree        allow a whole-tree commit even with SOL_ACTOR set (else refused)
+  --force             commit even with unresolved <<<<<<< conflict markers
+
+examples:
+  sol commit "add login route"
+  sol commit -m "fix parser" src/parse.ts src/lex.ts`,
+    push: `sol push                          push the current branch to the configured remote (converging \u2014 never FF-rejected)
+  sol push <repo>                   if no remote is set, use the hosted Sol (${DEFAULT_REMOTE_URL}) + this repo name, then push
+  sol push --create <repo>          same, explicit form (creates the repo on first push)
+
+notes:
+  a remote already configured? the <repo>/--create arg is ignored \u2014 \`sol push\` just syncs.
+  set SOL_TOKEN (or \`sol auth login\`) first; the push registers the current branch's head on the remote.
+
+examples:
+  sol push                          # remote already configured
+  sol push alice/app                # one step: configure hosted remote + push`,
+    pull: `sol pull                          fetch + converge the current branch from the configured remote
+  sol pull <dir>                    OFFLINE: converge another local repo's .sol on disk into this one (multi-agent, no network)
+
+notes:
+  refuses to run over a dirty tree \u2014 commit or discard first. conflicts land in the working tree with markers.
+  refuses to run while UNRESOLVED <<<<<<< markers remain \u2014 resolve them and \`sol commit\`, then pull again.`,
+    seal: `sol seal <path> [recipient...]    encrypt a file so the HOST only ever sees ciphertext (per-path privacy)
+
+  the content becomes host-blind ciphertext committed into history; the keys stay LOCAL (~/.sol keystore).
+  you are always a recipient of your own seals. add other actors to share read access. \`sol cat\` decrypts
+  for a recipient; everyone else sees <<sealed>>.
+
+example:
+  sol seal secrets/.env alice bob   # alice, bob (and you) can read it; the server cannot`,
+    remote: `sol remote                        show the configured remote
+  sol remote <url> <repo>           set the remote (url + repo name)
+
+tip: \`sol push <repo>\` configures the hosted remote for you in one step.`,
+    branch: `sol branch                        list branches (* = current)
+  sol branch <name> [<ref>]         create a branch at <ref> (default: HEAD)`,
+    switch: `sol switch <branch>               switch branches (commits/keeps current work first; never loses it)`,
+    merge: `sol merge <branch>                3-way merge <branch> into the current branch
+  conflicts land in the working tree with <<<<<<< markers \u2014 resolve, then \`sol commit\`.`,
+    log: `sol log                           commit history for the current branch
+  sol log <branch|commit>           history scoped to a ref
+  sol log --all                     every op in the log (not just commits)`,
+    diff: `sol diff                          working tree vs HEAD
+  sol diff <ref>                    working tree vs a branch/commit
+  sol diff <ref> <ref>              tree vs tree
+  sol diff <path>                   one file, working tree vs HEAD`,
+    restore: `sol restore [--from <ref>] [<path>...]   restore a file (or the whole tree) from a ref (default HEAD)`,
+    run: `sol run [--keep <path>]... [--isolate] <command...>
+  hydrate the current tree to a sandbox, run the command, capture produced files back into a commit.
+  --isolate confines the run (no network, writes stay in the sandbox).`,
+    promote: "sol promote [branch]   point the remote's production branch at <branch> (default: current branch)",
+    git: `sol git import <repo> [dir]       import a git repo's HEAD into a new Sol repo
+  sol git export <repo> [-m "msg"]  write Sol's tree back as a git commit, then \`git push\``,
     mr: `sol mr open [--from <branch>] [--to <branch>] [--upstream <repo>] -t "title" [-m body]
   sol mr list | show <id> | review <id> --approve|--request-changes|--comment [-m msg]
   sol mr comment <id> -m msg [--path f --line N] | check <id> --run -- <cmd> | merge <id> [--force] | close <id>`,
@@ -2176,12 +2648,12 @@ async function main() {
     if (t)
       process.env.SOL_TOKEN = t;
   }
-  const release = new Set(["add", "track", "commit", "checkpoint", "rm", "gc", "branch", "tag", "switch", "merge", "pull", "run", "seal"]).has(cmd) && existsSync9(solDir2) ? acquireLock() : undefined;
+  const release = new Set(["add", "track", "commit", "checkpoint", "rm", "gc", "branch", "tag", "switch", "merge", "pull", "run", "seal"]).has(cmd) && existsSync10(solDir2) ? acquireLock() : undefined;
   try {
     switch (cmd) {
       case "init": {
-        const here = join9(procCwd2, ".sol");
-        if (existsSync9(here))
+        const here = join10(procCwd2, ".sol");
+        if (existsSync10(here))
           die("already a sol repo: " + procCwd2);
         if (repoRoot2 && repoRoot2 !== procCwd2 && !args.includes("--force")) {
           die(`already inside a Sol repo at ${repoRoot2}
@@ -2195,7 +2667,7 @@ async function main() {
       }
       case "track":
       case "add": {
-        if (!existsSync9(solDir2))
+        if (!existsSync10(solDir2))
           die("not a sol repo \u2014 run `sol init` first");
         const files = args.filter((a) => a !== "." && !a.startsWith("-"));
         if (!files.length) {
@@ -2206,7 +2678,7 @@ async function main() {
         let n = 0;
         for (const f of files) {
           const rf = repoRel(f);
-          if (!existsSync9(join9(cwd2, rf))) {
+          if (!existsSync10(join10(cwd2, rf))) {
             console.error("skip (not on disk): " + f);
             continue;
           }
@@ -2235,14 +2707,14 @@ async function main() {
         if (!message)
           die('commit needs a message: sol commit "what you did"  (scoped: sol commit -m "msg" file1 file2)');
         const parentHead = await repo.head();
-        const mergeHeadPath = join9(solDir2, "MERGE_HEAD");
-        const parent2 = existsSync9(mergeHeadPath) ? readFileSync9(mergeHeadPath, "utf8").trim() || undefined : undefined;
+        const mergeHeadPath = join10(solDir2, "MERGE_HEAD");
+        const parent2 = existsSync10(mergeHeadPath) ? readFileSync9(mergeHeadPath, "utf8").trim() || undefined : undefined;
         let changed = 0;
         let commitRoot = parentHead;
         if (paths.length) {
           for (const p of paths) {
             const rp = repoRel(p);
-            if (existsSync9(join9(cwd2, rp))) {
+            if (existsSync10(join10(cwd2, rp))) {
               if (await snapshotFile(repo, rp))
                 changed++;
             } else if ((await repo.list()).includes(rp)) {
@@ -2255,7 +2727,8 @@ async function main() {
           commitRoot = await repo.head();
         } else {
           const optedIn = wholeTreeOptIn || process.env.SOL_ALLOW_WHOLE_TREE === "1";
-          if (process.env.SOL_ACTOR && !optedIn) {
+          const otherActorPresent = (await log.history()).some((o) => o.by && o.by !== actor2);
+          if (process.env.SOL_ACTOR && !optedIn && otherActorPresent) {
             die(`refusing a whole-tree commit as "${actor2}" \u2014 it would attribute ALL pending files to you.
   concurrent agents: sol commit -m "${message}" <your files>   (or a per-agent SolWorkspace/MCP)
   if you truly own the whole tree: add --whole-tree  or set SOL_ALLOW_WHOLE_TREE=1`);
@@ -2292,7 +2765,7 @@ async function main() {
       }
       case "status": {
         const { repo, log } = open();
-        const refs = existsSync9(refsPath()) ? await loadRefs(log) : undefined;
+        const refs = existsSync10(refsPath()) ? await loadRefs(log) : undefined;
         const head = await repo.head();
         console.log(`repo ${cwd2}`);
         console.log(`on ${refs ? refs.current : "main"}   head ${head.slice(0, 14)}   seq ${await log.seq()}   actor ${actor2}`);
@@ -2348,7 +2821,7 @@ async function main() {
             byRoot.set(o.rootAfter, o);
         const live = await log.head() ?? "";
         const refArg = args.find((a) => !a.startsWith("-"));
-        const lrefs = existsSync9(refsPath()) ? JSON.parse(readFileSync9(refsPath(), "utf8")) : null;
+        const lrefs = existsSync10(refsPath()) ? JSON.parse(readFileSync9(refsPath(), "utf8")) : null;
         let tip = live;
         if (refArg) {
           tip = lrefs?.branches[refArg]?.head ?? refArg;
@@ -2359,19 +2832,27 @@ async function main() {
         }
         const chain = [];
         const seen = new Set;
-        let cur = tip;
-        while (cur && byRoot.has(cur) && !seen.has(cur)) {
+        const stack = [tip];
+        while (stack.length) {
+          const cur = stack.pop();
+          if (!cur || seen.has(cur) || !byRoot.has(cur))
+            continue;
           seen.add(cur);
           const c = byRoot.get(cur);
           chain.push(c);
-          cur = c.parent;
+          if (c.parent)
+            stack.push(c.parent);
+          if (c.parent2)
+            stack.push(c.parent2);
         }
+        chain.sort((a, b) => b.seq - a.seq);
         if (!chain.length) {
           console.log(ops.length ? '(no commits on this branch yet \u2014 run `sol commit "msg"`)' : "(no history yet)");
         }
         for (const c of chain) {
           const n = countChanges(store, c.parent ?? "", c.rootAfter);
-          const tag = c.parent2 ? `  [merge ${c.parent2.slice(0, 8)}]` : "";
+          const mergedIn = [c.parent2 && byRoot.get(c.parent2)?.by].filter(Boolean);
+          const tag = c.parent2 ? `  [merge ${c.parent2.slice(0, 8)}${mergedIn.length ? ` <- ${mergedIn.join(", ")}` : ""}]` : "";
           console.log(`${c.rootAfter.slice(0, 14)}  ${(c.by ?? "?").padEnd(14)}  ${c.message ?? ""}  (${n} change${n === 1 ? "" : "s"})${tag}`);
         }
         const wc = workingChanges(store, live);
@@ -2384,7 +2865,7 @@ async function main() {
         const path = args[0] || die("rm needs a path");
         let onDisk = false;
         try {
-          unlinkSync6(join9(cwd2, path));
+          unlinkSync6(join10(cwd2, path));
           onDisk = true;
         } catch {}
         if (onDisk) {
@@ -2401,10 +2882,26 @@ async function main() {
       case "diff": {
         const { log } = open();
         const store = loadStore();
+        const head = await log.head() ?? "";
         if (args.length >= 2) {
           printTreeDiff(diffTrees(store, (await resolveRef(log, args[0])).head, (await resolveRef(log, args[1])).head));
+        } else if (args.length === 1) {
+          const resolved = await resolveRefSoft(log, args[0]);
+          if (resolved) {
+            printWorkingDiff(store, resolved.head);
+          } else {
+            const path = isWorkingPath(store, head, args[0]);
+            if (path)
+              printWorkingDiff(store, head, path);
+            else
+              die(`'${args[0]}' is neither a ref nor a working-tree path.
+  usage: sol diff            (working tree vs HEAD)
+         sol diff <ref>      (working tree vs a branch/commit)
+         sol diff <ref> <ref> (tree vs tree)
+         sol diff <path>     (one file, working tree vs HEAD)`);
+          }
         } else {
-          printWorkingDiff(store, (await resolveRef(log, args[0])).head);
+          printWorkingDiff(store, head);
         }
         break;
       }
@@ -2535,11 +3032,11 @@ async function main() {
         };
         for (const op of ops)
           walk(op.rootAfter);
-        const objDir = join9(solDir2, "objects");
+        const objDir = join10(solDir2, "objects");
         let removed = 0;
         for (const name of readdirSync7(objDir)) {
           if (name.endsWith(".tmp") || !reachable.has(name)) {
-            unlinkSync6(join9(objDir, name));
+            unlinkSync6(join10(objDir, name));
             removed++;
           }
         }
@@ -2553,8 +3050,8 @@ async function main() {
             console.log(p);
           break;
         }
-        const f = join9(cwd2, ".solignore");
-        const lead = existsSync9(f) && !readFileSync9(f, "utf8").endsWith(`
+        const f = join10(cwd2, ".solignore");
+        const lead = existsSync10(f) && !readFileSync9(f, "utf8").endsWith(`
 `) ? `
 ` : "";
         appendFileSync4(f, lead + pat + `
@@ -2572,8 +3069,8 @@ async function main() {
         if (content === SEALED2)
           die("already sealed: " + path);
         if (content === undefined) {
-          const abs = join9(cwd2, path);
-          if (!existsSync9(abs))
+          const abs = join10(cwd2, path);
+          if (!existsSync10(abs))
             die("no such file: " + path);
           content = readFileSync9(abs, "utf8");
         }
@@ -2639,7 +3136,7 @@ async function main() {
         refs.current = name;
         saveRefs(refs);
         const n = materializeDiff(loadStore(), fromHead, target.head);
-        console.log(`switched to ${name} (${(target.head || "empty").slice(0, 12)}); working tree = ${n} file(s)`);
+        console.log(`switched to ${name} (${(target.head || "empty").slice(0, 12)}); ${n} file(s) changed`);
         break;
       }
       case "merge": {
@@ -2660,7 +3157,7 @@ async function main() {
         const result = merge({ store }, other.base, ours, other.head);
         if (result.conflicts.length) {
           materializeTree(store, result.head);
-          writeFileSync9(join9(solDir2, "MERGE_HEAD"), other.head);
+          writeFileSync9(join10(solDir2, "MERGE_HEAD"), other.head);
           console.log(`merge ${name} -> ${result.conflicts.length} conflict(s), left in your working tree (uncommitted):`);
           for (const c of result.conflicts)
             console.log("  " + c.path);
@@ -2679,7 +3176,7 @@ async function main() {
         break;
       }
       case "remote": {
-        if (!existsSync9(solDir2))
+        if (!existsSync10(solDir2))
           die("not a sol repo");
         if (args[0]) {
           const repoName = args[1] || die("usage: sol remote <url> <repo>");
@@ -2733,7 +3230,7 @@ async function main() {
           if (!c.handle)
             console.log("  (no handle yet \u2014 set one in the web app to get your <handle>/<repo> namespace)");
         } else if (sub === "logout") {
-          if (existsSync9(CRED_PATH))
+          if (existsSync10(CRED_PATH))
             unlinkSync6(CRED_PATH);
           console.log("logged out");
         } else if (sub === "status" || !sub) {
@@ -2742,7 +3239,7 @@ async function main() {
             console.log(`authenticated via SOL_TOKEN (env)${c2.handle ? ` as @${c2.handle}` : ""}`);
             break;
           }
-          if (!existsSync9(CRED_PATH)) {
+          if (!existsSync10(CRED_PATH)) {
             console.log("not logged in \u2014 run `sol auth login` (or set SOL_TOKEN)");
             break;
           }
@@ -2753,20 +3250,26 @@ async function main() {
         } else if (sub === "whoami") {
           const token = process.env.SOL_TOKEN || await loadStoredToken();
           if (!token)
-            die("not logged in \u2014 run `sol auth login` (or set SOL_TOKEN)");
-          const res = await fetch(`${authHost()}/api/auth/me`, { headers: { authorization: `Bearer ${token}` } });
-          if (res.status === 401)
-            die("not logged in \u2014 your session expired; run `sol auth login` again");
-          if (!res.ok)
-            die(`could not reach ${authHost()} (me -> ${res.status})`);
-          const me = await res.json();
-          console.log(me.handle ? `signed in as @${me.handle}  ${me.email ?? ""}`.trimEnd() : `signed in${me.email ? ` as ${me.email}` : ""} \u2014 no handle yet (\`sol auth set-handle <name>\`)`);
+            authExpired();
+          let id = identityFromToken(token);
+          try {
+            const res = await fetch(`${authHost()}/api/auth/me`, { headers: { authorization: `Bearer ${token}` } });
+            if (res.status === 401 && !id)
+              authExpired();
+            if (res.ok) {
+              const me = await res.json();
+              id = { handle: me.handle ?? id?.handle, email: me.email ?? id?.email, userId: id?.userId };
+            }
+          } catch {}
+          if (!id)
+            authExpired();
+          console.log(id.handle ? `signed in as @${id.handle}  ${id.email ?? ""}`.trimEnd() : `signed in${id.email ? ` as ${id.email}` : ""} \u2014 no handle yet (\`sol auth set-handle <name>\`)`);
         } else if (sub === "set-handle") {
           const want = args[1] || die("usage: sol auth set-handle <name>");
           const handle = want.toLowerCase();
           const token = process.env.SOL_TOKEN || await loadStoredToken();
           if (!token)
-            die("not logged in \u2014 run `sol auth login` (or set SOL_TOKEN)");
+            authExpired();
           let hadHandle = false;
           try {
             const meRes = await fetch(`${authHost()}/api/auth/me`, { headers: { authorization: `Bearer ${token}` } });
@@ -2775,7 +3278,7 @@ async function main() {
           } catch {}
           const res = await fetch(`${authHost()}/api/auth/handle`, { method: "POST", headers: { authorization: `Bearer ${token}`, "content-type": "application/json" }, body: JSON.stringify({ handle }) });
           if (res.status === 401)
-            die("not logged in \u2014 your session expired; run `sol auth login` again");
+            authExpired();
           if (!res.ok) {
             let msg = `could not set handle (${res.status})`;
             try {
@@ -2790,7 +3293,7 @@ async function main() {
             console.log("heads-up: changing your handle re-namespaces your repos under the new <handle>/<repo>.");
           console.log(`handle set to @${out.handle}`);
         } else if (sub === "pat") {
-          if (!existsSync9(CRED_PATH))
+          if (!existsSync10(CRED_PATH))
             die("run `sol auth login` first");
           const creds = JSON.parse(readFileSync9(CRED_PATH, "utf8"));
           const token = await loadStoredToken();
@@ -2844,12 +3347,33 @@ async function main() {
         break;
       }
       case "clone": {
+        const localSrc = args[0] ? localPeerSolDir(args[0], procCwd2) : undefined;
+        if (localSrc) {
+          const peer = openPeer(localSrc);
+          const peerHead = await peer.log.head();
+          const dest = resolve4(procCwd2, args[1] || (args[0].replace(/\/+$/, "").split("/").pop() || "clone") + "-clone");
+          const ddir = join10(dest, ".sol");
+          if (existsSync10(ddir))
+            die("already a sol repo: " + dest);
+          mkdirSync7(ddir, { recursive: true });
+          const res = await converge({ store: new FileStore(ddir), log: new FileOpLog(ddir) }, { nodes: await peerNodes(peer, peerHead), ops: await peer.log.history(), incomingHead: peerHead, actor: actor2 });
+          const dstore = new Store2;
+          for (const n2 of await peerNodes({ store: new FileStore(ddir), log: new FileOpLog(ddir) }, res.head))
+            dstore.put(n2);
+          const files = res.head ? listAll3(dstore, res.head) : [];
+          for (const f of files)
+            materializeInto(dstore, res.head, dest, f);
+          writeFileSync9(join10(ddir, "refs.json"), JSON.stringify({ current: "main", branches: { main: { head: res.head, base: res.head, remote: res.head } }, tags: {} }, null, 2));
+          writeWorkingIndexAt(ddir, dest, files);
+          console.log(`cloned local peer ${args[0]} -> ${dest} (${(await peer.log.history()).length} ops, ${files.length} files)`);
+          break;
+        }
         const [url, rest] = remoteUrlArg(args);
         const repoName = rest[0] || die("usage: sol clone [<url>] <owner>/<repo> [dir]");
         const token = process.env.SOL_TOKEN || die("set SOL_TOKEN to the backend bearer token");
-        const target = resolve3(cwd2, rest[1] || repoName.split("/").pop() || repoName);
-        const fdir = join9(target, ".sol");
-        if (existsSync9(fdir))
+        const target = resolve4(cwd2, rest[1] || repoName.split("/").pop() || repoName);
+        const fdir = join10(target, ".sol");
+        if (existsSync10(fdir))
           die("already a sol repo: " + target);
         const cfg = { url, repo: repoName };
         const bundle = await remoteExport(cfg, token);
@@ -2865,63 +3389,62 @@ async function main() {
           cloneBranches[name] = { head: h, base: h, remote: h };
         if (!cloneBranches[onBranch])
           cloneBranches[onBranch] = { head: checkoutHead, base: checkoutHead, remote: checkoutHead };
-        writeFileSync9(join9(fdir, "refs.json"), JSON.stringify({ current: onBranch, branches: cloneBranches, tags: {} }, null, 2));
-        writeFileSync9(join9(fdir, "HEAD"), JSON.stringify({ head: checkoutHead, seq: bundle.seq, logTip: bundle.tip }));
+        writeFileSync9(join10(fdir, "refs.json"), JSON.stringify({ current: onBranch, branches: cloneBranches, tags: {} }, null, 2));
+        writeFileSync9(join10(fdir, "HEAD"), JSON.stringify({ head: checkoutHead, seq: bundle.seq, logTip: bundle.tip }));
         const store = new Store2;
         for (const node of bundle.nodes)
           store.put(node);
         let n = 0;
         if (checkoutHead) {
-          for (const f of listAll3(store, checkoutHead)) {
-            const abs = resolve3(target, f);
-            if (abs !== target && !abs.startsWith(target + sep3))
-              continue;
-            const blob = fileAt3(store, checkoutHead, f);
-            if (!blob)
-              continue;
-            mkdirSync7(dirname5(abs), { recursive: true });
-            writeFileSync9(abs, blob.encoding === "base64" ? Buffer.from(blob.content, "base64") : blob.content);
-            n++;
-          }
+          const files = listAll3(store, checkoutHead);
+          for (const f of files)
+            if (materializeInto(store, checkoutHead, target, f))
+              n++;
+          writeWorkingIndexAt(fdir, target, files);
         }
         console.log(`cloned ${repoName} -> ${rest[1] || repoName} (${bundle.ops.length} ops, ${Object.keys(cloneBranches).length} branch(es), ${n} files, on ${onBranch})`);
         break;
       }
       case "push": {
         const { log } = open();
-        const cfg = resolveRemote(solDir2) || die("no remote \u2014 set one with `sol remote <url> <repo>`");
-        const token = process.env.SOL_TOKEN || die("set SOL_TOKEN");
+        if (!loadRemote(solDir2)) {
+          const ci = args.indexOf("--create");
+          const repoName = ci >= 0 ? args[ci + 1] : args.find((a) => !a.startsWith("-"));
+          if (repoName) {
+            saveRemote(solDir2, { url: DEFAULT_REMOTE_URL, repo: repoName });
+            console.log(`remote set: ${DEFAULT_REMOTE_URL} (repo ${repoName})`);
+          }
+        }
+        const cfg = resolveRemote(solDir2) || die("no remote \u2014 set one with `sol remote <url> <repo>`, or `sol push <repo>` to use the hosted Sol");
+        const token = process.env.SOL_TOKEN || authExpired();
         const rh = await remoteHead(cfg, token);
         const ops = await log.history();
         const localSeq = ops.length ? ops[ops.length - 1].seq : 0;
         const localTip = await log.logTip();
-        const localRefs = existsSync9(refsPath()) ? JSON.parse(readFileSync9(refsPath(), "utf8")) : undefined;
+        const localRefs = existsSync10(refsPath()) ? JSON.parse(readFileSync9(refsPath(), "utf8")) : undefined;
         const branch = localRefs?.current ?? "main";
         const branchHead = await log.head() ?? "";
+        const remoteWasEmpty = rh.seq === 0 && !rh.tip;
         if (localSeq === rh.seq && localTip === rh.tip) {
-          console.log("everything up to date");
-          break;
-        }
-        if (rh.seq > 0) {
-          const atRemote = ops.find((o) => o.seq === rh.seq);
-          if (!atRemote || atRemote.entryHash !== rh.tip)
-            die("push rejected \u2014 the remote has changes you don't have (run `sol pull` first)");
-        }
-        if (localSeq <= rh.seq) {
-          console.log("nothing to push");
+          console.log(remoteWasEmpty ? "nothing to push \u2014 local repo is empty (commit something first)" : "everything up to date");
           break;
         }
-        let res;
-        try {
-          res = await remotePush(cfg, token, { nodes: allLocalNodes(), ops: ops.filter((o) => o.seq > rh.seq), branch, head: branchHead, expectedHead: localRefs?.branches[branch]?.remote });
-        } catch (e) {
-          if (String(e?.message ?? "").includes("409"))
-            die(`push rejected \u2014 branch '${branch}' moved on the remote. run \`sol pull\`, then push again.`);
-          throw e;
-        }
+        if (localSeq <= rh.seq) {}
+        const forkBase = localRefs?.branches[branch]?.remote;
+        const baseOp = forkBase ? ops.find((o) => o.rootAfter === forkBase) : undefined;
+        const fromSeq = baseOp ? baseOp.seq : rh.seq;
+        const res = await remotePush(cfg, token, {
+          nodes: allLocalNodes(),
+          ops: ops.filter((o) => o.seq > fromSeq),
+          branch,
+          head: branchHead,
+          expectedHead: forkBase
+        });
         const canon = await remoteExport(cfg, token);
+        const prevHead = await log.head() ?? "";
         await writeBundle(solDir2, canon, 0);
-        if (existsSync9(refsPath())) {
+        const convergedHead = res.head ?? canon.refs?.branches?.[branch] ?? branchHead;
+        if (existsSync10(refsPath())) {
           const refs = JSON.parse(readFileSync9(refsPath(), "utf8"));
           if (canon.refs) {
             for (const [name, h] of Object.entries(canon.refs.branches)) {
@@ -2929,28 +3452,76 @@ async function main() {
             }
           }
           if (refs.branches[branch]) {
-            refs.branches[branch].head = res.head ?? branchHead;
-            refs.branches[branch].remote = res.head ?? branchHead;
+            refs.branches[branch].head = convergedHead;
+            refs.branches[branch].remote = convergedHead;
           }
           saveRefs(refs);
         }
-        setOpLogHead(res.head ?? branchHead);
+        setOpLogHead(convergedHead);
+        if (convergedHead && convergedHead !== prevHead)
+          materializeDiff(loadStore(), prevHead, convergedHead);
         const prod = res.refs?.production;
-        console.log(`pushed ${res.applied} op(s) -> remote (branch ${branch} @ ${(res.head ?? "").slice(0, 12)})${prod ? `; production=${prod}` : ""}`);
+        const mergedNote = res.merged ? " (converged with a concurrent commit)" : "";
+        const conflictNote = res.conflicts && res.conflicts.length ? ` \u2014 ${res.conflicts.length} conflict(s) kept with markers in: ${res.conflicts.map((c) => c.path).join(", ")}` : "";
+        if (remoteWasEmpty) {
+          console.log(`created remote repo ${cfg.repo} \u2014 pushed ${res.applied} op(s) (branch ${branch} @ ${(convergedHead || "").slice(0, 12)})${prod ? `; production=${prod}` : ""}`);
+        } else {
+          console.log(`pushed ${res.applied} op(s) -> remote (branch ${branch} @ ${(convergedHead || "").slice(0, 12)})${mergedNote}${conflictNote}${prod ? `; production=${prod}` : ""}`);
+        }
         break;
       }
       case "pull": {
         const { log } = open();
+        {
+          const marked = unresolvedConflictPaths();
+          if (marked.length)
+            die(`unresolved conflict markers in ${marked.join(", ")} \u2014 resolve them and \`sol commit\`, then pull again.`);
+        }
+        const peerArg = args[0];
+        const peerSolDir = peerArg ? localPeerSolDir(peerArg, cwd2) : undefined;
+        if (peerSolDir) {
+          const wcLocal = workingChanges(loadStore(), await log.head() ?? "");
+          if (wcLocal.added.length + wcLocal.modified.length + wcLocal.removed.length > 0) {
+            die("you have uncommitted changes \u2014 commit (`sol commit`) or discard them before pulling.");
+          }
+          const peer = openPeer(peerSolDir);
+          const peerHead = await peer.log.head();
+          if (!peerHead) {
+            console.log("peer repo is empty \u2014 nothing to pull");
+            break;
+          }
+          const prevHead = await log.head() ?? "";
+          const res = await converge({ store: new FileStore(solDir2), log }, { nodes: await peerNodes(peer, peerHead), ops: await peer.log.history(), incomingHead: peerHead, actor: actor2 });
+          if (existsSync10(refsPath())) {
+            const refs = JSON.parse(readFileSync9(refsPath(), "utf8"));
+            if (refs.branches[refs.current])
+              refs.branches[refs.current].head = res.head;
+            saveRefs(refs);
+          }
+          setOpLogHead(res.head);
+          if (res.head !== prevHead)
+            materializeDiff(loadStore(), prevHead, res.head);
+          if (res.conflicts.length) {
+            console.log(`pulled + merged from ${peerArg} WITH ${res.conflicts.length} conflict(s) \u2014 both sides kept with markers in:`);
+            for (const c of res.conflicts)
+              console.log("  " + c.path);
+            console.log("resolve the <<<<<<< markers, then `sol commit`");
+            process.exitCode = 1;
+          } else {
+            console.log(`pulled from ${peerArg} -> ${res.applied} new op(s)${res.merged ? " (converged by merge)" : ""}, now at ${(res.head || "").slice(0, 12)}`);
+          }
+          break;
+        }
         const cfg = resolveRemote(solDir2) || die("no remote \u2014 set one with `sol remote <url> <repo>`");
-        const token = process.env.SOL_TOKEN || die("set SOL_TOKEN");
+        const token = process.env.SOL_TOKEN || authExpired();
         const bundle = await remoteExport(cfg, token);
         const ops = await log.history();
         const localSeq = ops.length ? ops[ops.length - 1].seq : 0;
         const localTip = await log.logTip();
-        const curBranch = existsSync9(refsPath()) ? JSON.parse(readFileSync9(refsPath(), "utf8")).current : bundle.refs?.production || "main";
+        const curBranch = existsSync10(refsPath()) ? JSON.parse(readFileSync9(refsPath(), "utf8")).current : bundle.refs?.production || "main";
         const remoteCurHead = bundle.refs?.branches?.[curBranch] ?? bundle.head ?? "";
         if (bundle.seq === localSeq && bundle.tip === localTip) {
-          if (bundle.refs && existsSync9(refsPath())) {
+          if (bundle.refs && existsSync10(refsPath())) {
             const lr = JSON.parse(readFileSync9(refsPath(), "utf8"));
             const before = lr.branches[lr.current]?.head;
             for (const [name, h] of Object.entries(bundle.refs.branches))
@@ -2975,7 +3546,7 @@ async function main() {
           break;
         }
         const syncRefHead = (h) => {
-          if (!existsSync9(refsPath()))
+          if (!existsSync10(refsPath()))
             return;
           const refs = JSON.parse(readFileSync9(refsPath(), "utf8"));
           if (refs.branches[refs.current])
@@ -2995,7 +3566,7 @@ async function main() {
           syncRefHead(remoteCurHead);
           setOpLogHead(remoteCurHead);
           materializeTree(loadStore(), remoteCurHead);
-          if (bundle.refs && existsSync9(refsPath())) {
+          if (bundle.refs && existsSync10(refsPath())) {
             const lr = JSON.parse(readFileSync9(refsPath(), "utf8"));
             for (const [name, h] of Object.entries(bundle.refs.branches))
               lr.branches[name] = { head: h, base: lr.branches[name]?.base ?? h, remote: h };
@@ -3044,9 +3615,9 @@ async function main() {
           for (const c of result.conflicts) {
             const blob = fileAt3(store, result.head, c.path);
             if (blob)
-              writeFileSync9(join9(cwd2, c.path), blob.encoding === "base64" ? Buffer.from(blob.content, "base64") : blob.content);
+              writeFileSync9(join10(cwd2, c.path), blob.encoding === "base64" ? Buffer.from(blob.content, "base64") : blob.content);
           }
-          writeFileSync9(join9(solDir2, "MERGE_HEAD"), remoteHead2);
+          writeFileSync9(join10(solDir2, "MERGE_HEAD"), remoteHead2);
           console.log(`pulled + merged WITH ${result.conflicts.length} conflict(s), left uncommitted in your working tree:`);
           for (const c of result.conflicts)
             console.log("  " + c.path);
@@ -3058,11 +3629,11 @@ async function main() {
         break;
       }
       case "promote": {
-        if (!existsSync9(solDir2))
+        if (!existsSync10(solDir2))
           die("not a sol repo");
         const cfg = resolveRemote(solDir2) || die("no remote \u2014 set one with `sol remote <url> <repo>`");
-        const token = process.env.SOL_TOKEN || die("set SOL_TOKEN");
-        const cur = existsSync9(refsPath()) ? JSON.parse(readFileSync9(refsPath(), "utf8")).current : "main";
+        const token = process.env.SOL_TOKEN || authExpired();
+        const cur = existsSync10(refsPath()) ? JSON.parse(readFileSync9(refsPath(), "utf8")).current : "main";
         const branch = args[0] || cur;
         const refs = await remotePromote(cfg, token, branch);
         console.log(`promoted '${branch}' -> production '${refs.production}' now at ${(refs.branches[refs.production] ?? "").slice(0, 12)}`);
@@ -3072,10 +3643,10 @@ async function main() {
         const [url, frest] = remoteUrlArg(args);
         const parent = frest[0] || die("usage: sol fork [<url>] <parent-repo> <new-repo> [dir]");
         const newRepo = frest[1] || die("usage: sol fork [<url>] <parent-repo> <new-repo> [dir]");
-        const token = process.env.SOL_TOKEN || die("set SOL_TOKEN");
-        const target = resolve3(cwd2, frest[2] || newRepo);
-        const fdir = join9(target, ".sol");
-        if (existsSync9(fdir))
+        const token = process.env.SOL_TOKEN || authExpired();
+        const target = resolve4(cwd2, frest[2] || newRepo);
+        const fdir = join10(target, ".sol");
+        if (existsSync10(fdir))
           die("already a sol repo: " + target);
         const parentCfg = { url, repo: parent };
         const newCfg = { url, repo: newRepo, forkParent: parent };
@@ -3100,32 +3671,26 @@ async function main() {
         const cloneBranches = {};
         for (const [name, h] of Object.entries(srvRefs.branches))
           cloneBranches[name] = { head: h, base: h, remote: h };
-        writeFileSync9(join9(fdir, "refs.json"), JSON.stringify({ current: onBranch, branches: cloneBranches, tags: {} }, null, 2));
-        writeFileSync9(join9(fdir, "HEAD"), JSON.stringify({ head: checkoutHead, seq: canon.seq, logTip: canon.tip }));
+        writeFileSync9(join10(fdir, "refs.json"), JSON.stringify({ current: onBranch, branches: cloneBranches, tags: {} }, null, 2));
+        writeFileSync9(join10(fdir, "HEAD"), JSON.stringify({ head: checkoutHead, seq: canon.seq, logTip: canon.tip }));
         saveRemote(fdir, newCfg);
         const store = new Store2;
         for (const node of canon.nodes)
           store.put(node);
         let n = 0;
         if (checkoutHead) {
-          for (const f of listAll3(store, checkoutHead)) {
-            const abs = resolve3(target, f);
-            if (abs !== target && !abs.startsWith(target + sep3))
-              continue;
-            const blob = fileAt3(store, checkoutHead, f);
-            if (!blob)
-              continue;
-            mkdirSync7(dirname5(abs), { recursive: true });
-            writeFileSync9(abs, blob.encoding === "base64" ? Buffer.from(blob.content, "base64") : blob.content);
-            n++;
-          }
+          const files = listAll3(store, checkoutHead);
+          for (const f of files)
+            if (materializeInto(store, checkoutHead, target, f))
+              n++;
+          writeWorkingIndexAt(fdir, target, files);
         }
         console.log(`forked ${parent} -> ${newRepo}  (your copy at ${args[3] || newRepo}: ${Object.keys(cloneBranches).length} branch(es), ${n} files; parent: ${parent})`);
         break;
       }
       case "access": {
+        const token = process.env.SOL_TOKEN || authExpired();
         const cfg = resolveRemote(solDir2) || die("no remote \u2014 set one with `sol remote <url> <repo>`");
-        const token = process.env.SOL_TOKEN || die("set SOL_TOKEN");
         const sub = args[0];
         if (!sub || sub === "show") {
           const a = await accessGet(cfg, token);
@@ -3160,7 +3725,7 @@ async function main() {
       }
       case "forks": {
         const cfg = resolveRemote(solDir2) || die("no remote \u2014 set one with `sol remote <url> <repo>`");
-        const token = process.env.SOL_TOKEN || die("set SOL_TOKEN");
+        const token = process.env.SOL_TOKEN || authExpired();
         const { forks } = await forksList(cfg, token);
         if (!forks.length)
           console.log(`(no forks of ${cfg.repo})`);
@@ -3173,9 +3738,9 @@ async function main() {
       }
       case "mr": {
         const cfg = resolveRemote(solDir2) || die("no remote \u2014 set one with `sol remote <url> <repo>`");
-        const token = process.env.SOL_TOKEN || die("set SOL_TOKEN");
+        const token = process.env.SOL_TOKEN || authExpired();
         const sub = args[0];
-        const localRefs = () => existsSync9(refsPath()) ? JSON.parse(readFileSync9(refsPath(), "utf8")) : { current: "main", branches: {}, tags: {} };
+        const localRefs = () => existsSync10(refsPath()) ? JSON.parse(readFileSync9(refsPath(), "utf8")) : { current: "main", branches: {}, tags: {} };
         const flag = (name) => {
           const i = args.indexOf(name);
           return i >= 0 ? args[i + 1] : undefined;
@@ -3352,9 +3917,9 @@ ${mrSummary(pr)}`);
         if (!command.length)
           die("usage: sol run [--keep <path>] [--isolate] <command...>");
         const head = await repo.head();
-        const dir = mkdtempSync(join9(tmpdir(), "sol-run-"));
+        const dir = mkdtempSync(join10(tmpdir(), "sol-run-"));
         try {
-          const hn = hydrate2(loadStore(), head, dir);
+          const hn = hydrate3(loadStore(), head, dir);
           console.log(`hydrated ${hn} file(s) -> sandbox${isolate ? " (isolated: no network, writes confined to the sandbox)" : ""}`);
           const argv2 = isolate ? isolateCommand(command, dir) : command;
           console.log(`$ ${command.join(" ")}`);
@@ -3372,7 +3937,7 @@ ${mrSummary(pr)}`);
           const { written, deleted } = await capture(repo, dir, keep);
           if (written.length || deleted.length) {
             await appendCommit(log, await repo.head(), `run: ${command.join(" ")}`, head);
-            if (existsSync9(refsPath())) {
+            if (existsSync10(refsPath())) {
               const refs = JSON.parse(readFileSync9(refsPath(), "utf8"));
               if (refs.branches[refs.current]) {
                 refs.branches[refs.current].head = await repo.head();
@@ -3385,7 +3950,7 @@ ${mrSummary(pr)}`);
               materialize(synced, nh, f);
             for (const f of deleted) {
               try {
-                unlinkSync6(join9(cwd2, f));
+                unlinkSync6(join10(cwd2, f));
               } catch {}
             }
             console.log(`captured ${written.length} written, ${deleted.length} deleted file(s):`);
@@ -3404,10 +3969,10 @@ ${mrSummary(pr)}`);
       case "git": {
         const sub = args[0];
         if (sub === "import") {
-          const gitPath = resolve3(cwd2, args[1] || die("usage: sol git import <git-repo> [dir]"));
-          const target = resolve3(cwd2, args[2] || basename(gitPath));
-          const fdir = join9(target, ".sol");
-          if (existsSync9(fdir))
+          const gitPath = resolve4(cwd2, args[1] || die("usage: sol git import <git-repo> [dir]"));
+          const target = resolve4(cwd2, args[2] || basename(gitPath));
+          const fdir = join10(target, ".sol");
+          if (existsSync10(fdir))
             die("already a sol repo: " + target);
           mkdirSync7(fdir, { recursive: true });
           const { commits, branches, head, current } = await importGitRepo(gitPath, fdir);
@@ -3417,20 +3982,20 @@ ${mrSummary(pr)}`);
           if (!refsBranches[current])
             refsBranches[current] = { head, base: head };
           refsBranches[current].head = head;
-          writeFileSync9(join9(fdir, "refs.json"), JSON.stringify({ current, branches: refsBranches, tags: {} }, null, 2));
+          writeFileSync9(join10(fdir, "refs.json"), JSON.stringify({ current, branches: refsBranches, tags: {} }, null, 2));
           const store = new Store2;
-          for (const name of readdirSync7(join9(fdir, "objects"))) {
+          for (const name of readdirSync7(join10(fdir, "objects"))) {
             if (name.endsWith(".tmp"))
               continue;
             try {
-              store.put(decodeObject(readFileSync9(join9(fdir, "objects", name))));
+              store.put(decodeObject(readFileSync9(join10(fdir, "objects", name))));
             } catch {}
           }
-          const onDisk = hydrate2(store, head, target);
+          const onDisk = hydrate3(store, head, target);
           console.log(`imported ${commits} commit(s), ${branches.length} branch(es) from git -> ${args[2] || basename(gitPath)} (${onDisk} files; on branch ${current})`);
         } else if (sub === "export") {
           const { log } = open();
-          const gitPath = resolve3(cwd2, args[1] || die('usage: sol git export <git-repo> [-m "msg"]'));
+          const gitPath = resolve4(cwd2, args[1] || die('usage: sol git export <git-repo> [-m "msg"]'));
           const mi = args.indexOf("-m");
           const store = loadStore();
           const head = await log.head() ?? "";
@@ -3470,6 +4035,10 @@ everyday (examples are copy-safe \u2014 use real filenames):
   sol ignore "*.tmp"             add an ignore pattern (no arg lists the active patterns)
   sol fsck / sol gc            verify integrity / drop unreachable objects
 
+privacy (native per-path encryption \u2014 the host only ever stores ciphertext):
+  sol seal secrets/.env alice    encrypt a file to recipients (you + alice); keys stay LOCAL, history is host-blind
+                                 \`sol cat\` decrypts for a recipient; everyone else sees <<sealed>>. (sol seal --help)
+
 branches & tags:
   sol branch                     list branches (sol branch feature creates one at HEAD)
   sol switch feature             switch to a branch (captures current work first, never loses it)
@@ -3486,6 +4055,7 @@ auth (sign in once; remote commands then use the cached token, no SOL_TOKEN need
 remotes (self-hostable backend; token in SOL_TOKEN or via sol auth login):
   sol clone [<url>] <owner>/<repo> [dir]   clone a remote repo (checks out PRODUCTION); default dir = <repo>
   sol push / sol pull          sync your commits with the remote (push registers your branch's head)
+  sol push <repo>                one-step share: no remote set? use the hosted Sol + <repo>, then push
   sol promote [branch]         point the remote's production branch at <branch> (default: current)
   sol remote <url> <repo>        set the remote (no arg: show it; url defaults to the hosted Sol)
   sol fork [<url>] <parent> <new> [dir]   make your own copy of a repo (all branches + history + a parent link)
@@ -3515,4 +4085,9 @@ addressed; history is a tamper-evident hash-chained op-log. attribute changes wi
     release?.();
   }
 }
-main().catch((e) => die(e?.message || String(e)));
+main().catch((e) => {
+  const msg = e?.message || String(e);
+  if (/ -> 401\b/.test(msg) || /\b401 unauthorized\b/i.test(msg))
+    authExpired();
+  die(msg);
+});