heyquilt 0.3.121 → 0.3.138

package/src/source-live/live-block.js

@@ -1,5 +1,5 @@
 // Quilt's side of seam: live squares in a Quilt session. Seam (src/quilts/) never imports this.
-// The folder side of a live square (plans/quilt-source-control/05): a block whose files mirror the
+// The folder side of a live square (Seam's plans/quilt-source-control/05): a block whose files mirror the
 // square's live document on the relay (live-square.js). Disk under the block is the snapshot at
 // `block.at` plus the overlay; every edit seen on disk goes into the live document at once, so the
 // relay always knows the square's uncommitted work, and every change another member of the square
@@ -9,18 +9,41 @@
 // It reuses the session's sync engine: the relay connection (connection.js: sign-in, passes, the
 // branch-document protocol), the relay's branch documents themselves, and the text diff into a
 // Y.Text (textdiff.js). There is no git: every change on disk is an edit (decision 18).
+//
+// In place (`inPlace`): a session's own folder becomes the block at the layout-3 switch (Seam's
+// plans/quilt-source-control/16: the first rebuild is a no-op, because the folder already equals
+// the square's live document). Nothing is checked out: the record is written beside the session's
+// state (.quilt/block.json), what disk holds is compared with the live document file by file, and
+// a difference is the person's edit (in it goes) unless the session says the folder was not
+// touched since it last synced (then the live document's newer version comes to disk). Paths the
+// session never syncs (`skip`) are never read or written. Reads can go through the relay
+// (`reader`), so a member needs no Seam sign-in to follow; uploads and commits are the member's.
 import fs from 'node:fs'
 import path from 'node:path'
 import * as Y from 'yjs'
 import { Connection, REMOTE } from '../connection.js'
+import { FEATURES } from '../protocol.js'
 import { applyTextDiff } from '../textdiff.js'
-import { blobId, under } from '../quilts/records.js'
-import { isText } from '../quilts/textdiff.js'
-import { checkout, findBlock, saveBlock, localChanges, BLOCK_DIR } from '../quilts/block.js'
+import { mergeAuto, mergeSmart } from '../merge3.js'
+// Seam's block folders and ids come from Seam's client package (@heyquilt/seam), never Seam's server code.
+import { blobId, under } from '@heyquilt/seam/lib/quilts/records.js'
+import { isText } from '@heyquilt/seam/lib/quilts/textdiff.js'
+import { checkout, findBlock, saveBlock, localChanges, conflictStyle, BLOCK_DIR } from '@heyquilt/seam/lib/quilts/block.js'
 import { liveKey, liveMaps, liveHead, entryOf, entryId, overlay } from './live-square.js'
 
 export const MAX_LIVE_TEXT = 2 * 1024 * 1024
 const SCAN_MS = 40
+// On macOS, Node's fs.watch shares one FSEvents stream per process and rebuilds it whenever a watch
+// is added or removed (another folder's block opening, this folder's next square after a merge), so
+// an edit in that gap is never delivered. The block looks at the folder this often too, as the
+// session does before the switch (session.js RECONCILE_MS).
+export const RECONCILE_MS = 1000
+// After a watcher starts, the folder is scanned again at these times (watch).
+const WATCH_SETTLE_MS = [250, 1000, 3000]
+// And this often the folder is brought in step with the square even with no news from the relay (a
+// write-out that failed, or one that never ran, is tried again): disk and square never disagree for
+// long, nor without a word (2026-11-01: a folder kept a file the square had deleted).
+export const STEP_MS = 15000
 
 const waitUntil = async (fn, ms = 10000, what = 'the relay') => {
   const t = Date.now()
@@ -40,10 +63,23 @@ export class LiveBlock {
    * @param {string[]} [o.paths]
    * @param {object} o.relay    { server, room, secret, name, identity, kind?, passes?, tool? }: the session
    */
-  constructor ({ dir, client, quilt, square, paths = [''], relay, api = '' }) {
-    Object.assign(this, { dir: path.resolve(dir), client, quilt, squareRef: square, paths, relayOpts: relay, api })
+  /**
+   * In place, also: `inPlace` { edited(path) }: whether the session saw the folder's copy change
+   * since it last synced it; `skip(path)`: the session never syncs it (`skipDir(path)`: nor
+   * anything in that folder); `record`: where block.json
+   * goes; `reader`: a client for reads (square, tree, blobs, diff), else `client`; `log`;
+   * `onEdits(list, doc, held)`: the edits this folder made, as each scan takes them into the live
+   * document `doc` ([{ path, kind: created|edited|deleted, detail, before?, after? }]), so the session
+   * keeps them on record (who changed what) as it did on its branch; `held()` resolves once the relay
+   * holds them.
+   */
+  constructor ({ dir, client, quilt, square, paths = [''], relay, api = '', inPlace = null, skip = null, skipDir = null, record = null, reader = null, log = null, onEdits = null, started = null, stepMs = STEP_MS }) {
+    Object.assign(this, { dir: path.resolve(dir), client, quilt, squareRef: square, paths, relayOpts: relay, api, inPlace, skip, skipDir, record, reader: reader || client, logFn: log, onEdits, stepMs })
+    // `started(block)`: told as it starts to open, so whoever waits for it can stop it part-way (abandon).
+    if (started) started(this)
     this.known = {} // path -> { blob, mode, size, mtimeMs }: what is on disk as this block last read or wrote it
     this.cache = new Map() // blob id -> bytes (the snapshot's files this block wrote out)
+    this.lastText = new Map() // path -> { id, text }: a live text as disk last had it (bytes no server holds), for combining (scan)
     this.queue = Promise.resolve()
     this.closed = false
     this.errors = []
@@ -57,6 +93,15 @@ export class LiveBlock {
   }
 
   async open () {
+    // A block that fails part-way lets go of what it opened: its relay connection would otherwise
+    // reconnect for good, one more with each try the folder makes to follow its square.
+    try { return await (this.inPlace ? this.openInPlace() : this.openCheckout()) } catch (err) {
+      this.abandon()
+      throw err
+    }
+  }
+
+  async openCheckout () {
     const found = findBlock(this.dir)
     if (found && found.dir === this.dir) this.block = found.block
     else {
@@ -67,29 +112,302 @@ export class LiveBlock {
     if (!b.square) throw new Error('a live block needs a square')
     b.live = liveKey(b.square)
     for (const [p, f] of Object.entries(b.files)) this.known[p] = { ...f }
-    saveBlock(this.dir, b)
+    this.save()
+    await this.connect()
+    await this.run(async () => { await this.scan(); await this.pull() })
+    this.watch()
+    return this
+  }
+
+  /** The relay connection on the square's live document, with its head set. */
+  async connect () {
+    const b = this.block
     this.roomDoc = new Y.Doc()
     this.doc = new Y.Doc()
     const r = this.relayOpts
-    this.conn = new Connection({ ...r, kind: r.kind || 'human', doc: this.roomDoc, branch: { key: b.live, doc: this.doc } })
+    // quilt-block: the relay counts it as part of the app's visit, not a visit of its own (the audit trail).
+    // Only the square's live document: the app's own connection has the room's (chat, tasks, activity).
+    this.conn = new Connection({ ...r, kind: r.kind || 'human', features: `${r.features || FEATURES},quilt-block`, roomDoc: false, doc: this.roomDoc, branch: { key: b.live, doc: this.doc } })
     this.conn.on('fatal', (err) => this.errors.push(err))
-    await this.conn.waitForSync()
-    await this.conn.waitForBranchSync()
+    // Stopped while it opens (the session stopped, or the folder moved on): its waits for the relay end with it.
+    const stopped = new Promise((resolve, reject) => { this.stopOpening = () => reject(new Error('the block was closed while it opened')) })
+    stopped.catch(() => {})
+    if (this.closed) this.stopOpening()
+    await Promise.race([this.conn.waitForSync(), stopped])
+    await Promise.race([this.conn.waitForBranchSync(), stopped])
     if (!liveHead(this.doc)) {
-      const sq = await this.client.square(b.quilt, b.square)
+      const sq = await this.reader.square(b.quilt, b.square)
       await this.conn.branchRequest({ op: 'start', branch: b.live, head: sq.head || sq.base })
       await waitUntil(() => liveHead(this.doc), 10000, 'the live head')
     }
     this.doc.on('update', (u, origin) => { if (origin === REMOTE && !this.closed) this.run(() => this.pull()) })
-    await this.run(async () => { await this.scan(); await this.pull() })
+  }
+
+  watch () {
     this.watcher = fs.watch(this.dir, { recursive: true }, (ev, name) => {
-      if (this.closed || !name || String(name).split(path.sep)[0] === BLOCK_DIR) return
+      if (this.closed || !name) return
+      const rel = String(name).split(path.sep).join('/')
+      if (rel.split('/')[0] === BLOCK_DIR || (this.skip && this.skip(rel))) return
       clearTimeout(this.scanTimer)
       this.scanTimer = setTimeout(() => this.run(() => this.scan()), SCAN_MS)
     })
+    this.reconcileTimer = setInterval(() => {
+      if (this.closed || this.reconciling) return
+      this.reconciling = true
+      this.run(() => this.scan()).catch(() => {}).finally(() => { this.reconciling = false })
+    }, RECONCILE_MS)
+    this.reconcileTimer.unref?.()
+    this.stepTimer = setInterval(() => { if (!this.closed) this.run(() => this.pull()).catch(() => {}) }, this.stepMs)
+    this.stepTimer.unref?.()
+    // A watcher just started does not hear everything at once (macOS's FSEvents takes a moment): a
+    // save in that moment would wait for the next change in the folder. Looked at again, to be sure.
+    this.settleTimers = WATCH_SETTLE_MS.map((ms) => {
+      const t = setTimeout(() => { if (!this.closed) this.run(() => this.scan()) }, ms)
+      t.unref?.()
+      return t
+    })
+  }
+
+  /**
+   * The block's record: Seam's .seam/block.json, or (in place) the file the session names, which
+   * also keeps what disk held as the block last read or wrote it (`known`): after a restart, a file
+   * that differs from it is an edit made while the app was closed, and any other difference is the
+   * square's newer version.
+   */
+  save () {
+    clearTimeout(this.saveTimer)
+    if (!this.record) return saveBlock(this.dir, this.block)
+    fs.mkdirSync(path.dirname(this.record), { recursive: true })
+    fs.writeFileSync(this.record + '.tmp', JSON.stringify({ ...this.block, known: this.known }))
+    fs.renameSync(this.record + '.tmp', this.record)
+  }
+
+  saveSoon () {
+    if (!this.record || this.saveTimer || this.closed) return
+    this.saveTimer = setTimeout(() => { this.saveTimer = null; try { this.save() } catch {} }, 2000)
+    this.saveTimer.unref?.()
+  }
+
+  /**
+   * The in-place record of an earlier run in this quilt: its `known`, or null. On this square (the
+   * app restarted), or on the branch's earlier square (a merge moved the folder on to the next one).
+   */
+  priorKnown () {
+    try {
+      const r = JSON.parse(fs.readFileSync(this.record, 'utf8'))
+      return r && r.inPlace && r.quilt === this.quilt && r.known && typeof r.known === 'object' ? r.known : null
+    } catch { return null }
+  }
+
+  /**
+   * The session's own folder as the block, nothing checked out (see the top of this file). What
+   * happened is logged: { same, taken, brought }, the files that matched, the person's edits that
+   * went in, and the live document's newer versions written to disk.
+   */
+  async openInPlace () {
+    const sq = await this.reader.square(this.quilt, this.squareRef)
+    const prior = this.inPlace.fresh ? null : this.priorKnown()
+    // Followed before (the app restarted, or the folder moved on to its branch's next square): edits
+    // are what changed since the block last saw the folder, not since the session's last sync, and
+    // a file only the square changed (its new head: what a merge took in from main) is the square's.
+    if (prior) this.inPlace = { ...this.inPlace, edited: (p, blob) => (blob ?? null) !== ((prior[p] && prior[p].blob) ?? null), base: null, baseBlob: (p) => (prior[p] && prior[p].blob) || null, seen: true }
+    this.block = { api: this.api, quilt: this.quilt, square: sq.id, square_short: sq.short || null, line: sq.line || null, paths: [''], at: null, head: null, files: {}, inPlace: true, live: liveKey(sq.id) }
+    await this.connect()
+    const head = this.head
+    const t = await this.reader.tree(this.quilt, `c:${head}`)
+    const b = this.block
+    for (const e of (t && t.entries) || []) b.files[e.path] = { blob: e.blob || null, mode: e.mode, size: e.size, ...(e.term ? { term: e.term } : {}) }
+    b.at = head
+    b.head = sq.head || null // a commit's expect_head: none while the square has no commit of its own (its live head is then its base)
+    this.save()
+    this.summary = await this.run(() => this.adopt())
+    this.watch()
     return this
   }
 
+  /** What the live document says `p` holds, as a blob id (null: absent), and whether it says so itself (not only by its head). */
+  wantedId (p) {
+    const e = entryOf(this.doc, p)
+    if (e) return { id: entryId(e), mode: e.op === 'delete' ? null : e.mode, named: true }
+    const s = this.block.files[p]
+    const m = liveMaps(this.doc)
+    return { id: s ? s.blob : null, mode: s ? s.mode : null, named: m.clean.has(p) }
+  }
+
+  /**
+   * In place, once: each file on disk against the live document. Equal: nothing to do. Different
+   * and the session saw the folder's copy change since it last synced, or, the first time the
+   * folder follows a square, a path the live document does not name that the folder's branch
+   * changed since it left main (`inPlace.own`, from git: in its commits, or not committed and not
+   * synced by the session, whose own changes are others' work too; without git: a file the folder
+   * has that the session never synced): the person's, which the scan after this takes in;
+   * when the square changed the same text since the session last synced it, both changes are
+   * combined first (combineAway). Otherwise the live document's version (another member's, since
+   * the folder's last sync, or the square's head) is written: a file the folder lacks, or has as git
+   * left it, is never taken for the person's deletion or edit (a folder whose git was behind main,
+   * a branch that left main before main's newer work, or a member back after the switch would
+   * undo main's work in the square, and on main at the next merge).
+   */
+  async adopt () {
+    const m = liveMaps(this.doc)
+    const firstLook = !this.inPlace.seen && !this.inPlace.fresh
+    const own = firstLook && this.inPlace.own ? await this.inPlace.own() : null
+    const disk = new Map(this.diskChanges({}).filter((c) => !this.skipped(c.path)).map((c) => [c.path, c]))
+    const paths = new Set([...disk.keys(), ...Object.keys(this.block.files), ...m.files.keys(), ...m.blobs.keys(), ...m.gone.keys(), ...m.clean.keys()])
+    const out = { same: 0, taken: [], brought: [], combined: [] }
+    for (const p of [...paths].sort()) {
+      if (this.skipped(p) || !this.block.paths.some((x) => under(p, x)) || (this.block.files[p] || {}).mode === 'gitlink' || (this.inPlace && this.nested(p))) continue
+      const d = disk.get(p)
+      const w = this.wantedId(p)
+      if (entryOf(this.doc, p) && this.staleCopy(p, d, own, firstLook)) {
+        await this.headStands(p, m)
+        out.brought.push(p)
+        continue
+      }
+      if ((d ? d.blob : null) === w.id) {
+        // The same bytes: a different mode on disk (made executable here) goes in as an edit too.
+        if (d) { const st = fs.lstatSync(path.join(this.dir, ...p.split('/'))); this.known[p] = w.mode && w.mode !== d.mode ? { blob: d.blob, mode: w.mode, size: -1, mtimeMs: -1 } : { blob: d.blob, mode: d.mode, size: st.size, mtimeMs: st.mtimeMs } }
+        out.same++
+        continue
+      }
+      // A file the session held back from this folder (someone else's box, or a change waiting for
+      // whoever held the file): the folder never had the session's copy, so lacking it is no deletion.
+      // The square's copy comes to disk (2026-11-01: a folder's first look deleted such a file).
+      if (firstLook && !d && w.id && this.inPlace.heldBack && this.inPlace.heldBack(p)) {
+        this.write(p, await this.wanted(p))
+        out.brought.push(p)
+        continue
+      }
+      const synced = !!(this.inPlace.synced && this.inPlace.synced(p))
+      const branchs = firstLook && !w.named && (own ? own.committed.has(p) || (own.uncommitted.has(p) && !synced) : !!d && !synced)
+      if (this.inPlace.edited(p, d ? d.blob : null) || branchs) {
+        // The square changed it too since the folder last had it (a merge while the app was closed):
+        // only the folder's own edit goes in, combined with the square's, never its old copy over it.
+        const merged = d && w.id ? await this.combineAway(p, d) : null
+        if (merged) { this.write(p, { bytes: merged, mode: d.mode }); out.combined.push(p) }
+        // The person's: the scan sees disk differ from this and takes it in (a deletion when disk has nothing).
+        if (w.id) this.known[p] = { blob: w.id, mode: w.mode, size: -1, mtimeMs: -1 }
+        out.taken.push(p)
+        continue
+      }
+      this.write(p, await this.wanted(p))
+      out.brought.push(p)
+    }
+    await this.scan()
+    this.save()
+    if (this.logFn && (out.taken.length || out.brought.length)) {
+      const list = (a) => `${a.slice(0, 5).join(', ')}${a.length > 5 ? `, and ${a.length - 5} more` : ''}`
+      this.logFn(`${out.same} file(s) already matched the square${out.taken.length ? `; ${out.taken.length} edit(s) of yours went in (${list(out.taken)})` : ''}${out.combined.length ? `, combined with the square's changes to them since this folder last synced (${list(out.combined)})` : ''}${out.brought.length ? `; ${out.brought.length} newer version(s) came from the square (${list(out.brought)})` : ''}.`)
+    }
+    return out
+  }
+
+  /**
+   * Whether the live document's entry for `p` is the branch's older copy of main's file, not work: in
+   * a square the move started at main's tip for want of the branch's own commit (`inPlace.atTip`), a
+   * full branch document names every file as the branch has it, and a file main changed (or deleted,
+   * or added) after the branch left it, that the branch never changed (git: not in its commits since
+   * it left main, nothing uncommitted here, no edit the session saw), would undo main's change at the
+   * square's merge. Only at the first look, with git to ask.
+   */
+  staleCopy (p, d, own, firstLook) {
+    if (!firstLook || !this.inPlace.atTip || !own) return false
+    if (own.committed.has(p) || own.uncommitted.has(p)) return false
+    return !this.inPlace.edited(p, d ? d.blob : null)
+  }
+
+  /** The square's head version of `p` stands: the live document's entry goes, and disk gets the head's file (or loses it). */
+  async headStands (p, m) {
+    const s = this.block.files[p]
+    this.write(p, s ? await this.headFile(p, s) : null)
+    this.doc.transact(() => {
+      m.files.delete(p); m.blobs.delete(p); m.gone.delete(p); m.modes.delete(p)
+      if (s) m.clean.set(p, { at: this.block.at }); else m.clean.delete(p)
+    })
+  }
+
+  /**
+   * The folder's copy of `p` (disk entry `d`) combined with the square's, against what the folder last
+   * had (the session's last sync of it, `inPlace.base`; after a restart, the blob the block last saw):
+   * the bytes to write, or null when there is nothing to combine (the square did not change it since,
+   * or that base is not known, or a side is not text). Where both changed the same lines, the folder's
+   * edit is kept (mergeAuto, the folder's side newer) and the square's lines it replaced are said.
+   */
+  async combineAway (p, d) {
+    if (!d.bytes || d.mode === 'symlink' || !isText(d.bytes)) return null
+    let base = this.inPlace.base ? await this.inPlace.base(p) : null
+    if (typeof base !== 'string' && this.inPlace.baseBlob) {
+      const id = this.inPlace.baseBlob(p)
+      if (id) { try { const b = await this.bytesOf(id); if (isText(b)) base = b.toString('utf8') } catch {} }
+    }
+    if (typeof base !== 'string') return null
+    const ours = d.bytes.toString('utf8')
+    // Someone else's box on it before the move (inPlace.boxed): the folder kept its own copy (git's,
+    // moved on by pulls) while the session held theirs, and `base` is what everyone had when the box
+    // began. Their change goes onto the folder's copy, never their whole older file over it.
+    const boxed = !!(this.inPlace.boxed && this.inPlace.boxed(p))
+    // The folder's copy is what it last had: nothing of its own to combine. It is taken as it is (an
+    // edit the session took in that the relay never held, a path the square does not name at the switch).
+    if (base === ours && !boxed) return null
+    const want = await this.wanted(p)
+    if (!want || want.mode === 'symlink' || !isText(want.bytes)) return null
+    const theirs = want.bytes.toString('utf8')
+    if (theirs === ours) return null
+    // A box on a file the folder never moved past: the box's work is the file now.
+    if (base === ours) return want.bytes
+    if (theirs === base) return null
+    const r = mergeAuto(base, ours, theirs, { oursNewer: true })
+    if (r.lost.length && this.logFn) this.logFn(`${p}: your edit made while away and the square's both changed the same lines; yours were kept, and the square's (${r.lost.reduce((n, x) => n + x.lines.length, 0)} line(s)) are in its history`)
+    return r.text === ours ? null : Buffer.from(r.text, 'utf8')
+  }
+
+  skipped (p) { return !!(this.skip && this.skip(p)) }
+
+  /** Whether `p` is inside a folder with a .git of its own (a submodule): never this block's to read or write. */
+  nested (p) {
+    const parts = p.split('/')
+    for (let i = 1; i < parts.length; i++) if (fs.existsSync(path.join(this.dir, ...parts.slice(0, i), '.git'))) return true
+    return false
+  }
+
+  /**
+   * What changed on disk against `files` (path -> { blob, mode, size, mtimeMs }), as Seam's
+   * localChanges answers. In place, the walk never enters a folder the session never syncs
+   * (`skipDir`: .git, .quilt with the git folder set aside in it, node_modules, ignored ones), so a
+   * big folder is not read on every scan, nor one that is a repository of its own (a submodule).
+   */
+  diskChanges (files) {
+    if (!this.inPlace) return localChanges(this.dir, { paths: this.block.paths, files })
+    const out = []
+    const seen = new Set()
+    const visit = (rel) => {
+      let names
+      try { names = fs.readdirSync(path.join(this.dir, rel), { withFileTypes: true }) } catch { return }
+      for (const d of names) {
+        const r = rel ? `${rel}/${d.name}` : d.name
+        if (d.name === '.git' || d.name === BLOCK_DIR) continue
+        // A folder with a .git of its own (a submodule, a repository inside this one) is its own: the square holds it as a gitlink at most.
+        if (d.isDirectory()) { if (!(this.skipDir && this.skipDir(r)) && !fs.existsSync(path.join(this.dir, r, '.git'))) visit(r); continue }
+        if (!(d.isFile() || d.isSymbolicLink()) || this.skipped(r)) continue
+        const abs = path.join(this.dir, r)
+        let st
+        try { st = fs.lstatSync(abs) } catch { continue }
+        seen.add(r)
+        const k = files[r]
+        if (k && k.size === st.size && k.mtimeMs === st.mtimeMs) continue
+        let bytes
+        try { bytes = st.isSymbolicLink() ? Buffer.from(fs.readlinkSync(abs)) : fs.readFileSync(abs) } catch { continue }
+        const mode = st.isSymbolicLink() ? 'symlink' : (st.mode & 0o111) && process.platform !== 'win32' ? 'exec' : 'file'
+        const id = blobId(bytes)
+        if (k && k.blob === id && k.mode === mode) continue
+        out.push({ path: r, status: k ? 'modified' : 'added', blob: id, mode, size: bytes.length, bytes })
+      }
+    }
+    visit('')
+    for (const p of Object.keys(files)) if (!seen.has(p) && !this.skipped(p) && !this.nested(p)) out.push({ path: p, status: 'deleted' })
+    return out.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
+  }
+
   get head () { return liveHead(this.doc) }
   get by () { return this.relayOpts.name || '' }
 
@@ -98,48 +416,142 @@ export class LiveBlock {
     if (this.block.at !== this.head) return // 05: no ingest against the wrong base; pull re-projects first
     const m = liveMaps(this.doc)
     const snap = this.block.files
-    const changes = localChanges(this.dir, { paths: this.block.paths, files: this.known })
+    let changes = this.diskChanges(this.known)
+    // What the session never syncs is never taken in; noting its size and time spares reading it again.
+    for (const c of changes) {
+      if (!this.skipped(c.path)) continue
+      if (c.status === 'deleted') { delete this.known[c.path]; continue }
+      try { const st = fs.lstatSync(path.join(this.dir, ...c.path.split('/'))); this.known[c.path] = { blob: c.blob, mode: c.mode, size: st.size, mtimeMs: st.mtimeMs } } catch {}
+    }
+    changes = changes.filter((c) => !this.skipped(c.path))
     if (!changes.length) return
-    const uploads = []
+    let uploads = []
     for (const c of changes) {
       if (c.status === 'deleted') continue
       if (c.mode === 'symlink' || !isText(c.bytes) || c.bytes.length > MAX_LIVE_TEXT) uploads.push({ kind: 'blob', id: c.blob, bytes: c.bytes })
     }
-    if (uploads.length) await this.client.upload(this.block.quilt, uploads)
+    if (uploads.length) {
+      // A binary needs Seam to hold its bytes first, as this member. Without that, the texts still go in, and the binaries wait for the next scan.
+      try {
+        if (!this.client) throw new Error('sign in to Seam (quilt login) so binary files reach the square')
+        await this.client.upload(this.block.quilt, uploads)
+        this.problem = null
+      } catch (err) {
+        const ids = new Set(uploads.map((u) => u.id))
+        const waiting = changes.filter((c) => c.status !== 'deleted' && ids.has(c.blob)).map((c) => c.path)
+        this.problem = `${waiting.length} binary file(s) are not in the square yet (${waiting.slice(0, 3).join(', ')}): ${err.message}`
+        if (this.logFn) this.logFn(this.problem)
+        changes = changes.filter((c) => !waiting.includes(c.path))
+        uploads = []
+      }
+    }
+    // What each file held before, for the record of who changed what (onEdits): the live document's text, else the head's.
+    const before = new Map()
+    if (this.onEdits) {
+      for (const c of changes) {
+        const t = m.files.get(c.path)
+        if (t) { before.set(c.path, t.toString()); continue }
+        const b = snap[c.path]
+        if (!b || !b.blob || m.blobs.has(c.path) || m.gone.has(c.path) || (b.size || 0) > MAX_LIVE_TEXT) continue
+        try { const bytes = await this.bytesOf(b.blob); if (isText(bytes)) before.set(c.path, bytes.toString('utf8')) } catch {}
+      }
+    }
+    // A file changed on disk and in the square since disk last had it (someone's edit, or main brought in,
+    // reached the live document or the head before this edit was read): what disk last had is the base
+    // the two are combined against, so the edit goes in as a change and nothing the square has is undone.
+    const both = new Map()
+    for (const c of changes) {
+      if (c.status === 'deleted' || c.mode === 'symlink' || c.bytes.length > MAX_LIVE_TEXT || !isText(c.bytes)) continue
+      const k = this.known[c.path]
+      if (!k || !k.blob || k.blob === c.blob) continue
+      const e = entryOf(this.doc, c.path)
+      const s = snap[c.path]
+      const now = e ? entryId(e) : s && s.mode !== 'conflict' ? s.blob : null
+      if (!now || now === k.blob) continue
+      try {
+        const last = this.lastText.get(c.path)
+        const base = last && last.id === k.blob ? last.text : (await this.bytesOf(k.blob)).toString('utf8')
+        const head = e ? null : (await this.bytesOf(s.blob))
+        if (head && !isText(head)) continue
+        both.set(c.path, { base, head: head ? head.toString('utf8') : null })
+      } catch {}
+    }
+    const taken = []
+    const rewrite = []
     this.doc.transact(() => {
       for (const c of changes) {
         const p = c.path
         const base = snap[p]
+        const had = !!(base && !m.gone.has(p)) || m.files.has(p) || m.blobs.has(p)
+        // Whose work this path is now (on going back to git, its box is theirs: Session.leaveSquare), and the
+        // head it was made on: the relay combines an edit made on a head it has moved on from (bring-in.js lateEdits).
+        m.writers.set(p, { by: this.by, ts: Date.now(), at: this.block.at })
         if (c.status === 'deleted') {
           if (base) { m.clean.delete(p); m.gone.set(p, { by: this.by, ts: Date.now() }) } else m.clean.set(p, { at: this.block.at })
           delete this.known[p]
+          if (had) taken.push({ path: p, kind: 'deleted', detail: '', ...(before.has(p) ? { before: before.get(p), after: '' } : {}) })
           continue
         }
-        if (base && base.blob === c.blob && base.mode === c.mode) { m.clean.set(p, { at: this.block.at }); m.gone.delete(p) } else if (uploads.some((u) => u.id === c.blob)) {
+        const kind = had ? 'edited' : 'created'
+        if (base && base.blob === c.blob && base.mode === c.mode) {
+          m.clean.set(p, { at: this.block.at }); m.gone.delete(p)
+          // Back as the head has it: an edit too (undoing one), unless it never left.
+          if (before.has(p) && before.get(p) !== c.bytes.toString('utf8')) taken.push({ path: p, kind, detail: '', before: before.get(p), after: c.bytes.toString('utf8') })
+        } else if (uploads.some((u) => u.id === c.blob)) {
           m.clean.delete(p); m.gone.delete(p)
           m.blobs.set(p, { blob: c.blob, size: c.bytes.length, mode: c.mode })
+          taken.push({ path: p, kind, detail: `${c.bytes.length} bytes` })
         } else {
           m.clean.delete(p); m.gone.delete(p); m.blobs.delete(p)
           let t = m.files.get(p)
+          const fresh = !t
           if (!t) { t = new Y.Text(); m.files.set(p, t) }
-          applyTextDiff(t, c.bytes.toString('utf8'))
+          let after = c.bytes.toString('utf8')
+          const w = both.get(p)
+          const cur = w ? (fresh ? w.head : t.toString()) : null
+          if (w && cur !== null && cur !== w.base && cur !== after) {
+            const r = mergeSmart(w.base, after, cur)
+            // The same lines changed on both sides: the newer edit, this one, wins them (as everywhere in Quilt).
+            after = r.conflicts.length ? mergeAuto(w.base, after, cur, { oursNewer: true }).text : r.text
+            if (after !== c.bytes.toString('utf8')) rewrite.push({ path: p, bytes: Buffer.from(after, 'utf8'), mode: c.mode })
+          }
+          let detail = applyTextDiff(t, after)
+          this.lastText.set(p, { id: blobId(Buffer.from(after, 'utf8')), text: after })
+          // A file new to the live document took its whole text: what changed is measured from the head's.
+          if (fresh && before.has(p)) { const probe = new Y.Doc().getText(); probe.insert(0, before.get(p)); detail = applyTextDiff(probe, after) }
           if (c.mode === 'exec') m.modes.set(p, 'exec'); else if (m.modes.has(p)) m.modes.delete(p)
+          if (detail || !had) taken.push({ path: p, kind, detail, before: before.get(p) ?? '', after })
         }
         const st = fs.lstatSync(path.join(this.dir, ...p.split('/')))
         this.known[p] = { blob: c.blob, mode: c.mode, size: st.size, mtimeMs: st.mtimeMs }
       }
     })
+    // Disk gets the combination: what the square had that this edit was not made on.
+    for (const x of rewrite) this.write(x.path, x)
+    this.saveSoon()
+    if (this.onEdits && taken.length) { try { this.onEdits(taken, this.doc, () => this.conn.confirmBranch()) } catch (err) { if (this.logFn) this.logFn(`could not record ${taken.length} edit(s): ${err.message}`) } }
   }
 
   /** Bytes of a blob, from this block's cache or the server. */
   async bytesOf (id) {
     if (!this.cache.has(id)) {
-      const { blobs } = await this.client.blobs(this.block.quilt, [id])
+      const { blobs } = await this.reader.blobs(this.block.quilt, [id])
       this.cache.set(id, Buffer.from(blobs[id], 'base64'))
     }
     return this.cache.get(id)
   }
 
+  /**
+   * The head's file `s` (block.files) at `p` as disk holds it: { bytes, mode }. A conflict Seam keeps in
+   * the square (a term: a rebase or merge that did not combine) has no bytes of its own: it is written
+   * with its markers, as Seam's own folders write it, and settled by editing them out and committing.
+   */
+  async headFile (p, s, rev = `c:${this.block.at}`) {
+    if (s.mode !== 'conflict') return { bytes: await this.bytesOf(s.blob), mode: s.mode }
+    const r = await this.reader.cat(this.block.quilt, rev, p, { format: conflictStyle() })
+    return { bytes: Buffer.from((r && r.content) || '', 'base64'), mode: 'file' }
+  }
+
   /** What disk should hold at `p`: { bytes, mode } or null (absent). */
   async wanted (p) {
     const e = entryOf(this.doc, p)
@@ -147,12 +559,12 @@ export class LiveBlock {
     if (e && e.bytes) return { bytes: e.bytes, mode: e.mode }
     if (e && e.blob) return { bytes: await this.bytesOf(e.blob), mode: e.mode }
     const s = this.block.files[p]
-    return s ? { bytes: await this.bytesOf(s.blob), mode: s.mode } : null
+    return s ? this.headFile(p, s) : null
   }
 
   write (p, want) {
     const abs = path.join(this.dir, ...p.split('/'))
-    if (!want) { fs.rmSync(abs, { force: true }); delete this.known[p]; return }
+    if (!want) { fs.rmSync(abs, { force: true }); delete this.known[p]; this.lastText.delete(p); return }
     fs.mkdirSync(path.dirname(abs), { recursive: true })
     const tmp = path.join(path.dirname(abs), `.${path.basename(abs)}.quilt-tmp`)
     if (want.mode === 'symlink') { fs.rmSync(abs, { force: true }); fs.symlinkSync(want.bytes.toString('utf8'), abs) } else {
@@ -161,6 +573,9 @@ export class LiveBlock {
     }
     const st = fs.lstatSync(abs)
     this.known[p] = { blob: blobId(want.bytes), mode: want.mode, size: st.size, mtimeMs: st.mtimeMs }
+    if (this.doc && liveMaps(this.doc).files.has(p) && want.bytes.length <= MAX_LIVE_TEXT) this.lastText.set(p, { id: this.known[p].blob, text: want.bytes.toString('utf8') })
+    else this.lastText.delete(p)
+    this.saveSoon()
   }
 
   /** Moves the block to the document's head (a commit by anyone in the square), then writes the overlay out. */
@@ -170,32 +585,51 @@ export class LiveBlock {
     await this.scan() // an edit not yet ingested is merged in before a remote change is written over it
     const m = liveMaps(this.doc)
     const paths = new Set([...m.files.keys(), ...m.blobs.keys(), ...m.gone.keys(), ...m.clean.keys()])
+    // One file that can't be written out (its bytes not readable, the disk refusing) never holds up the
+    // others, and is said (outOfStep, in the folder's status), then tried again (STEP_MS).
+    const failed = []
     for (const p of paths) {
-      if (!this.block.paths.some((x) => under(p, x))) continue
-      const want = await this.wanted(p)
-      const id = want ? blobId(want.bytes) : null
-      const have = this.known[p] ? this.known[p].blob : null
-      if (id !== have || (want && this.known[p].mode !== want.mode)) this.write(p, want)
+      if (!this.block.paths.some((x) => under(p, x)) || this.skipped(p) || (this.inPlace && this.nested(p))) continue
+      try {
+        const want = await this.wanted(p)
+        const id = want ? blobId(want.bytes) : null
+        const have = this.known[p] ? this.known[p].blob : null
+        if (id !== have || (want && this.known[p].mode !== want.mode)) this.write(p, want)
+      } catch (err) { failed.push({ path: p, err }) }
     }
+    this.noteOutOfStep(failed)
+  }
+
+  /** What a write-out could not bring in step, said once while it lasts (and when it is over). */
+  noteOutOfStep (failed) {
+    const was = this.outOfStep || null
+    this.outOfStep = failed.length ? `${failed.length} file(s) here are not as the square has them yet (${failed.slice(0, 3).map((f) => f.path).join(', ')}${failed.length > 3 ? ', …' : ''}): ${String(failed[0].err && failed[0].err.message || failed[0].err).slice(0, 200)}` : null
+    if (this.logFn && this.outOfStep && this.outOfStep !== was) this.logFn(this.outOfStep)
+    if (this.logFn && was && !this.outOfStep) this.logFn('every file here is as the square has it again.')
   }
 
   /** 05 "Moving block.at": rewrites the files that are Quilt's; files in the overlay are the holder's and stay. */
   async reproject (to) {
     const b = this.block
-    const d = await this.client.diff(b.quilt, { from: `c:${b.at}`, to: `c:${to}`, paths: b.paths, format: 'names' })
-    const t = d.files.length ? await this.client.tree(b.quilt, `c:${to}`, b.paths) : { entries: [] }
+    const d = await this.reader.diff(b.quilt, { from: `c:${b.at}`, to: `c:${to}`, paths: b.paths, format: 'names' })
+    const t = d.files.length ? await this.reader.tree(b.quilt, `c:${to}`, b.paths) : { entries: [] }
     const byPath = new Map(t.entries.map((e) => [e.path, e]))
-    const local = new Set(localChanges(this.dir, { paths: b.paths, files: this.known }).map((c) => c.path))
+    const local = new Set(this.diskChanges(this.known).map((c) => c.path))
     for (const f of d.files) {
       const e = byPath.get(f.path)
-      if (e) b.files[f.path] = { blob: e.blob, mode: e.mode, size: e.size }
+      if (e) b.files[f.path] = { blob: e.mode === 'conflict' ? null : e.blob, mode: e.mode, size: e.size, ...(e.term ? { term: e.term } : {}) }
       else delete b.files[f.path]
-      if (entryOf(this.doc, f.path) || local.has(f.path)) continue
-      this.write(f.path, e ? { bytes: await this.bytesOf(e.blob), mode: e.mode } : null)
+      if (entryOf(this.doc, f.path) || local.has(f.path) || this.skipped(f.path) || (this.inPlace && this.nested(f.path))) continue
+      // Already on disk as the new head has it (the commit was made from this very work): left alone.
+      const k = this.known[f.path]
+      if (e ? k && e.mode !== 'conflict' && k.blob === e.blob && k.mode === e.mode : !k) continue
+      this.write(f.path, e ? await this.headFile(f.path, b.files[f.path], `c:${to}`) : null)
     }
     b.at = to
-    b.head = to
-    saveBlock(this.dir, b)
+    // A square with no commit of its own (a rebase only moved its base): a commit's expect_head is none.
+    const rec = this.doc.getMap('live').get('head') || {}
+    b.head = rec.commit === to && rec.base ? null : to
+    this.save()
   }
 
   /** Every disk change in, and the relay holding all of it. */
@@ -216,10 +650,13 @@ export class LiveBlock {
    * then the relay moves the head and drops what was committed (live-square.js `seal`).
    */
   async commit ({ message = '' } = {}) {
+    if (!this.client) throw new Error('sign in to Seam first (quilt login, or set SEAM_TOKEN): a commit is made as you')
     await this.flush()
     return this.run(async () => {
       const head = this.head
-      const list = overlay(this.doc)
+      // An untracked file this folder never syncs (ignored, or a Quilt built-in) is never committed, even if
+      // the live document names it (a square from before 0.3.135's switch took agents' scratch files in).
+      const list = overlay(this.doc).filter((e) => !(this.skipped(e.path) && !this.block.files[e.path]))
       if (!list.length) return { nothing: true }
       const uploads = list.filter((e) => e.bytes).map((e) => ({ kind: 'blob', id: blobId(e.bytes), bytes: e.bytes }))
       if (uploads.length) await this.client.upload(this.block.quilt, uploads)
@@ -233,17 +670,52 @@ export class LiveBlock {
     })
   }
 
+  /**
+   * The square's head moved on Seam itself (a rebase, a settled conflict, a merge that kept its
+   * conflict in the square): the relay moves the live document onto it, each live file the move
+   * changed combined with it (source-live/bring-in.js), and the folder is re-projected onto it.
+   * `base`: the square has no commit of its own, and `head` is its new base.
+   */
+  async moveTo (head, { base = false } = {}) {
+    await this.flush()
+    return this.run(async () => {
+      const was = this.head
+      if (!head || head === was) return { moved: false }
+      await this.conn.branchRequest({ op: 'live-move', branch: this.block.live, prev: was, head, ...(base ? { base: true } : {}) })
+      await waitUntil(() => this.head === head, 10000, 'the moved head')
+      await this.reproject(head)
+      return { moved: true, head }
+    })
+  }
+
   /** Merges the square into a line (07), after sealing anything uncommitted. */
   async merge ({ into = 'main', message } = {}) {
     await this.commit({ message: message || 'Work in progress' })
     return this.client.merge(this.block.quilt, into, { square: this.block.square, expect_head: this.block.head, ...(message ? { message } : {}) })
   }
 
+  /** Stops the block without saving its record: it never opened (open failed part-way). */
+  abandon () {
+    this.closed = true
+    if (this.stopOpening) this.stopOpening()
+    clearTimeout(this.scanTimer)
+    clearTimeout(this.saveTimer)
+    clearInterval(this.reconcileTimer)
+    clearInterval(this.stepTimer)
+    for (const t of this.settleTimers || []) clearTimeout(t)
+    if (this.watcher) this.watcher.close()
+    if (this.conn) this.conn.close()
+  }
+
   async close () {
     this.closed = true
     clearTimeout(this.scanTimer)
+    clearInterval(this.reconcileTimer)
+    clearInterval(this.stepTimer)
+    for (const t of this.settleTimers || []) clearTimeout(t)
     if (this.watcher) this.watcher.close()
     await this.queue.catch(() => {})
+    if (this.record && this.block && this.block.at) { try { this.save() } catch {} }
     if (this.conn) this.conn.close()
   }
 }