heyquilt 0.3.121 → 0.3.122

package/src/server.js

@@ -14,6 +14,7 @@
 // editors change files, viewers only watch and chat, and agents can be
 // limited to some folders. The relay enforces it by undoing file changes a
 // member isn't allowed to make, before anyone else sees them.
+import { quiltOf, gitTokenRefusal } from './session-seam.js'
 import http from 'node:http'
 import { makeChatLink, extendChatLink, pruneChatLinks, handleChatLink, fetchPublicFile } from './chat-links.js'
 import fs from 'node:fs'
@@ -34,7 +35,15 @@ import {
   ROOM_DOC, syncHeader,
   syncStep1Message, updateMessage, awarenessMessage, bytesMessage, jsonMessage
 } from './protocol.js'
-import { isLiveKey, liveRequest } from './source-live/live-square.js'
+import { isLiveKey, liveRequest, liveKey, liveMaps } from './source-live/live-square.js'
+import { planSessionQuilt, quiltPlanRefusal, describeQuiltPlan, fileHash } from './session-quilt.js'
+import { makeQuiltWithoutHistory } from './session-migrate.js'
+import { LAYOUT_QUILT, treeIds, overlayFor, writeOverlay, checkOverlay } from './session-layout3.js'
+import { readMerges } from './merges.js'
+import { readTasks, updateTask } from './tasks.js'
+import { addComment } from './task-comments.js'
+// Seam over HTTP through its client package (@heyquilt/seam), never Seam's code.
+import { quiltClient } from '@heyquilt/seam/lib/quilts/client.js'
 import { BranchStore, DEFAULT_KEY, BRANCH_IDLE_MS, DETACHED_TTL_MS, MAX_BRANCHES, validBranchKey, covers, splitLegacyDoc } from './branchdocs.js'
 import { parsePublicKey, verifyChallenge } from './identity.js'
 import { verifyPass, PASS_TTL_MS } from './passes.js'
@@ -1026,7 +1035,7 @@ class Room {
    * are never only in memory, and a crash part-way is finished at the next load.
    */
   migrateLegacy () {
-    if (this.meta.layout === 2) return
+    if (this.meta.layout === 2 || this.meta.layout === LAYOUT_QUILT) return
     const legacy = this.doc
     if (this.docFile && (legacy.getMap('files').size || legacy.getMap('blobs').size)) {
       const stored = [...legacy.getMap('blobs').values()].filter((x) => x && x.stored && x.stored.id).map((x) => x.stored.id).sort()
@@ -1384,6 +1393,7 @@ class Room {
 
   /** A room whose move to branch documents failed on the relay's disk (migrateLegacy) stays read-only: no branch document is used. */
   assertMigrated () {
+    if (this.meta.layout === LAYOUT_QUILT) throw new Error(`This session is the quilt ${(this.meta.quilt && this.meta.quilt.slug) || this.meta.quilt_id} now: its files are in its squares, not in branches. Use Seam (squares, commits, merges).`)
     if (this.meta.layout !== 2) throw new Error("The relay couldn't finish updating how it stores this session (its disk refused), so the session is read-only until the relay is fixed.")
   }
 
@@ -1811,8 +1821,18 @@ class Room {
     if (this.cfg.upstreamAuto) this.checkUpstreams().catch(() => {})
   }
 
+  /**
+   * What every branch-list message carries: the list and, once the session is a quilt (behind
+   * QUILT_SOURCE_URL), its link { id, slug, squares: { branch: square id } } so each member's
+   * app and agents can use Seam (plans/quilt-source-control/16).
+   */
+  branchesFields () {
+    const q = this.meta.quilt_id && process.env.QUILT_SOURCE_URL ? { id: this.meta.quilt_id, slug: (this.meta.quilt || {}).slug || '', squares: (this.meta.quilt || {}).squares || {}, ...((this.meta.quilt || {}).at ? { at: this.meta.quilt.at } : {}), ...(this.meta.layout === LAYOUT_QUILT ? { layout: LAYOUT_QUILT, live: this.meta.quilt.live || {}, ...(this.meta.quilt.adoption ? { adoption: this.meta.quilt.adoption } : {}) } : {}) } : null
+    return { branches: this.branchList(), ...(q ? { quilt: q } : {}) }
+  }
+
   broadcastBranches () {
-    const msg = jsonMessage(MSG_BRANCHES, { branches: this.branchList() })
+    const msg = jsonMessage(MSG_BRANCHES, { ...this.branchesFields() })
     for (const ws of this.conns.keys()) send(ws, msg)
   }
 
@@ -1838,7 +1858,7 @@ class Room {
 
   /** The relay pushed `sha` to branch `key`'s upstream: folders on it fetch now and follow it (no file is written: the session has it). */
   tellPushed (key, sha) {
-    const msg = jsonMessage(MSG_BRANCHES, { branches: this.branchList(), pushed: { branch: key, sha } })
+    const msg = jsonMessage(MSG_BRANCHES, { ...this.branchesFields(), pushed: { branch: key, sha } })
     for (const ws of this.conns.keys()) send(ws, msg)
   }
 
@@ -1961,7 +1981,7 @@ class Room {
       if (head && sync && sync.pushed === head && sync.base === head) { echo = true; this.saveMeta(); continue } // our own push, come back round
       const at = this.cfg.gitSync && this.mirrors && this.meta.sync && this.meta.sync[key] && this.meta.sync[key].base ? this.meta.sync[key].base : rec.sha
       if (head && at === head) { this.saveMeta(); continue } // already there
-      const msg = jsonMessage(MSG_BRANCHES, { branches: this.branchList(), pushed: { branch: key, sha: head, ...(forced ? { forced: true } : {}) } })
+      const msg = jsonMessage(MSG_BRANCHES, { ...this.branchesFields(), pushed: { branch: key, sha: head, ...(forced ? { forced: true } : {}) } })
       for (const ws of this.conns.keys()) send(ws, msg)
       this.checkUpstreamsNow([key]).catch((err) => this.log(`[${this.name}] could not look for new commits: ${err.message}`))
     }
@@ -2017,14 +2037,22 @@ class Room {
    * app asks before it clears its folder for a switch).
    */
   branchRequest (ws, req) {
+    // Seam, behind QUILT_SOURCE_URL (plans/quilt-source-control/16): what making this session a
+    // quilt would do, read only. The owner's (or, in a session without one, any editor's).
+    if (req.op === 'quilt-plan') {
+      if (!process.env.QUILT_SOURCE_URL) throw new Error('Seam is not on for this relay, so a session cannot become a quilt here yet')
+      return { ok: true, plan: this.quiltPlan(this.access.get(ws), req.tip) }
+    }
     const key = String(req.branch ?? '')
     if (!validBranchKey(key)) throw new Error(`"${key.slice(0, 60)}" isn't a branch name`)
     if (req.op === 'join') {
-      this.assertMigrated()
+      // At layout 3 the only documents members join are squares' live documents (quiltSwitch).
+      const square = this.meta.layout === LAYOUT_QUILT && isLiveKey(key)
+      if (!square) this.assertMigrated()
       // An app from before branch documents names the branch the old document was; else the first real branch takes ∅.
       let adopted = false
-      if (validBranchKey(String(req.adopt || ''))) adopted = this.adoptDefault(String(req.adopt))
-      adopted = this.adoptDefault(key) || adopted
+      if (!square && validBranchKey(String(req.adopt || ''))) adopted = this.adoptDefault(String(req.adopt))
+      if (!square) adopted = this.adoptDefault(key) || adopted
       const k = this.resolveKey(key)
       const created = !this.meta.branches[k]
       if (created) {
@@ -2095,9 +2123,240 @@ class Room {
     throw new Error('unknown branch request')
   }
 
+  /**
+   * Tasks with a pull request, once the room is a quilt (16's table): one whose branch became a
+   * square is kept in `meta.quilt.tasks` (task id -> square id); one whose branch did not loses
+   * its `pr`, kept as a task comment. Returns the task id -> square id map.
+   */
+  quiltTasks (squares) {
+    const tasks = readTasks(this.tasks)
+    const out = {}
+    for (const t of tasks) {
+      if (!t.pr) continue
+      const sq = t.pr.branch && squares[t.pr.branch]
+      if (sq) { out[t.id] = sq; continue }
+      const which = `${t.pr.number ? ` #${t.pr.number}` : ''}${t.pr.url ? ` (${t.pr.url})` : ''}`
+      updateTask(this.doc, this.tasks, { id: t.id, pr: null }, 'quilt-migrate')
+      addComment(this.doc, this.taskComments, tasks, { taskId: t.id, by: 'Quilt', text: `This task's pull request${which} did not carry over when the session became a quilt: no square was made from its branch${t.pr.branch ? ` ${t.pr.branch}` : ''}.` }, 'quilt-migrate')
+    }
+    return out
+  }
+
+  /**
+   * Open commit requests have no replacement in a quilt (12): each becomes a comment on its task,
+   * or a chat line when it has none, "Please get this into history: <paths>" with its square.
+   */
+  quiltCommitRequests (squares) {
+    const tasks = readTasks(this.tasks)
+    for (const r of this.commitRequests.values()) {
+      if (!r || r.state !== 'open') continue
+      const sq = squares[r.branch || this.defaultKey]
+      const text = `Please get this into history: ${(r.files || []).join(', ')}${sq ? ` (square sq:${sq.slice(0, 8)})` : ''}. ${r.by || 'Someone'} asked for a commit ("${String(r.message || '').slice(0, 200)}") before the session became a quilt: commit it in Seam.`
+      if (r.task && tasks.some((t) => t.id === r.task.id)) addComment(this.doc, this.taskComments, tasks, { taskId: r.task.id, by: 'Quilt', text }, 'quilt-migrate')
+      else this.postChat({ by: 'Quilt', text, kind: 'note' })
+    }
+  }
+
+  /**
+   * The owner's app asks to make the session a quilt (`op: 'quilt-migrate'`, `token`: their Seam
+   * sign-in). Answered when it is done, on the branch channel like every branch request.
+   */
+  quiltMigrateRequest (ws, req) {
+    const answer = (fields) => send(ws, jsonMessage(MSG_BRANCHES, { ...this.branchesFields(), reply: { id: req.id, op: req.op, ...fields } }))
+    const api = process.env.QUILT_SOURCE_URL
+    if (!api) return answer({ ok: false, error: 'Seam is not on for this relay, so a session cannot become a quilt here yet' })
+    if (!req.token || typeof req.token !== 'string') return answer({ ok: false, error: 'sign in to Seam first: making a session a quilt is done as its owner' })
+    const seam = (this.seamClient || quiltClient)({ api, token: req.token })
+    if (req.op === 'quilt-switch') {
+      return this.quiltSwitch(this.access.get(ws), seam).then((r) => answer({ ok: true, ...r }), (err) => answer({ ok: false, error: err.message }))
+    }
+    this.quiltMigrate(this.access.get(ws), seam).then(
+      (r) => answer({ ok: true, quilt: r }),
+      (err) => answer({ ok: false, error: err.message, ...(err.quilt_id ? { quilt_id: err.quilt_id } : {}) })
+    )
+  }
+
+  /** The dry run of making this session a quilt, for someone with access `a` (session-quilt.js). */
+  quiltPlan (a, tip = null) {
+    const no = quiltPlanRefusal({ controlled: this.controlled, access: a })
+    if (no) throw new Error(no)
+    this.assertMigrated()
+    return planSessionQuilt(this.quiltSnapshot(), { tip: tip && typeof tip === 'object' ? tip : null })
+  }
+
+  /**
+   * The room as session-quilt.js's dry run reads it: each branch document's files (by hash),
+   * history and merge records, the claims, tasks with pull requests, and commit requests.
+   * Live square documents (quilt/<id>) are already Seam's and are left out.
+   */
+  quiltSnapshot () {
+    const branches = []
+    for (const [key, b] of Object.entries(this.meta.branches || {})) {
+      if (isLiveKey(key)) continue
+      const e = this.store.load(key)
+      if (!e) continue
+      const files = {}
+      for (const [p, t] of e.files) { const s = t.toString(); files[p] = { hash: fileHash(s), bytes: Buffer.byteLength(s) } }
+      for (const [p, x] of e.blobs) if (x && !files[p]) files[p] = { hash: String(x.hash || x.sha256 || ''), bytes: Number(x.size) || 0 }
+      const merges = [...e.doc.getMap('merges').values()].map((m) => ({ id: m && m.id, state: m && m.state }))
+      branches.push({ key, by: b.by || '', files, history: e.doc.getArray('history').toArray(), merges })
+    }
+    const claims = Object.values(this.meta.claims || {}).map((c) => ({ pattern: c.pattern, branch: this.branchOf(c), by: c.by || '', byId: c.byId || '', queue: c.queue || [] }))
+    const tasks = [...this.tasks.entries()].map(([id, t]) => ({ id, pr: t && typeof t.get === 'function' ? t.get('pr') : t && t.pr })).filter((t) => t.pr)
+    return {
+      room: this.name,
+      owner: this.meta.ownerSub || this.meta.ownerName || this.meta.owner || '',
+      defaultKey: this.defaultKey,
+      hasRemote: Object.keys(this.meta.upstreams || {}).length > 0,
+      branches,
+      claims,
+      tasks,
+      commitRequests: this.doc.getMap('commitRequests').size
+    }
+  }
+
+  /**
+   * Makes this session a quilt (plans/quilt-source-control/16, "Without history"), behind
+   * QUILT_SOURCE_URL: the owner's (as quiltPlan), with `seam` a Seam client acting as them.
+   * The room is linked (`meta.quilt_id`, `meta.quilt`) only when every step worked, so a
+   * failure leaves it a git-mode session as before. A room with a git remote goes with history
+   * (the import and the cut-over, 14 and 16 step 3), not here.
+   */
+  async quiltMigrate (a, seam, { date = new Date() } = {}) {
+    const no = quiltPlanRefusal({ controlled: this.controlled, access: a })
+    if (no) throw new Error(no.replace('see what making it a quilt would do', 'make it a quilt'))
+    this.assertMigrated()
+    if (this.meta.quilt_id) throw new Error(`this session is already the quilt ${(this.meta.quilt && this.meta.quilt.slug) || this.meta.quilt_id}`)
+    if (Object.keys(this.meta.upstreams || {}).length) throw new Error('this session has a git remote: it becomes a quilt with its history, by importing the remote and cutting over (docs/seam-cutover.md)')
+    if (this.quiltMoving) throw new Error('this session is already being made a quilt')
+    this.quiltMoving = true
+    try {
+      const texts = (key) => {
+        const e = this.store.load(key)
+        const files = {}; const big = []
+        if (!e) return { files, big, merges: [] }
+        for (const [p, t] of e.files) files[p] = t.toString()
+        for (const [p, x] of e.blobs) if (x && !(p in files)) big.push(p)
+        return { files, big, merges: e.doc ? readMerges(e.doc.getMap('merges')) : [] }
+      }
+      const def = texts(this.defaultKey)
+      const leftOut = new Set(def.big)
+      const branches = []
+      for (const key of Object.keys(this.meta.branches || {})) {
+        if (key === this.defaultKey || isLiveKey(key)) continue
+        const t = texts(key)
+        for (const p of t.big) leftOut.add(`${key}:${p}`)
+        branches.push({ key, files: t.files, merges: t.merges })
+      }
+      const r = await makeQuiltWithoutHistory({ seam, room: this.name, defaultFiles: def.files, defaultMerges: def.merges, branches, leftOut: [...leftOut], date })
+      this.meta.quilt_id = r.quilt_id
+      this.meta.quilt = { slug: r.slug, patch: r.patch, squares: Object.fromEntries(r.squares.map((s) => [s.from, s.id])), at: new Date(date).toISOString(), by: (a && (a.sub || a.key || a.name)) || '' }
+      // Open merges now live in Seam as conflict terms; the ones with no text to carry are named.
+      if (r.terms.length || r.merges_left.length) this.meta.quilt.merges = { terms: r.terms, left: r.merges_left }
+      this.meta.quilt.tasks = this.quiltTasks(this.meta.quilt.squares)
+      this.quiltCommitRequests(this.meta.quilt.squares)
+      this.saveMeta()
+      this.broadcastBranches()
+      return { ...r, tasks: this.meta.quilt.tasks }
+    } finally {
+      this.quiltMoving = false
+    }
+  }
+
+  /**
+   * The layout-3 switch (16, "How a session becomes a quilt"), after quiltMigrate linked the
+   * quilt: each branch document is copied into its square's live document on the relay
+   * (`quilt/<square id>`, an overlay over the square's head), the default branch's difference
+   * from `main` into an adoption square ("Uncommitted work from <room>"), every copy is checked
+   * against its branch document, and only then `meta.layout = 3` is written. A failed check
+   * removes the copies and leaves the room at layout 2. The branch documents are not touched: at
+   * layout 3 they are read-only, and quiltUnswitch goes back to them. Apps without `quilts` are
+   * sent away (supported). The owner's, with `seam` acting as them, behind QUILT_SOURCE_URL.
+   */
+  async quiltSwitch (a, seam, { date = new Date() } = {}) {
+    const no = quiltPlanRefusal({ controlled: this.controlled, access: a })
+    if (no) throw new Error(no.replace('see what making it a quilt would do', 'move its files into its squares'))
+    if (this.meta.layout === LAYOUT_QUILT) throw new Error('this session\'s files are already in its squares')
+    this.assertMigrated()
+    const q = this.meta.quilt_id
+    if (!q || !this.meta.quilt) throw new Error('this session is not a quilt yet: make it one first (quilt session migrate)')
+    if (this.quiltMoving) throw new Error('this session is already being moved')
+    this.quiltMoving = true
+    const made = []
+    const by = (a && (a.name || a.sub || a.key)) || ''
+    try {
+      const texts = (key) => {
+        const e = this.store.load(key)
+        const files = {}
+        if (e) for (const [p, t] of e.files) files[p] = t.toString()
+        return files
+      }
+      const held = (from) => new Set(((this.meta.quilt.merges && this.meta.quilt.merges.terms) || []).filter((t) => t.from === from).map((t) => t.path))
+      const without = (o, skip) => Object.fromEntries(Object.entries(o).filter(([p]) => !skip.has(p)))
+      const plan = []
+      for (const [key, sq] of Object.entries(this.meta.quilt.squares || {})) {
+        if (key === this.defaultKey || !this.meta.branches[key] || isLiveKey(key)) continue
+        const s = await seam.square(q, sq)
+        const head = s.head || s.base || null
+        const skip = held(key)
+        plan.push({ key, sq, head, files: without(texts(key), skip), tree: without(head ? treeIds(await seam.tree(q, head)) : {}, skip) })
+      }
+      const def = texts(this.defaultKey)
+      const main = this.meta.quilt.patch ? treeIds(await seam.tree(q, this.meta.quilt.patch.commit)) : {}
+      const adopt = overlayFor(def, main)
+      let adoption = null
+      if (Object.keys(adopt.puts).length || adopt.gone.length) {
+        const s = await seam.openSquare(q, { title: `Uncommitted work from ${this.name}`.slice(0, 200) })
+        adoption = s.id
+        plan.push({ key: this.defaultKey, sq: s.id, head: (this.meta.quilt.patch && this.meta.quilt.patch.commit) || null, files: def, tree: main })
+      }
+      for (const p of plan) {
+        const lk = liveKey(p.sq)
+        if (this.meta.branches[lk] && this.store.load(lk) && liveMaps(this.store.load(lk).doc).live.size) throw new Error(`square ${p.sq.slice(0, 8)} already has a live document on the relay`)
+        this.noteBranch(lk, { by })
+        made.push(lk)
+        writeOverlay(this.store.load(lk).doc, overlayFor(p.files, p.tree), p.head, by)
+      }
+      for (const p of plan) {
+        const bad = checkOverlay(this.store.load(liveKey(p.sq)).doc, p.files, p.tree)
+        if (bad) throw new Error(`the check after copying ${p.key === this.defaultKey ? 'the default branch' : p.key} failed: ${bad}`)
+      }
+      this.meta.quilt.live = Object.fromEntries(plan.map((p) => [p.key, liveKey(p.sq)]))
+      if (adoption) this.meta.quilt.adoption = adoption
+      this.meta.quilt.layoutAt = new Date(date).toISOString()
+      this.meta.layout = LAYOUT_QUILT // last
+      this.saveMeta()
+      for (const ws of [...this.conns.keys(), ...this.pending.keys()]) {
+        if (!ws.hosted && !this.supported(ws)) { ws.endReason = 'needs_update'; ws.close(CLOSE_NEEDS_UPDATE, NEEDS_UPDATE) }
+      }
+      this.broadcastBranches()
+      return { layout: LAYOUT_QUILT, live: this.meta.quilt.live, adoption }
+    } catch (err) {
+      for (const lk of made) this.removeBranch(lk)
+      if (made.length) this.broadcastBranches()
+      throw new Error(`Migration undone: ${err.message}. The session stays as it was.`)
+    } finally {
+      this.quiltMoving = false
+    }
+  }
+
+  /** Back to layout 2 from the kept branch documents (16's rollback before R3). The squares' live documents stay. */
+  quiltUnswitch (a) {
+    const no = quiltPlanRefusal({ controlled: this.controlled, access: a })
+    if (no) throw new Error(no.replace('see what making it a quilt would do', 'move it back to branches'))
+    if (this.meta.layout !== LAYOUT_QUILT) throw new Error('this session\'s files are not in squares')
+    this.meta.layout = 2
+    this.meta.quilt.unswitchedAt = new Date().toISOString()
+    this.saveMeta()
+    this.broadcastBranches()
+    return { layout: 2 }
+  }
+
   /** Can this connection's app handle the session as it is now? */
   supported (ws) {
-    return !this.meta.largeFiles || (ws.features || []).includes('large-files')
+    const f = ws.features || []
+    if (this.meta.layout === LAYOUT_QUILT && !f.includes('quilts')) return false
+    return !this.meta.largeFiles || f.includes('large-files')
   }
 
   /**
@@ -2975,7 +3234,7 @@ class Room {
     this.conns.set(ws, new Set())
     this.names.set(ws, name)
     send(ws, syncStep1Message(this.doc))
-    send(ws, jsonMessage(MSG_BRANCHES, { branches: this.branchList() }))
+    send(ws, jsonMessage(MSG_BRANCHES, { ...this.branchesFields() }))
     const states = [...this.awareness.getStates().keys()]
     if (states.length) send(ws, awarenessMessage(this.awareness, states))
     send(ws, jsonMessage(MSG_CLAIMS, { claims: this.claimList(ws.branch) }))
@@ -3051,6 +3310,8 @@ class Room {
         // A branch over its size limit takes nothing new; the room and every other branch carry
         // on, and nobody is disconnected for it (its members hear it in the branch list).
         if (!this.unsavable && this.branchFull(k) && decoding.peekVarUint(dec) !== syncProtocol.messageYjsSyncStep1) return
+        // At layout 3 the branch documents are kept read-only: the work is in the squares (quiltSwitch).
+        if (this.meta.layout === LAYOUT_QUILT && !isLiveKey(k) && decoding.peekVarUint(dec) !== syncProtocol.messageYjsSyncStep1) return
       }
       if (docId === ROOM_DOC ? this.full : this.unsavable) {
         // Over quota: still answer "what do you have?" so people can read, but refuse new data.
@@ -3069,13 +3330,15 @@ class Room {
       let reply
       try {
         req = JSON.parse(decoding.readVarString(dec))
-        reply = { id: req.id, op: req.op, ...this.branchRequest(ws, req) }
+        if (req.op === 'quilt-migrate' || req.op === 'quilt-switch') { this.quiltMigrateRequest(ws, req); return }
+        if (req.op === 'quilt-unswitch') reply = { id: req.id, op: req.op, ok: true, ...this.quiltUnswitch(this.access.get(ws)) }
+        else reply = { id: req.id, op: req.op, ...this.branchRequest(ws, req) }
       } catch (err) {
         reply = { id: req.id, op: req.op, ok: false, error: err.message }
       }
       const listChanged = reply.listChanged
       delete reply.listChanged
-      send(ws, jsonMessage(MSG_BRANCHES, { branches: this.branchList(), reply }))
+      send(ws, jsonMessage(MSG_BRANCHES, { ...this.branchesFields(), reply }))
       if (reply.ok && reply.op === 'join') {
         // What the relay has of the branch, and its claims: the app answers with what it has.
         send(ws, syncStep1Message(this.store.get(ws.branch).doc, ws.branchAs))
@@ -3127,7 +3390,9 @@ class Room {
           const id = req.id
           const a = this.access.get(ws)
           if (!a || !ws.branch) throw new Error('not in this session')
-          this.gitTokenFor(ws.branch, { access: req.access === 'write' ? 'write' : 'read', who: { name: a.name, kind: a.kind === 'agent' ? 'agent' : 'human', id: a.id }, repo: typeof req.repo === 'string' ? req.repo : null })
+          // In a session that is a quilt, an agent's git gets no GitHub token: it uses Seam (session-seam.js).
+          const onSeam = gitTokenRefusal(quiltOf(this.meta), a.kind === 'agent' ? 'agent' : 'human')
+          ;(onSeam ? Promise.reject(new Error(onSeam)) : this.gitTokenFor(ws.branch, { access: req.access === 'write' ? 'write' : 'read', who: { name: a.name, kind: a.kind === 'agent' ? 'agent' : 'human', id: a.id }, repo: typeof req.repo === 'string' ? req.repo : null }))
             .then((git) => ({ id, ok: true, git }), (err) => ({ id, ok: false, error: err.message }))
             .then((r) => { if (this.conns.has(ws)) send(ws, jsonMessage(MSG_MEMBERS, { members: this.memberList(), sessionName: this.meta.name || '', admitBy: this.admitBy, pending: this.personCanAdmit(this.access.get(ws)) ? this.pendingList() : [], reply: r })) })
           return
@@ -4036,6 +4301,44 @@ export function startServer ({ port = 4321, host = '0.0.0.0', dataDir = null, lo
         json(200, { ok: true, rooms: n })
       })
     }
+    // Making a session a quilt from the accounts API (POST /v1/sessions/:room/migrate, which checked the
+    // owner's sign-in): { room, account, dry_run } plans it; { room, account, token } makes it, as the
+    // owner, with their Seam sign-in. The room's own owner check still applies (Room.quiltPlan).
+    if (url.pathname === '/quilt/migrate' && req.method === 'POST') {
+      if (!fromApi(req)) return json(401, { error: 'only the accounts API may say this' })
+      return readJson(req, 16 * 1024, (err, b) => {
+        if (err || !b) return json(400, { error: 'send JSON' })
+        const name = String(b.room || '')
+        if (!/^[A-Za-z0-9_-]{1,64}$/.test(name)) return json(400, { error: 'give the room' })
+        if (!/^[a-z]+:[A-Za-z0-9_-]{1,64}$/.test(String(b.account || ''))) return json(400, { error: 'give the account' })
+        const api = process.env.QUILT_SOURCE_URL
+        if (!api) return json(409, { error: 'Seam is not on for this relay, so a session cannot become a quilt here yet' })
+        const onDisk = dataDir && fs.existsSync(path.join(dataDir, `${name}.json`))
+        if ((!rooms.has(name) && !onDisk) || roomEnded(name)) return json(404, { error: 'no such session' })
+        const room = getRoom(name)
+        if (!room) return json(409, { error: 'this session is not on this relay machine' })
+        const access = { state: 'approved', role: 'editor', scopes: [], owner: !room.controlled || room.meta.ownerSub === b.account, sub: b.account }
+        if (room.controlled && !access.owner) return json(403, { error: 'only the session\'s owner can make it a quilt' })
+        if (b.dry_run === true) {
+          try {
+            const plan = room.quiltPlan(access, b.tip && typeof b.tip === 'object' ? b.tip : null)
+            return json(200, { ok: true, plan, text: describeQuiltPlan(plan) })
+          } catch (e) { return json(409, { error: e.message }) }
+        }
+        if (b.step === 'unswitch') {
+          try { return json(200, { ok: true, ...room.quiltUnswitch(access) }) } catch (e) { return json(409, { error: e.message }) }
+        }
+        if (!b.token || typeof b.token !== 'string') return json(400, { error: 'sign in to Seam first: making a session a quilt is done as its owner' })
+        const seam = (room.seamClient || quiltClient)({ api, token: b.token })
+        if (b.step === 'switch') {
+          return room.quiltSwitch(access, seam).then((r) => json(200, { ok: true, ...r }), (e) => json(409, { error: e.message }))
+        }
+        room.quiltMigrate(access, seam).then(
+          (quilt) => json(200, { ok: true, quilt }),
+          (e) => json(409, { error: e.message, ...(e.quilt_id ? { quilt_id: e.quilt_id } : {}) })
+        )
+      })
+    }
     // Moving a room between machines (the accounts API runs it, src/api/relay-cluster.js): the source
     // lets it go, the target copies it from the source, the source forgets its copy (or takes it back).
     const cm = url.pathname.match(/^\/cluster\/rooms\/([A-Za-z0-9_-]{1,64})\/(release|export|fetch|forget|restore)$/)
@@ -4379,7 +4682,7 @@ export function startServer ({ port = 4321, host = '0.0.0.0', dataDir = null, lo
       return reject(socket, auth === 'need-key' ? 403 : 401, auth === 'need-key' ? 'Relay key required to create rooms' : 'Wrong room secret')
     }
     // Checked after the secret, so only members learn what the session needs.
-    if (room.meta.largeFiles && !features.includes('large-files')) {
+    if ((room.meta.largeFiles && !features.includes('large-files')) || (room.meta.layout === LAYOUT_QUILT && !features.includes('quilts'))) {
       if (!room.conns.size && room.onEmpty) room.onEmpty() // don't keep it in memory for nobody
       return reject(socket, 400, NEEDS_UPDATE)
     }

package/src/session-follow.js

@@ -0,0 +1,81 @@
+// Quilt's side of Seam (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.
+import path from 'node:path'
+import { FEATURES } from './protocol.js'
+import { openLiveBlock } from './source-live/live-block.js'
+
+const LAYOUT_QUILT = 3
+const PREFIX = 'quilt/'
+
+/** 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) {
+  if (!quilt || quilt.layout !== LAYOUT_QUILT || !branch) return null
+  const key = (quilt.live || {})[branch]
+  if (typeof key !== 'string' || !key.startsWith(PREFIX) || key.length === PREFIX.length) return null
+  return { square: key.slice(PREFIX.length), key }
+}
+
+const withQuilts = (f) => (String(f || FEATURES).split(',').includes('quilts') ? String(f || FEATURES) : `${f || FEATURES},quilts`)
+
+export class SquareFollower {
+  /** @param {object} session a Session (server, room, secret, name, identity, passes, tool, kind, features, quilt, branchKey(), log) */
+  constructor (session, { open = openLiveBlock } = {}) {
+    this.session = session
+    this.open = open
+    this.following = null // { square, dir, block }
+  }
+
+  /** 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 (!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.
+    if (s.root) {
+      const rel = path.relative(path.resolve(s.root), path.resolve(dir))
+      if (!rel || (!rel.startsWith('..') && !path.isAbsolute(rel))) throw new Error('Give a folder outside this session\'s folder: the square\'s files are synced there by Seam, not by this folder.')
+    }
+    if (!s.quilt) throw new Error('This session is not a quilt.')
+    const branch = s.branchKey()
+    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) }
+    })
+    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'}.`)
+  }
+
+  async close () {
+    const f = this.following
+    this.following = null
+    if (f && f.block && f.block.close) await f.block.close().catch(() => {})
+  }
+
+  stop () { return this.close() }
+}

package/src/session-layout3.js

@@ -0,0 +1,60 @@
+// Quilt's side of Seam: the room's switch to layout 3 (plans/quilt-source-control/16, "How a
+// session becomes a quilt"). After the session became a quilt (session-migrate.js), each branch
+// document is copied into its square's live document on the relay (`quilt/<square id>`,
+// source-live/live-square.js), whose shape is an overlay: only the paths that differ from the
+// square's head. The default branch's difference from `main` goes to an adoption square. The copy
+// is checked against the branch document before `meta.layout = 3` is written; the branch
+// documents themselves stay where they are, read-only, so going back to layout 2 loses nothing.
+// Seam (src/quilts/) never imports this.
+import * as Y from 'yjs'
+import { blobId } from '@heyquilt/seam/lib/quilts/records.js'
+import { liveMaps, startHead, entryOf, entryId } from './source-live/live-square.js'
+
+export const LAYOUT_QUILT = 3
+
+const idOf = (text) => blobId(Buffer.from(String(text), 'utf8'))
+
+/** A Seam tree answer ({ entries: [{ path, blob, mode }] }) as path -> blob id (conflict terms by term id). */
+export function treeIds (tree) {
+  const out = {}
+  for (const e of (tree && tree.entries) || []) out[e.path] = e.blob || e.term || null
+  return out
+}
+
+/** What turns `head` (path -> id) into `files` (path -> text): { puts: { path: text }, gone: [path] }. */
+export function overlayFor (files, head) {
+  const puts = {}
+  for (const [p, t] of Object.entries(files || {})) if (head[p] !== idOf(t)) puts[p] = t
+  const gone = Object.keys(head || {}).filter((p) => !Object.prototype.hasOwnProperty.call(files || {}, p)).sort()
+  return { puts, gone }
+}
+
+/** Writes an overlay into an empty live document, with `head` as its first head. */
+export function writeOverlay (doc, { puts, gone }, head, by = '') {
+  const m = liveMaps(doc)
+  doc.transact(() => {
+    for (const [p, t] of Object.entries(puts)) { const y = new Y.Text(); y.insert(0, t); m.files.set(p, y) }
+    for (const p of gone) m.gone.set(p, { by, ts: Date.now() })
+  }, 'relay-quilt')
+  if (head) startHead(doc, head, by)
+}
+
+/**
+ * The post-copy check (16, "Dry run and check"): the live document over its head holds exactly
+ * the branch document's files, by id. Returns null, or the first difference in words.
+ */
+export function checkOverlay (doc, files, head) {
+  const want = {}
+  for (const [p, t] of Object.entries(files || {})) want[p] = idOf(t)
+  const have = { ...head }
+  const m = liveMaps(doc)
+  for (const p of new Set([...m.files.keys(), ...m.blobs.keys(), ...m.gone.keys()])) {
+    const e = entryOf(doc, p)
+    if (!e) continue
+    if (e.op === 'delete') delete have[p]; else have[p] = entryId(e)
+  }
+  for (const p of new Set([...Object.keys(want), ...Object.keys(have)])) {
+    if (want[p] !== have[p]) return want[p] == null ? `${p} is in the square but not in the branch document` : have[p] == null ? `${p} is in the branch document but not in the square` : `${p} differs between the branch document and the square`
+  }
+  return null
+}