heyquilt 0.3.122 → 0.3.138

package/src/session-follow.js

@@ -1,18 +1,42 @@
-// Quilt's side of Seam (plans/quilt-source-control/16, "How a session becomes a quilt"): once a
+// Quilt's side of Seam (Seam's plans/quilt-source-control/16, "How a session becomes a quilt"): once a
 // session is switched to layout 3 (session-layout3.js), each branch's live work is a square's live
 // document on the relay (`quilt/<square>`), and a folder follows it through a live block
 // (source-live/live-block.js): its files mirror the square, every edit goes into the live document.
 //
-// SquareFollower is that link for one Session: `follow({ dir, client })` opens the block for the
-// session's branch, and the relay's `quilt` message (switched back, square moved) or the session
-// stopping closes it. Nothing here runs unless QUILT_SOURCE_URL is set and the relay says the
-// session is a quilt at layout 3, so GitHub-backed sessions never reach it.
+// SquareFollower is that link for one Session. The session's own folder follows its branch's square
+// in place, by itself, as soon as the relay says the session is a layout-3 quilt (`onQuilt`): the
+// folder already equals the square's live document (the switch copied the branch document into it
+// and checked), so nothing is checked out; the session's branch-document sync and git-mode upstream
+// work stop for the folder (Session.enterSquare) and the block takes over. When the relay says the
+// session went back (layout 2), or the branch's square changed, the block closes and the old sync
+// resumes (Session.leaveSquare). `follow({ dir, client })` also opens a block in a SEPARATE folder
+// (`quilt session follow <folder>`). Nothing here runs with Seam off for the app (seam-url.js) or for
+// a session the relay does not say is a quilt at layout 3, so GitHub-backed sessions never reach it.
+//
+// In a quilt, agents see no git and no GitHub at all: it is all Seam. So while the folder follows its
+// square, its .git (a folder, or a worktree's pointer file) is set aside in .quilt/git-before-seam with
+// one rename, and git there answers "not a git repository"; going back to layout 2 puts it back before
+// git-mode sync resumes, and a restart while following keeps it aside. It is never deleted.
+import fs from 'node:fs'
 import path from 'node:path'
+import * as Y from 'yjs'
 import { FEATURES } from './protocol.js'
 import { openLiveBlock } from './source-live/live-block.js'
+import { appSeamUrl } from './seam-url.js'
+import { lastWriters } from './source-live/live-square.js'
+import { broughtOf } from './source-live/bring-in.js'
+import { catchUpWords } from './ui/seam-model.js'
+import { QUILT_MOVE_TIMEOUT_MS } from './connection.js'
+import { squareShort } from '@heyquilt/seam/lib/quilts/errors.js'
 
 const LAYOUT_QUILT = 3
 const PREFIX = 'quilt/'
+// A folder whose block could not open (the relay or Seam did not answer) tries again this often, its sync still held.
+const RETRY_MS = 30 * 1000
+// The files of the square's uncommitted work that status lists (the count is all of them).
+const WORK_LISTED = 50
+// How often a folder asks whether main moved past its square's base (catchUp), besides when the relay says something of the quilt.
+export const CATCH_UP_MS = Number(process.env.QUILT_CATCH_UP_MS) || 60 * 1000
 
 /** The square the folder on `branch` follows: `{ square, key }`, or null while the session is not a layout-3 quilt. */
 export function squareFor (quilt, branch) {
@@ -22,19 +46,243 @@ export function squareFor (quilt, branch) {
   return { square: key.slice(PREFIX.length), key }
 }
 
-const withQuilts = (f) => (String(f || FEATURES).split(',').includes('quilts') ? String(f || FEATURES) : `${f || FEATURES},quilts`)
+export const GIT_ASIDE = path.join('.quilt', 'git-before-seam')
+
+/** The folder's .git set aside while it follows its square: { branch, at, kind } (from its note), or null. */
+export function gitAsideOf (root) {
+  const aside = path.join(root, GIT_ASIDE)
+  try { fs.lstatSync(aside) } catch { return null }
+  try { return JSON.parse(fs.readFileSync(`${aside}.json`, 'utf8')) } catch { return { branch: null } }
+}
+
+// Written into a worktree's admin folder in its repository (git worktree lock) while its .git is aside.
+const LOCK_REASON = 'Quilt: this worktree follows a Seam square, with its .git set aside in .quilt/git-before-seam; Quilt unlocks it when git comes back.\n'
+
+/** Where a worktree's .git file points (its repository's .git/worktrees/<name>), or null. */
+function worktreeAdmin (gitFile) {
+  try {
+    const m = /^gitdir:\s*(.+)$/m.exec(fs.readFileSync(gitFile, 'utf8'))
+    return m ? path.resolve(path.dirname(gitFile), m[1].trim()) : null
+  } catch { return null }
+}
+
+/** The other worktrees of the repository whose .git folder is `gitFolder` that are still there: their folders. */
+export function otherWorktrees (gitFolder) {
+  let names
+  try { names = fs.readdirSync(path.join(gitFolder, 'worktrees')) } catch { return [] }
+  const out = []
+  for (const n of names.sort()) {
+    try {
+      const dot = fs.readFileSync(path.join(gitFolder, 'worktrees', n, 'gitdir'), 'utf8').trim()
+      if (dot && fs.existsSync(dot)) out.push(path.dirname(dot))
+    } catch {}
+  }
+  return out
+}
+
+const real = (p) => { try { return fs.realpathSync(p) } catch { return path.resolve(p) } }
+
+/**
+ * The folder's own linked worktrees (`git worktree add`, in the folder or anywhere else): each one's
+ * .git pointer file names `<.git>/worktrees/<name>`, so moving the .git would leave them answering
+ * "not a git repository". [{ file, was, name }] for each pointer that names this .git.
+ */
+function linkedWorktrees (gitDir) {
+  let names = []
+  try { names = fs.readdirSync(path.join(gitDir, 'worktrees')) } catch { return [] }
+  const out = []
+  for (const name of names) {
+    const admin = path.join(gitDir, 'worktrees', name)
+    try {
+      let file = fs.readFileSync(path.join(admin, 'gitdir'), 'utf8').trim()
+      if (!path.isAbsolute(file)) file = path.resolve(admin, file)
+      // A worktree that follows a square too has its pointer set aside in its own .quilt.
+      for (const at of pointerPlaces(file)) {
+        let was
+        try { was = fs.readFileSync(at, 'utf8') } catch { continue }
+        const m = /^gitdir:\s*(.+?)\s*$/m.exec(was)
+        if (m && real(path.resolve(path.dirname(file), m[1])) === real(admin)) out.push({ file, was, name })
+        break
+      }
+    } catch {}
+  }
+  return out
+}
+
+/** Where a worktree's .git pointer file is: at its .git, or set aside (it follows a square too). */
+const pointerPlaces = (file) => [file, path.join(path.dirname(file), GIT_ASIDE)]
+
+/**
+ * Rewrites a worktree's .git pointer file in place, wherever it is now (pointerPlaces), when `was(text)`
+ * says it is the one expected: through an open handle, never by making the file anew, so a worktree
+ * that sets its own .git aside meanwhile (both follow squares, at once) finds it in its .quilt and
+ * not a new .git in its folder. Whether it wrote.
+ */
+function rewritePointer (file, text, was) {
+  for (const at of pointerPlaces(file)) {
+    let fd
+    try { if (!fs.statSync(at).isFile()) continue; fd = fs.openSync(at, 'r+') } catch { continue }
+    try {
+      if (!was(fs.readFileSync(fd, 'utf8'))) return false
+      fs.ftruncateSync(fd, 0)
+      fs.writeSync(fd, text, 0)
+      return true
+    } catch { return false } finally { fs.closeSync(fd) }
+  }
+  return false
+}
+
+/**
+ * Sets the folder's .git aside (one rename into .quilt): { moved, already?, both?, locked?, worktrees? }.
+ * A .git kept aside from before (a restart while following) stays where it is; a new .git made
+ * meanwhile is left alone (both: true), never moved over the one aside. A worktree's .git file
+ * points into its repository: that worktree is locked there meanwhile (locked: true), so git in the
+ * repository never prunes it as gone. A repository's other worktrees share its .git folder: their
+ * .git files are pointed at it where it is now (and back as they were with it, putGitBack), so
+ * they keep working; `worktrees` names their folders.
+ */
+export function setGitAside (root, { branch = null } = {}) {
+  const git = path.join(root, '.git')
+  const aside = path.join(root, GIT_ASIDE)
+  let st = null
+  try { st = fs.lstatSync(git) } catch {}
+  if (gitAsideOf(root)) return { moved: false, already: true, ...(st ? { both: true } : {}) }
+  if (!st) return { moved: false }
+  const kind = st.isDirectory() ? 'folder' : 'file'
+  const admin = kind === 'file' ? worktreeAdmin(git) : null
+  let locked = null
+  if (admin && fs.existsSync(admin) && !fs.existsSync(path.join(admin, 'locked'))) {
+    fs.writeFileSync(path.join(admin, 'locked'), LOCK_REASON)
+    locked = admin
+  }
+  const worktrees = kind === 'folder' ? otherWorktrees(git) : []
+  const linked = kind === 'folder' ? linkedWorktrees(git) : []
+  fs.mkdirSync(path.dirname(aside), { recursive: true })
+  fs.writeFileSync(`${aside}.json`, JSON.stringify({ branch, at: new Date().toISOString(), kind, ...(locked ? { locked } : {}), ...(linked.length ? { worktrees: linked.map(({ file, was }) => ({ file, was })) } : {}) }))
+  try { fs.renameSync(git, aside) } catch (err) {
+    if (locked) fs.rmSync(path.join(locked, 'locked'), { force: true })
+    fs.rmSync(`${aside}.json`, { force: true })
+    throw err
+  }
+  for (const w of linked) rewritePointer(w.file, `gitdir: ${path.join(real(aside), 'worktrees', w.name)}\n`, (now) => now === w.was)
+  return { moved: true, ...(locked ? { locked: true } : {}), ...(worktrees.length ? { worktrees } : {}) }
+}
+
+/** Puts the .git set aside back (one rename): true when it did; false with nothing aside, or with a new .git in the way (both kept). */
+export function putGitBack (root) {
+  const git = path.join(root, '.git')
+  const aside = path.join(root, GIT_ASIDE)
+  const note = gitAsideOf(root)
+  if (!note) return false
+  try { fs.lstatSync(git); return false } catch {}
+  fs.renameSync(aside, git)
+  // Its linked worktrees' pointers, as they were (one changed since is left as it is).
+  for (const w of note.worktrees || []) rewritePointer(w.file, w.was, (now) => now.includes(GIT_ASIDE))
+  fs.rmSync(`${aside}.json`, { force: true })
+  // The lock this set, and only that one (someone may have locked the worktree since, for their own reason):
+  // where it was set, or where its repository's .git is now (set aside meanwhile, its pointer says).
+  if (note.locked) {
+    for (const admin of new Set([note.locked, worktreeAdmin(git)].filter(Boolean))) {
+      const lock = path.join(admin, 'locked')
+      try { if (fs.readFileSync(lock, 'utf8') === LOCK_REASON) fs.rmSync(lock, { force: true }) } catch {}
+    }
+  }
+  return true
+}
+
+// The branch document's maps keyed by path (Session.bindBranchDoc): what a file's change touches.
+const PATH_MAPS = ['files', 'blobs', 'gone', 'modes']
+
+/**
+ * The paths of branch document `doc` with changes the relay does not hold (its state vector `sv`,
+ * and `deleted`, an update of its deletions, both encoded): at layout 3, edits the read-only
+ * document refused (they reached it after the switch) or never got (the app was offline). A change
+ * that only deleted text counts too: Yjs keeps deletions apart from the state vector, so the relay's
+ * own are compared.
+ */
+export function unsentPaths (doc, sv, deleted) {
+  const out = new Set()
+  const held = Y.decodeStateVector(sv)
+  const gone = Y.decodeUpdate(deleted).ds.clients
+  const past = (item) => item.id.clock + item.length > (held.get(item.id.client) || 0)
+  const goneThere = (item) => (gone.get(item.id.client) || []).some((d) => d.clock <= item.id.clock && item.id.clock + item.length <= d.clock + d.len)
+  const touched = (item) => past(item) || (item.deleted && !goneThere(item))
+  for (const name of PATH_MAPS) {
+    for (const [p, item] of doc.getMap(name)._map) {
+      if (touched(item)) { out.add(p); continue }
+      const type = item.content && item.content.type
+      if (!(type instanceof Y.Text)) continue
+      for (let it = type._start; it; it = it.right) if (touched(it)) { out.add(p); break }
+    }
+  }
+  return out
+}
+
+const withQuilts =(f) => (String(f || FEATURES).split(',').includes('quilts') ? String(f || FEATURES) : `${f || FEATURES},quilts`)
+
+/** The one line the app and quilt_status show for a folder that follows its square. */
+export function squareLine ({ square, quilt, problem = '', opening = false }) {
+  const short = squareShort(square || '')
+  const name = (quilt && (quilt.slug || quilt.id)) || 'the quilt'
+  if (problem) return `This folder's work belongs in square ${short} of ${name}, but it can't follow it yet (${problem}); Quilt tries again by itself, and nothing here is sent anywhere meanwhile.`
+  if (opening) return `This folder is starting to follow square ${short} of ${name}.`
+  return `This folder's work is live in square ${short} of ${name}: every edit reaches everyone on it. Commit it with quilt commit "<message>".`
+}
+
+// How long a read of the quilt through the relay may take: the relay reads Seam with the room's one
+// read token and retries a busy Seam (429, 503) itself, so a folder waits for it rather than giving up
+// after a branch request's 10 s (the second rehearsal: an app restarted with two others failed its
+// first try that way, and followed 30 s later).
+export const QUILT_READ_TIMEOUT_MS = 60 * 1000
+
+/**
+ * Reads of the room's quilt through the relay (server.js quiltBlockRead), with the room's read
+ * token: the calls a block reads with, so a member needs no Seam sign-in to follow its square.
+ */
+export function relayReader (conn) {
+  const read = async (fields) => {
+    if (!conn || !conn.connected) throw new Error('not connected to the relay')
+    try {
+      return await conn.branchRequest({ op: 'quilt-block', ...fields }, { timeoutMs: QUILT_READ_TIMEOUT_MS })
+    } catch (err) {
+      throw new Error(`reading the square's ${fields.call} through the relay: ${err.message}`)
+    }
+  }
+  return {
+    square: async (q, s) => (await read({ call: 'square', square: s })).square,
+    tree: async (q, rev, paths) => (await read({ call: 'tree', rev, ...(paths ? { paths } : {}) })).tree,
+    blobs: async (q, ids) => {
+      const out = {}
+      for (let i = 0; i < ids.length; i += 200) Object.assign(out, (await read({ call: 'blobs', ids: ids.slice(i, i + 200) })).blobs)
+      return { blobs: out }
+    },
+    diff: async (q, o = {}) => (await read({ call: 'diff', from: o.from, to: o.to, ...(o.paths ? { paths: o.paths } : {}) })).diff,
+    cat: async (q, rev, file, o = {}) => (await read({ call: 'cat', rev, file, format: o.format })).cat
+  }
+}
 
 export class SquareFollower {
   /** @param {object} session a Session (server, room, secret, name, identity, passes, tool, kind, features, quilt, branchKey(), log) */
-  constructor (session, { open = openLiveBlock } = {}) {
+  constructor (session, { open = openLiveBlock, retryMs = RETRY_MS, catchUpMs = CATCH_UP_MS } = {}) {
     this.session = session
     this.open = open
-    this.following = null // { square, dir, block }
+    this.retryMs = retryMs
+    this.catchUpMs = catchUpMs
+    this.following = null // { square, dir, block }: a separate folder
+    this.here = null // { square, quilt, block, opening, problem }: the session's own folder, in place
+    this.turn = Promise.resolve() // one change of square at a time
+  }
+
+  relayOpts () {
+    const s = this.session
+    // A person's session has no identity of its own (it signs in with passes): its connection loads this computer's.
+    const identity = s.identity || (s.conn && s.conn.identity) || null
+    return { server: s.server, room: s.room, secret: s.secret, name: s.name, identity, passes: s.passes, tool: s.tool, kind: s.kind, features: withQuilts(s.features) }
   }
 
   /** Opens the block at `dir` (its own folder, signed in to Seam with `client`) on the session's branch's square. */
   async follow ({ dir, client } = {}) {
-    if (!process.env.QUILT_SOURCE_URL) throw new Error('Seam is not on for this app (QUILT_SOURCE_URL is not set).')
+    if (!appSeamUrl()) throw new Error('Seam is turned off for this app (QUILT_SOURCE_URL=off).')
     if (!dir) throw new Error('Give the folder the square\'s files go to.')
     const s = this.session
     // Its own folder: inside the session's folder, the block's files would sync a second time.
@@ -47,35 +295,221 @@ export class SquareFollower {
     const at = squareFor(s.quilt, branch)
     if (!at) throw new Error(`The session is a quilt, but ${branch} has no live square yet (the owner switches it with quilt session migrate --switch).`)
     if (this.following && this.following.square === at.square && this.following.dir === dir) return { square: at.square, dir }
-    await this.close()
-    const block = await this.open({
-      dir,
-      client,
-      quilt: s.quilt.id,
-      square: at.square,
-      api: process.env.QUILT_SOURCE_URL,
-      relay: { server: s.server, room: s.room, secret: s.secret, name: s.name, identity: s.identity, passes: s.passes, tool: s.tool, kind: s.kind, features: withQuilts(s.features) }
-    })
+    await this.closeSeparate()
+    const block = await this.open({ dir, client, quilt: s.quilt.id, square: at.square, api: appSeamUrl(), relay: this.relayOpts() })
     this.following = { square: at.square, dir, block }
     if (s.log) s.log(`🧵 ${dir} follows the square ${at.square} of ${s.quilt.slug || s.quilt.id}: edits there are live for everyone on it.`)
     return { square: at.square, dir }
   }
 
-  /** The relay's `quilt` message: let go of a square the branch no longer has (switched back, moved). */
-  async onQuilt (quilt) {
-    if (!this.following) return
-    const at = squareFor(quilt, this.session.branchKey())
-    if (at && at.square === this.following.square) return
-    const was = this.following.square
-    await this.close()
-    if (this.session.log) this.session.log(`🧵 stopped following the square ${was}: ${at ? `the branch is on ${at.square} now` : 'the session is back on its branch documents'}.`)
+  /** The relay's `quilt` message: the folder follows its branch's square in place, or lets go of one the branch no longer has. */
+  onQuilt (quilt) {
+    const s = this.session
+    // Held before the first await: nothing of the folder reaches the read-only branch document while the block opens.
+    const at = this.inPlaceOn() ? squareFor(quilt, s.squareBranchKey ? s.squareBranchKey() : s.branchKey()) : null
+    if (at && s.enterSquare && !(this.here && this.here.square === at.square)) s.enterSquare(at, quilt)
+    const next = this.turn.then(() => this.settle(quilt)).catch((err) => { if (s.log) s.log(`🧵 ${err.message}`) })
+    this.turn = next
+    // A merge onto main moves a branch on (quiltNext), and the relay says so: the other squares may be behind now.
+    next.then(() => this.catchUpSoon())
+    return next
   }
 
-  async close () {
+  /** Seam on for the app, a folder of the session's own, and a session that can hold its sync (a Session). */
+  inPlaceOn () { return !!(appSeamUrl() && this.session.root && this.session.enterSquare) }
+
+  async settle (quilt) {
+    const s = this.session
+    const at = this.inPlaceOn() ? squareFor(quilt, s.squareBranchKey ? s.squareBranchKey() : s.branchKey()) : null
+    // The separate folder lets go of a square the branch no longer has (switched back, moved).
+    const sep = this.following && squareFor(quilt, s.branchKey())
+    if (this.following && !(sep && sep.square === this.following.square)) {
+      const was = this.following.square
+      await this.closeSeparate()
+      if (s.log) s.log(`🧵 stopped following the square ${was}: ${sep ? `the branch is on ${sep.square} now` : 'the session is back on its branch documents'}.`)
+    }
+    if (this.here && (!at || at.square !== this.here.square)) {
+      const was = this.here.square
+      // Moved on (a merge): what the folder has not sent yet reaches the old square first, and the relay takes it on to the new one.
+      if (at && this.here.block && this.here.block.flush) await this.here.block.flush().catch(() => {})
+      const writers = this.writersHere()
+      await this.closeHere()
+      if (!at) {
+        if (s.leaveSquare) await s.leaveSquare({ writers })
+        if (s.log) s.log(`🧵 this folder stopped following square ${squareShort(was)}: the session is back on its branches, and the folder syncs with its branch as before.`)
+      } else if (s.log) s.log(`🧵 this folder left square ${squareShort(was)}: its branch is on ${squareShort(at.square)} now.`)
+    }
+    if (!at || (this.here && this.here.square === at.square)) return
+    await this.openHere(at, quilt)
+  }
+
+  /** The session's own folder becomes the square's block (live-block.js, in place). */
+  async openHere (at, quilt, { fresh = false } = {}) {
+    const s = this.session
+    const here = { square: at.square, quilt, block: null, problem: '', opening: true }
+    this.here = here
+    if (s.scheduleStatusWrite) s.scheduleStatusWrite()
+    try {
+      // Edits the read-only branch document refused (they reached it after the switch) are the folder's too.
+      const unsent = !fresh && s.unsentPaths ? await s.unsentPaths().catch(() => null) : null
+      const block = await this.open({
+        dir: s.root,
+        // A square opened for this folder's branch (Session.openSquareHere: the branch had none) takes the folder as it is: its files are the work.
+        inPlace: fresh ? { edited: () => false, fresh: true } : s.folderWins === at.square ? { edited: () => true } : { edited: (p) => s.editedSinceSync(p) || !!(unsent && unsent.has(p)) || !!(s.boxedHere && s.boxedHere(p)), boxed: (p) => !!(s.boxedHere && s.boxedHere(p)), heldBack: (p) => !!(s.heldBackHere && s.heldBackHere(p)), synced: (p) => !!(s.syncedHere && s.syncedHere(p)), base: s.syncedText ? (p) => s.syncedText(p) : null, own: () => (s.branchOwnPaths ? s.branchOwnPaths() : null), atTip: ((quilt && quilt.atTip) || []).includes(s.squareBranchKey ? s.squareBranchKey() : s.branchKey()) },
+        skip: (p) => !s.syncable(p),
+        skipDir: s.ignoredDir ? (p) => s.ignoredDir(p) : null,
+        record: path.join(s.stateDir || path.join(s.root, '.quilt'), 'block.json'),
+        reader: s.squareReader ? s.squareReader() : relayReader(s.conn),
+        client: s.seamWriteClient ? await s.seamWriteClient() : null,
+        quilt: quilt.id,
+        square: at.square,
+        api: appSeamUrl(),
+        relay: this.relayOpts(),
+        log: (m) => { if (s.log) s.log(`🧵 ${m}`) },
+        started: (b) => { here.starting = b },
+        // Who changed what goes on as on the branch: this folder's edits on record as its member's.
+        onEdits: s.squareEdits ? (list, doc, held) => { if (this.here === here) s.squareEdits(list, doc, held) } : null
+      })
+      if (this.here !== here) { await block.close().catch(() => {}); return }
+      here.block = block
+      here.opening = false
+      if (s.followSquareDoc) s.followSquareDoc(block.doc)
+      // What the square holds not committed yet (status `work`) changes with every edit on it, anyone's: the app hears.
+      if (block.doc && block.doc.on && s.scheduleStatusWrite) block.doc.on('update', () => { if (this.here === here) s.scheduleStatusWrite() })
+      if (s.log) s.log(`🧵 ${squareLine({ square: at.square, quilt })}`)
+      // Another member's app brought main in, or a commit moved the head: how far behind, and what conflicts, asked again.
+      if (block.doc && block.doc.getMap) block.doc.getMap('live').observe(() => { if (this.here === here) this.catchUpSoon() })
+      here.catchUpTimer = setInterval(() => this.catchUp().catch(() => {}), this.catchUpMs)
+      here.catchUpTimer.unref?.()
+      this.catchUp().catch(() => {})
+    } catch (err) {
+      if (this.here !== here) return
+      here.opening = false
+      here.problem = String(err.message || err).slice(0, 300)
+      if (s.log) s.log(`🧵 ${squareLine({ square: at.square, quilt, problem: here.problem })}`)
+      clearTimeout(this.retryTimer)
+      this.retryTimer = setTimeout(() => {
+        if (this.here !== here || s.stopped) return
+        this.here = null
+        this.onQuilt(s.quilt)
+      }, this.retryMs)
+      if (this.retryTimer.unref) this.retryTimer.unref()
+    }
+    if (s.scheduleStatusWrite) s.scheduleStatusWrite()
+  }
+
+  /** git moved the folder to another branch: it follows that branch's square, as the square has it (git's checkout is not an edit). */
+  async branchMoved (quilt) {
+    const s = this.session
+    const at = squareFor(quilt, s.squareBranchKey())
+    if (at && this.here && this.here.square === at.square) return
+    const was = this.here && this.here.square
+    const writers = this.writersHere()
+    await this.closeHere()
+    if (!at) {
+      if (s.leaveSquare) await s.leaveSquare({ writers })
+      return
+    }
+    if (s.log && was) s.log(`🧵 this folder left square ${squareShort(was)} for ${s.squareBranchKey()}'s, ${squareShort(at.square)}.`)
+    s.enterSquare(at, quilt)
+    await this.openHere(at, quilt, { fresh: true })
+  }
+
+  /** catchUp in a moment: the relay says something of the quilt in bursts, and one ask answers them all. */
+  catchUpSoon () {
+    if (!this.here || !this.here.block || this.catchUpTimer) return
+    this.catchUpTimer = setTimeout(() => { this.catchUpTimer = null; this.catchUp().catch(() => {}) }, 1000)
+    this.catchUpTimer.unref?.()
+  }
+
+  /**
+   * Bringing main in (server.js quiltCatchUp, source-live/bring-in.js): asks the relay, as this member,
+   * whether main moved past the square's base; when it did and it is this member's turn (its holder
+   * first, else a writer), the relay brings main's new patches into the square, and this folder, like
+   * every folder on it, gets the new files. The answer says how far behind the square is, for status.
+   */
+  async catchUp () {
+    const s = this.session
+    const h = this.here
+    if (!h || !h.block || h.catching || s.stopped || !s.conn || !s.conn.connected || !s.seamMember || !appSeamUrl()) return null
+    h.catching = true
+    try {
+      const { token } = await s.seamMember().client(h.quilt.id, [h.square])
+      const branch = s.squareBranchKey ? s.squareBranchKey() : s.branchKey()
+      const r = await s.conn.branchRequest({ op: 'quilt-catch-up', token, branch }, { timeoutMs: QUILT_MOVE_TIMEOUT_MS })
+      if (this.here !== h) return null
+      h.behind = r.behind || 0
+      h.conflicted = r.conflicted || 0
+      // Main waits for a folder on the square too old to follow its base moving (server.js outdatedOn): whose.
+      h.outdated = Array.isArray(r.outdated) ? r.outdated.map(String).slice(0, 10) : []
+      h.catchUpProblem = ''
+      if (r.brought && s.log) s.log(`🧵 ${catchUpWords({ brought: { ...r.brought, at: Date.now() } }).join(' ')}`)
+      if (s.scheduleStatusWrite) s.scheduleStatusWrite()
+      return r
+    } catch (err) {
+      if (this.here === h && h.catchUpProblem !== err.message) {
+        h.catchUpProblem = err.message
+        if (s.log) s.log(`🧵 couldn't check whether main moved past square ${squareShort(h.square)} (${err.message}); Quilt asks again in a minute.`)
+      }
+      return null
+    } finally { h.catching = false }
+  }
+
+  /** Where the session's own folder stands, for status: { square, quilt, line, problem?, opening? }, or null. */
+  status () {
+    const h = this.here
+    if (!h) return null
+    const quilt = { id: h.quilt.id, slug: h.quilt.slug || '' }
+    const problem = h.problem || (h.block && (h.block.problem || h.block.outOfStep)) || ''
+    // `work`: the square's live work not committed yet (everyone's on it, as the relay holds it), for the app's count and list.
+    let work = null
+    try { if (h.block && h.block.status) { const all = h.block.status(); work = { count: all.length, files: all.slice(0, WORK_LISTED) } } } catch {}
+    // Main brought in (by this app or another member's): the live document keeps the last time, for everyone.
+    const b = h.block ? broughtOf(h.block.doc) : null
+    const brought = b ? { at: b.at, by: b.by || '', patches: b.patches || 0, combined: b.combined || [], conflicts: b.conflicts || [], ...(Array.isArray(b.stale) && b.stale.length ? { stale: b.stale } : {}) } : null
+    const catching = { ...(h.behind ? { behind: h.behind } : {}), ...(h.behind && h.outdated && h.outdated.length ? { outdated: h.outdated } : {}), ...(h.conflicted !== undefined ? { conflicted: h.conflicted } : {}), ...(brought ? { brought } : {}) }
+    const words = h.block ? catchUpWords(catching).join(' ') : ''
+    return { square: h.square, short: squareShort(h.square).slice(3), quilt, ...(h.opening ? { opening: true } : {}), ...(problem ? { problem } : {}), ...(work ? { work } : {}), ...catching, line: squareLine({ square: h.square, quilt, problem: h.problem, opening: h.opening }) + (h.block && h.block.problem ? ` ${h.block.problem}.` : '') + (h.block && h.block.outOfStep ? ` ${h.block.outOfStep}.` : '') + (words ? ` ${words}` : '') }
+  }
+
+  /** Who last wrote each path of the square's live work (live-square.js lastWriters), or null without an open block. */
+  writersHere () {
+    const b = this.here && this.here.block
+    try { return b && b.doc ? lastWriters(b.doc) : null } catch { return null }
+  }
+
+  /** Commits the square's live work from the session's own folder (live-block.js commit). */
+  async commit ({ message = '' } = {}) {
+    const h = this.here
+    if (!h) throw new Error('This folder does not follow a square: the session is not a quilt at layout 3 (or Seam is off for this app).')
+    if (!h.block) throw new Error(h.problem ? `This folder can't follow its square yet: ${h.problem}` : 'This folder is still starting to follow its square; try again in a moment.')
+    if (!message || !String(message).trim()) throw new Error('Say what the commit is (a message).')
+    return h.block.commit({ message: String(message).slice(0, 2000) })
+  }
+
+  async closeHere () {
+    const h = this.here
+    this.here = null
+    clearTimeout(this.retryTimer)
+    clearTimeout(this.catchUpTimer)
+    this.catchUpTimer = null
+    if (h) clearInterval(h.catchUpTimer)
+    if (this.session.unfollowSquareDoc) this.session.unfollowSquareDoc()
+    if (h && h.block && h.block.close) await h.block.close().catch(() => {})
+    // Still opening (waiting for the relay, say): stopped where it is, or its connection outlives the folder's square.
+    else if (h && h.starting && h.starting.abandon) h.starting.abandon()
+  }
+
+  async closeSeparate () {
     const f = this.following
     this.following = null
     if (f && f.block && f.block.close) await f.block.close().catch(() => {})
   }
 
+  async close () {
+    await this.closeSeparate()
+    await this.closeHere()
+  }
+
   stop () { return this.close() }
 }