heyquilt 0.0.1 → 0.3.106

package/src/relay-outbound.js

@@ -0,0 +1,1273 @@
+// Session → GitHub through the relay's git mirror (relay-git.js). An edit on a synced branch
+// starts a batch: after 5 s of quiet (or 60 s after the first unpushed change) the session's
+// files that differ from the branch's base commit become one commit on the base, built with git
+// plumbing in the mirror (the tree is the base's tree with the pending files applied, as git add
+// would store them), authored by whoever changed the most lines, co-authored by the rest, and
+// pushed forward only. Files a member holds and paths git ignores never go in; conflict markers a
+// git merge left in a file are settled by Quilt first (settleMarkers: both sides' lines kept). Never a force-push: when the remote moved, inbound runs first
+// (relay-sync.js) and the commit is rebuilt on the new head.
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import crypto from 'node:crypto'
+import { syncStateOf, runGit, GitFailed, gcMirror, deleteRemoteBranch } from './relay-git.js'
+import { githubWriter } from './github-commit.js'
+import { bringInBranch, keepRefs, keptObjects, crashPoint, remoteHead, filesAt, applyWrites } from './relay-sync.js'
+import { upstreamsOf, parseRepo, ignoreOf, hasMarkers, docKey, RELAY_ORIGIN } from './relay-upstream.js'
+import { gitBlobSha, slug, noreply, agentPrefix, othersInChange, othersEditing } from './github-commit.js'
+import { openPullOnPush, noteTaskRevision, agentCommitsOf } from './relay-commit.js'
+import { everyone, notePushedMerges, upstreamCommits, memberForAuthor, tellAutoMerge } from './relay-clash.js'
+import { notePublished, combine } from './upstream.js'
+import { looksBinary } from './fsutil.js'
+import { mergeAuto } from './merge3.js'
+import { unwrapAsRelay, decryptBlob } from './largefiles.js'
+import { lfsUpload } from './relay-lfs.js'
+import { isSafeRelPath, isIgnored, MAX_TEXT_BYTES, MAX_BINARY_BYTES } from './pathrules.js'
+import { RELAY_BY, isRelay } from './branches.js'
+import { validToken } from './relay-upstream.js'
+import { appCredentials } from './relay-github.js'
+
+/** With the relay's own timer on (cfg.syncAuto, off unless a relay is started with it): a batch commits after this long with no further change on the branch… */
+export const SYNC_QUIET_MS = 5 * 1000
+/** …or this long after its first unpushed change, whichever comes first. */
+export const SYNC_MAX_MS = 60 * 1000
+/** GitHub out of reach: the next try after this long, doubling up to OUTAGE_MAX_MS (plan §11). */
+export const OUTAGE_START_MS = 5 * 1000
+export const OUTAGE_MAX_MS = 5 * 60 * 1000
+/** A push waits for the repository's budget up to this long in place; longer, it is queued (addendum 16.11). */
+export const BUDGET_WAIT_MS = 15 * 1000
+/** A push the remote moved under is tried again this many times (inbound first each time) before the next batch window. */
+export const PUSH_RETRIES = 3
+export const COMMITTER = { name: 'quilt-by-heyquilt[bot]', email: 'quilt-by-heyquilt[bot]@users.noreply.github.com' }
+const LFS_POINTER = 'version https://git-lfs'
+const SPECIAL = new Set(['120000', '160000']) // a symlink, a submodule: kept as they are, never rewritten by the relay
+
+/** Where a protected branch's live work goes (plan §5.5). */
+export const liveBranchOf = (ref) => `quilt/live/${ref}`
+
+const plural = (k, w) => `${k} ${w}${k === 1 ? '' : 's'}`
+
+/** Whether branch `key` of the room syncs live to GitHub: the mirror is on, the owner hasn't switched it off, and the relay can write to the repository. */
+export function liveSyncOn (room, key) {
+  if (!room.cfg || !room.cfg.gitSync || !room.mirrors || room.meta.githubSync === false) return false
+  const rec = upstreamsOf(room)[key]
+  if (!rec || !rec.repo || !rec.ref) return false
+  // Agents' policy "off" (addendum 16.7): an agent's own branch stays in the session; a person adopts its work (adoptBranch).
+  if (agentCommitsOf(room) === 'off' && agentOwnerOf(room, rec.ref)) return false
+  const repo = parseRepo(`https://${rec.repo}`)
+  if (!repo || !repo.github) return false
+  return validToken(room.meta.githubToken) || !!(rec.github && rec.github.state === 'ok')
+}
+
+/** The agent whose own branch `ref` is (quilt/<agent>/…), or null. */
+export function agentOwnerOf (room, ref) {
+  return Object.values(room.meta.members || {}).find((m) => m && m.kind === 'agent' && m.name && String(ref).startsWith(agentPrefix(m.name)))?.name || null
+}
+
+/**
+ * Whether agent `name` may commit straight to branch `key`'s GitHub branch through the relay (plan §2):
+ * null when it may, else why not. "any": every branch. "branches" (the default): only its own
+ * (quilt/<agent>/…); a commit elsewhere goes to a branch of its own with a pull request (relay-commit.js).
+ * "off": nothing of its own reaches GitHub; a person adopts the work. Agents edit the session's files
+ * on any branch as always: the policy is about what reaches GitHub, which only a commit does.
+ */
+export function agentCommitRefusal (room, key, name) {
+  const rec = upstreamsOf(room)[key]
+  if (!rec || !rec.ref || !room.cfg || !room.cfg.gitSync || room.meta.githubSync === false) return null
+  // The rule over the session (an org's, a team's, a workspace's) counts too: agentCommitsOf.
+  const policy = agentCommitsOf(room)
+  if (policy === 'any' || String(rec.ref).startsWith(agentPrefix(name))) return null
+  if (!liveSyncOn(room, key)) return null
+  return policy === 'off'
+    ? `The session owner keeps agents' commits off GitHub: ask a person to commit (quilt_request_commit), or work on a branch of your own (quilt/${slug(name, 30)}/<topic>) for a person to adopt.`
+    : `Agents commit only to branches of their own here: your commit goes to quilt/${slug(name, 30)}/<task>, with a pull request to ${rec.ref}.`
+}
+
+/**
+ * The files `who`'s commit on branch `key` takes (quilt_git_commit): `files` when given, else every file
+ * they changed on record on the branch (or the task's), as commitForMember does. { list } or { refused }.
+ */
+export function ownFiles (room, key, { who, files = null, task = null }) {
+  const e = room.branchDoc(key)
+  const history = e.doc.getArray('history').toArray()
+  const t = task ? room.doc.getMap('tasks').get(String(task)) : null
+  if (task && !t) return { refused: `No task ${task} on the board.` }
+  const clean = (l) => [...new Set((Array.isArray(l) ? l : []).filter((p) => typeof p === 'string').map((p) => p.replace(/^\.\//, '')).filter(isSafeRelPath))]
+  let list = clean(files)
+  if (Array.isArray(files) && files.length && !list.length) return { refused: 'None of those are files in the project (give paths relative to its top folder).' }
+  if (!list.length) {
+    for (const h of history) {
+      if (!h || h.pulled || h.seed || typeof h.path !== 'string') continue
+      if (t ? h.task && h.task.id === t.id : h.by === who) list.push(h.path)
+    }
+    if (t) list.push(...(Array.isArray(t.files) ? t.files : []))
+    list = clean(list)
+  }
+  if (!list.length) return { refused: t ? `Task ${t.id} has no changed files on record: give them in files.` : 'Quilt has no changes of yours on record on this branch: give the files in files.' }
+  return { list }
+}
+
+/** The author line of a member: an agent as <name> <slug@agents.noreply.heyquilt.com>, a person by their GitHub noreply when the relay knows it, else their name's noreply. */
+export function authorOf (room, name) {
+  const m = everyone(room).find((x) => x && x.name === name)
+  if (m && m.kind === 'agent') return { name, email: noreply(name) }
+  const gh = m && m.github && m.github.login ? m.github : null
+  if (gh) return { name, email: `${gh.id ? `${gh.id}+` : ''}${gh.login}@users.noreply.github.com` }
+  return { name, email: `${slug(name, 40)}@people.noreply.heyquilt.com` }
+}
+
+/** "Session edits: a, b, c and 4 more" */
+export const editsMessage = (paths) => `Session edits: ${paths.slice(0, 6).join(', ')}${paths.length > 6 ? ` and ${paths.length - 6} more` : ''}`
+
+/**
+ * Who changed what in `paths` since `since` (ms), from the branch's history: Map name -> lines,
+ * and the one task every change was for (or null). Pulls from git and the relay's own writes are nobody's.
+ */
+export function blameBatch (history, paths, { since = 0, sinceFor = null } = {}) {
+  const want = new Set(paths)
+  const lines = new Map()
+  const tasks = new Set()
+  let any = false
+  for (const h of history || []) {
+    if (!h || !want.has(h.path) || h.pulled || h.seed || !h.by || isRelay(h.by) || (h.ts || 0) < (sinceFor ? (sinceFor(h.path) || 0) : since)) continue
+    any = true
+    lines.set(h.by, (lines.get(h.by) || 0) + (h.added || 0) + (h.removed || 0) + (h.kind === 'deleted' || h.kind === 'created' ? 1 : 0))
+    tasks.add(h.task && h.task.id ? `${h.task.id}\0${h.task.title || ''}` : '')
+  }
+  const ranked = [...lines].sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : 1)).map(([n]) => n)
+  const one = any && tasks.size === 1 && !tasks.has('') ? [...tasks][0].split('\0') : null
+  return { author: ranked[0] || null, others: ranked.slice(1), task: one ? { id: one[0], title: one[1] } : null }
+}
+
+/**
+ * The paths git ignores among `paths`, by the repository's own .gitignore files (every level,
+ * git's own matching: `git check-ignore` over the ignore files as the session has them), plus
+ * .quiltignore and Quilt's always-ignored list.
+ */
+export async function ignoredPaths (dir, e, paths) {
+  const out = new Set()
+  if (!paths.length) return out
+  const ig = ignoreOf(e)
+  for (const rel of paths) if (isIgnored(ig, rel)) out.add(rel)
+  const left = paths.filter((p) => !out.has(p))
+  if (!left.length) return out
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'quilt-ignore-'))
+  try {
+    let any = false
+    for (const [rel, t] of e.files) {
+      if (rel !== '.gitignore' && !rel.endsWith('/.gitignore')) continue
+      fs.mkdirSync(path.dirname(path.join(tmp, rel)), { recursive: true })
+      fs.writeFileSync(path.join(tmp, rel), t.toString())
+      any = true
+    }
+    if (!any) return out
+    const r = await runGit(tmp, ['check-ignore', '-z', '--stdin', '--no-index'], { input: left.join('\0') + '\0', env: { GIT_DIR: dir, GIT_WORK_TREE: tmp } })
+    for (const rel of (r.out || '').split('\0')) if (rel) out.add(rel)
+  } finally { fs.rmSync(tmp, { recursive: true, force: true }) }
+  return out
+}
+
+/** The `filter` attribute of each path (from the repository's .gitattributes as the session has them): Map path -> name, for those with one. */
+async function filterAttrs (dir, e, paths) {
+  const out = new Map()
+  if (!paths.length) return out
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'quilt-attr-'))
+  try {
+    let any = false
+    for (const [rel, t] of e.files) {
+      if (rel !== '.gitattributes' && !rel.endsWith('/.gitattributes')) continue
+      fs.mkdirSync(path.dirname(path.join(tmp, rel)), { recursive: true })
+      fs.writeFileSync(path.join(tmp, rel), t.toString())
+      any = true
+    }
+    if (!any) return out
+    const r = await runGit(tmp, ['check-attr', '-z', '--stdin', 'filter'], { input: paths.join('\0') + '\0', env: { GIT_DIR: dir, GIT_WORK_TREE: tmp, GIT_INDEX_FILE: path.join(tmp, '.index') } })
+    const f = (r.out || '').split('\0')
+    for (let i = 0; i + 2 < f.length; i += 3) if (f[i + 2] !== 'unspecified' && f[i + 2] !== 'unset' && f[i + 2] !== 'set') out.set(f[i], f[i + 2])
+  } finally { fs.rmSync(tmp, { recursive: true, force: true }) }
+  return out
+}
+
+/** The base commit's tree: Map path -> { mode, sha }. */
+async function treeOf (dir, sha) {
+  const r = await runGit(dir, ['ls-tree', '-r', '-z', sha])
+  if (!r.ok) throw new GitFailed(`listing ${sha.slice(0, 7)}`, r.err)
+  const out = new Map()
+  for (const entry of r.out.split('\0')) {
+    if (!entry) continue
+    const tab = entry.indexOf('\t')
+    const [mode, , oid] = entry.slice(0, tab).split(' ')
+    out.set(entry.slice(tab + 1), { mode, sha: oid })
+  }
+  return out
+}
+
+/** The session's bytes for a path on the branch document, or null (not there), or undefined (a large stored file the relay can't read). */
+function sessionBytes (e, rel) {
+  const t = e.files.get(rel)
+  if (t) return Buffer.from(t.toString(), 'utf8')
+  const b = e.blobs.get(rel)
+  if (b && b.stored) return undefined
+  if (b) return Buffer.from(b.data || '', 'base64')
+  return null
+}
+
+/** GitHub refuses a file over this in a plain commit; beyond it, Git LFS (plan §10). */
+export const GITHUB_MAX_BYTES = 100 * 1024 * 1024
+
+/**
+ * A large file kept encrypted in storage, as the relay can read it (plan §10): through its own wrap of
+ * the file key (the branch syncs with GitHub and the owner agreed), fetched and decrypted, checked
+ * against the hash the session keeps. Resolves the bytes, or undefined when the relay has no wrap of
+ * the key (the file stays end-to-end encrypted). Throws when the stored file can't be read or is wrong.
+ */
+export async function storedBytes (room, e, rel) {
+  const b = e.blobs.get(rel)
+  if (!b || !b.stored || !room.relayFileKey || !e.relayKeys) return undefined
+  const w = e.relayKeys.get(`${b.stored.key}:${room.relayFileKey.id}`)
+  const fileKey = w ? unwrapAsRelay(w, room.relayFileKey.privateKey) : null
+  if (!fileKey) return undefined
+  const store = room.blobStore
+  if (!store) throw new Error('this relay keeps no stored files')
+  let sealed
+  if (typeof store.file === 'function') sealed = fs.readFileSync(store.file(room.name, b.stored.id))
+  else {
+    const t = await store.downloadTarget(room.name, b.stored.id)
+    const res = await fetch(t.url)
+    if (!res.ok) throw new Error(`storage answered ${res.status}`)
+    sealed = Buffer.from(await res.arrayBuffer())
+  }
+  const plain = decryptBlob(sealed, fileKey)
+  if (crypto.createHash('sha1').update(plain).digest('hex') !== b.hash) throw new Error('the stored file isn\'t the one the session has')
+  return plain
+}
+
+/**
+ * A text with git's conflict markers, settled the way Quilt merges: each <<<<<<< … ======= … >>>>>>>
+ * block becomes both sides' lines (shared leading and trailing lines once); with the base recorded
+ * (||||||| in diff3 style), lines only one side changed are kept and lines both changed are the first
+ * side's. Returns the text, or null when the markers aren't whole blocks.
+ */
+export function settleMarkers (text) {
+  const lines = text.split('\n')
+  const out = []
+  const mark = (l, c) => l === c.repeat(7) || l.startsWith(`${c.repeat(7)} `)
+  for (let i = 0; i < lines.length; i++) {
+    if (!mark(lines[i], '<')) { if (mark(lines[i], '>')) return null; out.push(lines[i]); continue }
+    const a = []; let o = null; const b = []
+    let part = a
+    let j = i + 1
+    for (; j < lines.length; j++) {
+      const l = lines[j]
+      if (mark(l, '<')) return null
+      if (mark(l, '|') && part === a) { o = []; part = o; continue }
+      if (l === '=======' && part !== b) { part = b; continue }
+      if (mark(l, '>')) break
+      part.push(l)
+    }
+    if (j >= lines.length || part !== b) return null
+    const nl = (ls) => ls.length ? `${ls.join('\n')}\n` : ''
+    const both = !a.length ? b : !b.length ? a : mergeAuto(o ? nl(o) : '', nl(a), nl(b), { oursNewer: true }).text.split('\n').slice(0, -1)
+    out.push(...both)
+    i = j
+  }
+  return out.join('\n')
+}
+
+/**
+ * Builds the commit for branch `key` on `base`: the base's tree with every session file that
+ * differs applied, and the deletions the session made since the base. Resolves
+ * { sha, tree, changed: [paths], skipped: { ignored, markers, held, claimed, special, large } } or
+ * { sha: null, skipped } when nothing would change. `only`: limit to these paths (quilt_commit).
+ */
+export async function buildCommit (room, key, { dir, base, message = '', by = '', only = null, now = Date.now(), upstream = null, own = null, lfs = null }) {
+  const e = room.branchDoc(key)
+  const state = syncStateOf(room, key)
+  const baseTree = await treeOf(dir, base)
+  const skipped = { ignored: [], markers: [], held: [], claimed: [], special: [], large: [], encrypted: [], unreadable: [], lfs: [] }
+  const held = new Set(state.held.map((h) => h.path))
+  const history = e.doc.getArray('history').toArray()
+  const since = state.baseAt || 0
+  // What the session has: every file on the branch document.
+  const candidates = new Map() // path -> Buffer | null (delete)
+  const paths = new Set([...e.files.keys(), ...e.blobs.keys()])
+  // Large files kept encrypted in storage (plan §10): read by the relay when it may (its wrap of the key), else left out with a notice.
+  const stored = new Map()
+  const unreadable = new Set()
+  for (const rel of paths) {
+    const b = e.blobs.get(rel)
+    if (!b || !b.stored || !isSafeRelPath(rel) || (only && !only.includes(rel))) continue
+    let buf
+    try { buf = await storedBytes(room, e, rel) } catch (err) { (room.log || (() => {}))(`[${room.name}] ${key}: could not read the stored ${rel}: ${err.message}`); unreadable.add(rel) }
+    if (buf) stored.set(rel, buf)
+  }
+  for (const rel of paths) {
+    if (!isSafeRelPath(rel) || (only && !only.includes(rel))) continue
+    const buf = sessionBytes(e, rel) ?? stored.get(rel)
+    if (buf === undefined) { (unreadable.has(rel) ? skipped.unreadable : skipped.encrypted).push(rel); continue } // stored, and the relay may not (or could not) read it
+    const was = baseTree.get(rel)
+    if (was && was.sha === gitBlobSha(buf)) continue
+    candidates.set(rel, buf)
+  }
+  // On a live branch whose target moved on (addendum 16.5): a file the session has as the target has it, and the target
+  // changed since the live branch started, is the target's change, already there: not the session's to send again.
+  let target = null
+  let fork = null
+  if (upstream) { target = await treeOf(dir, upstream.target); fork = await treeOf(dir, upstream.fork) }
+  const theirs = (rel, buf) => {
+    if (!target) return false
+    const t = target.get(rel)
+    const f = fork.get(rel)
+    if (buf === null) return !t && !!f
+    return !!t && t.sha === gitBlobSha(buf) && (!f || f.sha !== t.sha)
+  }
+  for (const [rel, buf] of [...candidates]) if (theirs(rel, buf)) candidates.delete(rel)
+  // Deletions the session made since the base (its history says so; a file Quilt never synced is not a deletion).
+  for (const h of history) {
+    if (!h || h.kind !== 'deleted' || h.pulled || h.seed || (h.ts || 0) < since || !baseTree.has(h.path) || paths.has(h.path)) continue
+    if (only && !only.includes(h.path)) continue
+    if (theirs(h.path, null)) continue
+    candidates.set(h.path, null)
+  }
+  const ignored = await ignoredPaths(dir, e, [...candidates.keys()])
+  const changes = new Map()
+  const lfsPaths = new Set()
+  const filters = await filterAttrs(dir, e, [...candidates.keys()])
+  for (const [rel, buf] of candidates) {
+    const was = baseTree.get(rel)
+    // git's rule: a file the repository already tracks is committed even when a .gitignore matches it now (addendum 16.12).
+    if (ignored.has(rel) && !was) { skipped.ignored.push(rel); continue }
+    // The relay never runs a repository's filters (addendum 16.12): text/eol only; LFS through its batch API (§10), others refused.
+    if (filters.get(rel) && filters.get(rel) !== 'lfs') { (skipped.filtered = skipped.filtered || []).push(rel); continue }
+    const viaLfs = filters.get(rel) === 'lfs' && buf !== null
+    if (held.has(rel)) { skipped.held.push(rel); continue }
+    const c = room.claimFor ? room.claimFor(rel, key) : null
+    if (c && c.by !== by) { skipped.claimed.push(rel); continue } // a member's own held files go when they commit now
+    if (was && SPECIAL.has(was.mode)) { skipped.special.push(rel); continue }
+    // Stored large files (read by the relay) go up to GitHub's own limit; past it, or through filter=lfs, Git LFS.
+    const limit = viaLfs ? Infinity : stored.has(rel) ? GITHUB_MAX_BYTES : (buf && buf.includes(0) ? MAX_BINARY_BYTES : MAX_TEXT_BYTES)
+    if (buf && buf.length > limit) { (stored.has(rel) ? skipped.lfs : skipped.large).push(rel); continue }
+    if (buf && !buf.includes(0) && hasMarkers(buf.toString('utf8'))) {
+      // Conflict markers a git merge left: Quilt settles them in the session (both sides' lines kept) and commits that.
+      const settled = settleMarkers(buf.toString('utf8'))
+      if (settled === null) { skipped.markers.push(rel); continue }
+      applyWrites(room, e, new Map([[rel, settled]]), { bins: new Map(), now })
+      ;(skipped.settled = skipped.settled || []).push(rel)
+      changes.set(rel, Buffer.from(settled, 'utf8'))
+      continue
+    }
+    if (viaLfs) {
+      // Through Git LFS: the bytes to GitHub's LFS store, the pointer in the commit.
+      if (!lfs || !lfs.url) { skipped.lfs.push(rel); continue }
+      try { changes.set(rel, Buffer.from(await lfsUpload({ remoteUrl: lfs.url, token: lfs.token, bytes: buf, fetch: lfs.fetch }), 'utf8')); lfsPaths.add(rel) } catch (err) { (room.log || (() => {}))(`[${room.name}] ${key}: ${rel} through Git LFS: ${err.message}`); skipped.lfs.push(rel) }
+      continue
+    }
+    if (was) {
+      const r = await runGit(dir, ['cat-file', '-p', was.sha], { buffer: true })
+      if (r.ok && r.out.subarray(0, 24).toString() .startsWith(LFS_POINTER)) { skipped.special.push(rel); continue }
+    }
+    changes.set(rel, buf)
+  }
+  // A case-only rename (README.md → Readme.md) goes as two commits, the deletion first, so a case-insensitive checkout never loses the file.
+  const lower = new Map()
+  for (const [rel, buf] of changes) if (buf === null) lower.set(rel.toLowerCase(), rel)
+  skipped.renameWait = []
+  for (const [rel, buf] of changes) if (buf !== null && !baseTree.has(rel) && lower.has(rel.toLowerCase()) && lower.get(rel.toLowerCase()) !== rel) skipped.renameWait.push(rel)
+  for (const rel of skipped.renameWait) changes.delete(rel)
+  if (!changes.size) return { sha: null, tree: null, changed: [], skipped }
+  // A member's own commit (quilt_git_commit): others' changes in these files, not in git yet, go in only with with_others (they are co-authors then).
+  let ownOthers = null
+  if (own) {
+    const others = new Map()
+    for (const [rel, buf] of changes) {
+      const entries = history.filter((h) => h && h.path === rel)
+      const was = baseTree.get(rel)
+      const binary = (buf && buf.includes(0)) || e.blobs.get(rel)
+      let names
+      if (!binary) {
+        const before = was ? (await runGit(dir, ['cat-file', '-p', was.sha], { buffer: true })).out : null
+        names = othersInChange({ before: before ? before.toString('utf8') : '', after: buf ? buf.toString('utf8') : '', entries, me: own.who })
+      } else names = othersEditing([rel], history, { me: own.who, since: (state.pushedAt || {})[rel] || state.baseAt || 0 }).get(rel) || []
+      names = names.filter((n) => !isRelay(n))
+      if (names.length) others.set(rel, names)
+    }
+    if (others.size && !own.withOthers) return { sha: null, tree: null, changed: [], skipped, others }
+    ownOthers = [...new Set([...others.values()].flat())]
+  }
+  // The tree: the base's, with the changes applied through a temporary index and an empty work tree holding the
+  // repository's .gitattributes files, as git add stores files (text/eol rules honoured).
+  const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'quilt-index-'))
+  const index = path.join(scratch, 'index')
+  const worktree = path.join(scratch, 'tree')
+  fs.mkdirSync(worktree)
+  for (const [rel, t] of e.files) {
+    if (rel !== '.gitattributes' && !rel.endsWith('/.gitattributes')) continue
+    fs.mkdirSync(path.dirname(path.join(worktree, rel)), { recursive: true })
+    fs.writeFileSync(path.join(worktree, rel), t.toString())
+  }
+  // Run from the work tree with GIT_DIR at the mirror: only then does git apply the attributes to what it hashes.
+  const env = { GIT_DIR: dir, GIT_INDEX_FILE: index, GIT_WORK_TREE: worktree }
+  const wt = worktree
+  try {
+    const read = await runGit(wt, ['read-tree', base], { env })
+    if (!read.ok) throw new GitFailed('reading the base tree', read.err)
+    for (const [rel, buf] of changes) {
+      if (buf === null) {
+        const rm = await runGit(wt, ['update-index', '--force-remove', '--', rel], { env })
+        if (!rm.ok) throw new GitFailed(`removing ${rel}`, rm.err)
+        continue
+      }
+      const blob = await runGit(wt, ['hash-object', '-w', '--stdin', ...(lfsPaths.has(rel) ? ['--no-filters'] : ['--path', rel])], { input: buf, env })
+      if (!blob.ok) throw new GitFailed(`storing ${rel}`, blob.err)
+      const mode = (baseTree.get(rel) || {}).mode || (e.modes && e.modes.get && e.modes.get(rel) === 'x' ? '100755' : '100644')
+      const add = await runGit(wt, ['update-index', '--add', '--cacheinfo', `${mode},${blob.out.trim()},${rel}`], { env })
+      if (!add.ok) throw new GitFailed(`adding ${rel}`, add.err)
+    }
+    const tree = await runGit(wt, ['write-tree'], { env })
+    if (!tree.ok) throw new GitFailed('writing the tree', tree.err)
+    const treeSha = tree.out.trim()
+    const baseTreeSha = (await runGit(dir, ['rev-parse', `${base}^{tree}`])).out.trim()
+    if (treeSha === baseTreeSha) return { sha: null, tree: treeSha, changed: [], skipped }
+    const changed = [...changes.keys()].sort()
+    const pushedAt = state.pushedAt || {}
+    const who = blameBatch(history, changed, { sinceFor: (rel) => pushedAt[rel] || 0 })
+    const authorName = by || who.author || RELAY_BY
+    const author = authorOf(room, authorName)
+    // A member's own commit names exactly the others whose lines are in it; a batch, everyone who changed its files since the last push.
+    const coAuthors = (ownOthers || [who.author, ...who.others]).filter((n) => n && n !== authorName && !isRelay(n)).map((n) => authorOf(room, n))
+    const subject = String(message || '').trim() || (who.task && who.task.title ? who.task.title : editsMessage(changed))
+    const body = [subject, ...(coAuthors.length ? ['', ...coAuthors.map((a) => `Co-authored-by: ${a.name} <${a.email}>`)] : [])].join('\n')
+    const ts = Math.floor(now / 1000)
+    const committer = (room.cfg && room.cfg.committer) || COMMITTER
+    const c = await runGit(wt, ['commit-tree', treeSha, '-p', base, '-F', '-'], { input: body + '\n', env: { ...env, GIT_AUTHOR_NAME: author.name, GIT_AUTHOR_EMAIL: author.email, GIT_AUTHOR_DATE: `${ts} +0000`, GIT_COMMITTER_NAME: committer.name, GIT_COMMITTER_EMAIL: committer.email, GIT_COMMITTER_DATE: `${ts} +0000` } })
+    if (!c.ok) throw new GitFailed('making the commit', c.err)
+    return { sha: c.out.trim(), tree: treeSha, changed, skipped, author: authorName, coAuthors: coAuthors.map((a) => a.name), subject, contents: changes }
+  } finally { fs.rmSync(scratch, { recursive: true, force: true }) }
+}
+
+/** People whose folder on branch `key` has local commits ahead of GitHub (and not behind): their names. */
+export function foldersAhead (room, key) {
+  const out = []
+  if (!room.awareness || !room.conns) return out
+  const states = room.awareness.getStates()
+  for (const [ws, ids] of room.conns) {
+    if (ws.branch !== key) continue
+    const a = room.access && room.access.get(ws)
+    if (a && a.kind === 'agent') continue
+    for (const id of ids) {
+      const g = states.get(id)?.git
+      const u = g && g.upstream
+      if (u && u.ahead > 0 && !(u.behind > 0) && !g.held) out.push(room.names ? room.names.get(ws) : '')
+    }
+  }
+  return out
+}
+
+/** Whether the mirror has commit `sha`, fetching `refs` (the branch, the one it was cut from) until it does. Throws GitFailed for sign-in or network trouble. */
+/**
+ * The relay put branch `key`'s session at GitHub commit `sha` (a push, a replay, a recovered push): the branch
+ * record says so, the one in the room's meta included when a folder's presence replaced the record meanwhile
+ * (noteFolders), so folders following the relay (session.js memberAt) see it.
+ */
+function relayAt (room, key, rec, sha) {
+  const cur = upstreamsOf(room)[key]
+  for (const r of new Set([rec, ...(cur && cur.repo === rec.repo && cur.ref === rec.ref ? [cur] : [])])) { r.sha = sha; r.head = sha; r.relayHead = sha }
+}
+
+/** How long a push waits for an older app's folder bringing GitHub's commits in itself to say it has them (bringInFirst). */
+export const FOLDER_BRINGS_WAIT_MS = 10 * 1000
+
+/**
+ * Brings GitHub's head into the session before a push, holding the branch's queue (relay-sync.js bringInBranch).
+ * An older app's folder on the branch brings them in itself ('folder-brings'): it is waited for, up to
+ * FOLDER_BRINGS_WAIT_MS, as its word that it has them moves the base.
+ */
+async function bringInFirst (room, key, log) {
+  let inb = await bringInBranch(room, key, { log, now: () => Date.now(), inQueue: true })
+  for (const until = Date.now() + FOLDER_BRINGS_WAIT_MS; inb.state === 'folder-brings' && Date.now() < until && !room.destroyed;) {
+    await new Promise((resolve) => setTimeout(resolve, 500))
+    inb = await bringInBranch(room, key, { log, now: () => Date.now(), inQueue: true })
+  }
+  return inb
+}
+
+async function haveCommit (room, dir, sha, refs, token) {
+  if ((await runGit(dir, ['cat-file', '-e', `${sha}^{commit}`])).ok) return true
+  for (const ref of [...new Set(refs.filter(Boolean))]) {
+    await room.mirrors.fetch(dir, ref, { token })
+    if ((await runGit(dir, ['cat-file', '-e', `${sha}^{commit}`])).ok) return true
+  }
+  return false
+}
+
+/** The session's content of `rel` on `key`, as git's blob id (null: not there; undefined: a large stored file). */
+function sessionId (room, key, rel) {
+  const b = sessionBytes(room.branchDoc(key), rel)
+  return b === undefined ? undefined : b === null ? null : gitBlobSha(b)
+}
+
+/**
+ * A push the relay had started when it stopped (state.op, saved before the push): recognised by the
+ * commit being on GitHub, at or behind its head, even when GitHub moved on since (addendum 16.1).
+ * Accepted: the files that went in, unchanged since, are no longer pending, and the base moves to it
+ * when GitHub is still there (or inbound brings the rest). Not accepted: forgotten; the files are still
+ * pending and go with the next push. Never a second copy of the same commit. Resolves what it found.
+ */
+export async function recoverOp (room, key, { dir, token }) {
+  const state = syncStateOf(room, key)
+  const op = state.op
+  if (!op || op.kind !== 'push') return null
+  const rec = upstreamsOf(room)[key]
+  let head = null
+  try { head = (await room.mirrors.fetch(dir, op.branch, { token })).sha } catch { return null }
+  const has = head && (head === op.candidate || (await runGit(dir, ['merge-base', '--is-ancestor', op.candidate, head])).ok)
+  delete state.op
+  if (!has) { room.saveMeta(); return { accepted: false } }
+  state.pushed = op.candidate
+  if (op.branch === rec.ref) {
+    if (head === op.candidate) { state.base = op.candidate; relayAt(room, key, rec, op.candidate) }
+    for (const [rel, id] of Object.entries(op.files || {})) if (sessionId(room, key, rel) === id) delete state.pending[rel]
+  } else if (state.protected) state.protected.head = head === op.candidate ? op.candidate : state.protected.head
+  room.saveMeta()
+  room.log && room.log(`[${room.name}] ${key}: ${op.candidate.slice(0, 7)} was pushed before the relay stopped${head !== op.candidate ? ` (GitHub has moved on to ${head.slice(0, 7)} since)` : ''}`)
+  return { accepted: true, head }
+}
+
+/** The outbound side of a room: batches per branch, and the push. */
+export function outboundFor (room) {
+  const timers = new Map() // key -> { quiet, max, first }
+  const retryTimers = new Map() // key -> the next try after GitHub was out of reach
+  const log = room.log || (() => {})
+  const cfg = room.cfg || {}
+  const quietMs = Number.isFinite(cfg.syncQuietMs) ? cfg.syncQuietMs : SYNC_QUIET_MS
+  const maxMs = Number.isFinite(cfg.syncMaxMs) ? cfg.syncMaxMs : SYNC_MAX_MS
+
+  const clear = (key) => { const t = timers.get(key); if (t) { clearTimeout(t.quiet); clearTimeout(t.max); timers.delete(key) } }
+
+  /** A change on `key` (not the relay's own): pending, and the batch window starts or restarts. */
+  const note = (key, rel, { now = Date.now() } = {}) => {
+    if (!liveSyncOn(room, key) || !isSafeRelPath(rel)) return false
+    const state = syncStateOf(room, key)
+    const fresh = !state.pending[rel]
+    state.pending[rel] = now
+    if (fresh) tellSoon() // the branch's count of files not committed changed: the apps and agents hear it
+    schedule(key, { now })
+    return true
+  }
+
+  // The branch list goes out at most twice a second for new uncommitted files (an edit burst is one update).
+  let tellTimer = null
+  const tellSoon = () => {
+    if (tellTimer) return
+    tellTimer = setTimeout(() => { tellTimer = null; room.saveMeta(); if (room.broadcastBranches) room.broadcastBranches() }, 500)
+    tellTimer.unref?.()
+  }
+
+  /** The batch window for `key`: quietMs after the last change, or maxMs after the first pending one. */
+  const schedule = (key, { now = Date.now(), at = 0 } = {}) => {
+    const asked = Array.isArray(syncStateOf(room, key).asked) && syncStateOf(room, key).asked.length
+    // A commit someone asked for, waiting for the push budget: it goes at `at` (the relay's own batches only with its timer on).
+    if (at && (cfg.syncAuto === true || asked)) { const t = timers.get(key) || {}; clearTimeout(t.quiet); clearTimeout(t.max); t.quiet = setTimeout(() => (cfg.syncAuto === true ? flush(key, { auto: true }) : runAsked(key)).catch(() => {}), Math.max(0, at - now)); t.quiet.unref?.(); timers.set(key, t); return }
+    if (cfg.syncAuto !== true) return
+    const state = syncStateOf(room, key)
+    const first = Math.min(...Object.values(state.pending), now)
+    const t = timers.get(key) || { first }
+    clearTimeout(t.quiet)
+    t.quiet = setTimeout(() => flush(key, { auto: true }).catch(() => {}), quietMs)
+    t.quiet.unref?.()
+    if (!t.max) { t.max = setTimeout(() => flush(key, { auto: true }).catch(() => {}), Math.max(0, maxMs - (now - first))); t.max.unref?.() }
+    timers.set(key, t)
+  }
+
+  /**
+   * Commits and pushes what is pending on `key` now (quilt_commit, the batch window, a release):
+   * { state: 'pushed', sha, changed, skipped } · 'nothing' · 'moved' (the remote kept moving) ·
+   * 'protected' · 'paused' (sign-in or the repository refused: told) · 'off' · 'error'.
+   */
+  /**
+   * A commit asked for (quilt_git_commit, a person adopting work): made now. One GitHub couldn't take
+   * (out of reach, or refusing the relay) is kept and made when it answers, in the order asked.
+   */
+  const flush = async (key, o = {}) => {
+    const state = syncStateOf(room, key)
+    let ask = o.message && !o.auto ? { message: o.message, by: o.by || '', only: o.only || null, own: o.own || null, at: Date.now() } : null
+    if (ask) {
+      const list = Array.isArray(state.asked) ? state.asked : []
+      const same = list.find((a) => a.message === ask.message && a.by === ask.by && JSON.stringify(a.only) === JSON.stringify(ask.only))
+      if (same) ask = same // asked again (or made from the list): it keeps its place
+      else state.asked = [...list, ask].slice(-20)
+    }
+    let r
+    try { r = await flushNow(key, o) } finally {
+      if (ask && !(r && ((r.state === 'paused' && r.why !== 'lease') || r.state === 'queued'))) {
+        state.asked = (state.asked || []).filter((a) => a !== ask)
+        if (!state.asked.length) delete state.asked
+        room.saveMeta()
+      }
+    }
+    return r
+  }
+
+  const flushNow = async (key, { message = '', by = '', only = null, auto = false, own = null } = {}) => {
+    clear(key)
+    if (auto && cfg.syncAuto !== true) return { state: 'off' } // the relay's own timer is off: commits happen when someone asks
+    if (!liveSyncOn(room, key)) return { state: 'off' }
+    const recs = upstreamsOf(room)
+    const rec = recs[key]
+    const state = syncStateOf(room, key)
+    if (!state.base && rec.sha) state.base = rec.sha
+    if (!state.base) return { state: 'off' }
+    if (state.paused) {
+      const until = Number.isFinite(state.paused.until) ? state.paused.until : state.paused.at + 5 * 60 * 1000
+      if (Date.now() < until) return { state: 'paused', why: state.paused.why, retryIn: until - Date.now() }
+    }
+    // §6: a person's folder on the branch has commits ahead of GitHub: theirs go first (their message wins), for up to 30 s.
+    if (!message && !only) {
+      const ahead = foldersAhead(room, key)
+      if (ahead.length) {
+        if (!state.aheadSince) state.aheadSince = Date.now()
+        if (Date.now() - state.aheadSince < (Number.isFinite(cfg.folderAheadWaitMs) ? cfg.folderAheadWaitMs : FOLDER_AHEAD_WAIT_MS)) { schedule(key); return { state: 'waiting', for: ahead } }
+      } else delete state.aheadSince
+    }
+    // §5.4: a branch deleted on GitHub comes back with the next commit, unless the owner turned that off.
+    if (rec.gone && (room.meta.recreateDeleted !== true || rec.merged)) return { state: 'deleted', why: rec.problem || `${rec.ref} was deleted on GitHub` }
+    const repo = parseRepo(`https://${rec.repo}`)
+    let dir, token
+    try {
+      // Who the commit is for: their GitHub permissions count when the org requires GitHub (plan §2).
+      const actor = by ? everyone(room).find((m) => m.name === by) : null
+      const t = room.gitTokenState ? await room.gitTokenState(repo, { access: 'write', actingFor: actor && /^(person|agent):/.test(actor.id) ? actor.id : '' }) : { token: await room.gitToken(repo, { access: 'write' }) }
+      if (!t.token && (t.state === 'not-allowed' || t.require)) {
+        rec.problem = t.state === 'not-allowed' ? `${t.why || `this workspace doesn't allow ${rec.repo}`}: nothing is committed to it from here` : `the org requires GitHub: ${by || 'the committer'}'s commits go when the person ${by && actor && actor.kind === 'agent' ? 'it works for' : 'committing'} connects a GitHub account that may write to ${rec.repo}`
+        room.saveMeta(); room.broadcastBranches()
+        return { state: 'refused', why: rec.problem }
+      }
+      token = t.token
+      dir = (await room.mirrors.ensure(repo, { url: room.gitRemoteUrl(repo) })).dir
+    } catch (err) { log(`[${room.name}] ${key}: could not open the mirror: ${err.message}`); return { state: 'error' } }
+    return room.mirrors.queue(repo.slug, rec.ref, async () => {
+      if (state.op) await recoverOp(room, key, { dir, token })
+      // §8: one live session per repo@branch. Without the lease, this session's work goes to a branch of its own,
+      // with a pull request (as for a protected branch); with the API out of reach, nobody pushes (addendum 16.6).
+      if (room.leases && (!state.protected || state.protected.leased)) {
+        const lease = await room.leases.ensure({ repo: rec.repo, branch: rec.ref, room: room.name })
+        if (lease.error) { rec.problem = `commits to ${rec.ref} wait: the relay can't confirm this session holds the branch (${lease.error})`; room.saveMeta(); room.broadcastBranches(); return { state: 'paused', why: 'lease' } }
+        if (lease.ok) {
+          state.leaseGeneration = lease.generation
+          if (state.protected && state.protected.leased) { delete state.protected; delete rec.leasedBy; delete rec.problem; log(`[${room.name}] ${key}: this session holds the live sync of ${rec.ref} again`) }
+        } else {
+          rec.leasedBy = lease.room
+          if (!state.protected) state.protected = { since: Date.now(), head: null, pr: null, leased: true, entered: true, branch: `quilt/session-${room.name}/${rec.ref}` }
+        }
+      }
+      for (let attempt = 1; attempt <= PUSH_RETRIES; attempt++) {
+        const base = state.base
+        const started = Date.now()
+        try { if (!(await haveCommit(room, dir, base, [rec.ref, ...(rec.cutFrom && upstreamsOf(room)[rec.cutFrom] ? [upstreamsOf(room)[rec.cutFrom].ref] : [])], token))) { rec.problem = `the session's commit ${base.slice(0, 7)} on ${key} isn't on GitHub: the relay can't push on top of it`; room.saveMeta(); return { state: 'error' } } } catch (err) { return paused(key, state, rec, err) }
+        // Protected mode (§5.5): commits go on the live branch, on top of what is there; a live branch that no longer descends from the base (its pull request merged or closed) restarts from the base.
+        let live = null
+        let upstream = null
+        if (state.protected) {
+          const fate = await liveFate(key, state, rec, repo, dir, token, base)
+          if (fate === 'merged' || fate === 'gone' || (!state.protected.head && !state.protected.entered)) {
+            // The live branch's pull request merged (or the live branch is gone): the old live branch goes, and the branch
+            // itself is tried again first; its rules put the session back in protected mode if they still refuse. What the
+            // merge didn't have is still a difference between the session and the new head, so it goes in the next commit.
+            if (fate !== 'gone') { try { await deleteRemoteBranch(dir, state.protected.branch || liveBranchOf(rec.ref), { token }) } catch (err) { log(`[${room.name}] ${key}: could not remove the old live branch: ${err.message}`) } }
+            log(`[${room.name}] ${key}: the live branch ${state.protected.branch || liveBranchOf(rec.ref)} ${fate === 'gone' ? 'was deleted on GitHub' : 'is merged'}; live work starts again from ${rec.ref} at ${base.slice(0, 7)}`)
+            const wasLeased = state.protected.leased
+            delete state.protected
+            if (wasLeased) { attempt--; const l = await room.leases.ensure({ repo: rec.repo, branch: rec.ref, room: room.name }); if (!l.ok && !l.error) { state.protected = { since: Date.now(), head: null, pr: null, leased: true, entered: true, branch: `quilt/session-${room.name}/${rec.ref}` }; rec.leasedBy = l.room } ; continue }
+          } else {
+            live = state.protected.branch || liveBranchOf(rec.ref)
+            if (fate === 'closed') { log(`[${room.name}] ${key}: pull request #${state.protected.pr ? state.protected.pr.number : '?'} was closed without merging; the live branch keeps the work and a new pull request opens with this push`); state.protected.pr = null; delete state.protected.closed }
+            // The target moved past the live branch's start (other work merged into it) while its pull request is open:
+            // the commit carries the session's own changes only, never the target's new ones again (no merge of histories).
+            if (state.protected.head) {
+              const fork = (await runGit(dir, ['merge-base', base, state.protected.head])).out.trim()
+              if (fork && fork !== base) upstream = { target: base, fork }
+            }
+          }
+        }
+        const parent = live && state.protected.head ? state.protected.head : base
+        let built
+        try { built = await buildCommit(room, key, { dir, base: parent, message, by, only, now: started, upstream, own, lfs: { url: room.gitRemoteUrl(repo), token } }) } catch (err) { log(`[${room.name}] ${key}: could not build the commit: ${err.message}`); return { state: 'error', why: err.message } }
+        if (built.others) return { state: 'others', others: built.others }
+        tellSkipped(key, state, built.skipped)
+        if (!built.sha) { for (const rel of Object.keys(state.pending)) if ((!only || only.includes(rel)) && !built.skipped.claimed.includes(rel) && !built.skipped.held.includes(rel) && !(built.skipped.renameWait || []).includes(rel)) delete state.pending[rel]; room.saveMeta(); return { state: 'nothing', skipped: built.skipped } }
+        crashPoint(room, 'capture')
+        // Addendum 16.11: the repository's push budget, shared by all its branches; a named commit waits for it too.
+        const wait = room.mirrors.pushWait ? room.mirrors.pushWait(repo.slug) : 0
+        if (wait > BUDGET_WAIT_MS) { schedule(key, { at: Date.now() + wait }); return { state: 'queued', in: wait } }
+        if (wait > 0) { await new Promise((r) => setTimeout(r, wait)); attempt--; continue }
+        // Addendum 16.6: right before pushing to the branch itself, the lease must still be good for a whole push.
+        if (!live && room.leases && !room.leases.valid({ repo: rec.repo, branch: rec.ref, room: room.name })) {
+          const l = await room.leases.ensure({ repo: rec.repo, branch: rec.ref, room: room.name })
+          if (l.error) return { state: 'paused', why: 'lease' }
+          if (!l.ok) { rec.leasedBy = l.room; state.protected = { since: Date.now(), head: null, pr: null, leased: true, entered: true, branch: `quilt/session-${room.name}/${rec.ref}` }; continue }
+          state.leaseGeneration = l.generation
+        }
+        // Addendum 16.1: the intent is on disk before the push, so a relay that dies mid-push recognises its own commit on restart (recoverOp).
+        state.op = { id: built.sha.slice(0, 12), kind: 'push', generation: state.leaseGeneration || null, branch: live || rec.ref, expected: live ? (state.protected.head || null) : base, candidate: built.sha, files: Object.fromEntries([...built.contents].map(([rel, b]) => [rel, b === null ? null : gitBlobSha(b)])), started }
+        room.saveMeta()
+        crashPoint(room, 'push')
+        let r
+        if (room.mirrors.spendPush) room.mirrors.spendPush(repo.slug)
+        try { r = await room.mirrors.push(dir, { branch: live || rec.ref, sha: built.sha, expected: live ? (state.protected.head || null) : base, token }) } catch (err) { delete state.op; room.saveMeta(); return paused(key, state, rec, err) }
+        if (r.state === 'slow') { delete state.op; room.saveMeta(); room.mirrors.slowDown && room.mirrors.slowDown(repo.slug, 60 * 1000); schedule(key, { at: Date.now() + 60 * 1000 }); log(`[${room.name}] ${key}: GitHub asked to slow down (${r.why}); the push waits a minute`); return { state: 'queued', in: 60 * 1000 } }
+        if (r.state === 'accepted') crashPoint(room, 'ack')
+        if (r.state !== 'accepted') { delete state.op; room.saveMeta() }
+        if (r.state === 'protected' && !live) {
+          // The branch's rules refuse direct pushes: from now on work goes through quilt/live/<branch> and one pull request.
+          state.protected = { since: started, head: null, pr: null, why: r.why, entered: true } // just refused: the live branch starts now (no restart check)
+          log(`[${room.name}] ${key}: ${rec.ref} is protected on GitHub (${r.why}); work goes through ${liveBranchOf(rec.ref)}`)
+          continue
+        }
+        if (r.state === 'accepted') {
+          if (live) { state.protected.head = built.sha } else { state.base = built.sha; state.baseAt = started }
+          state.pushed = built.sha
+          if (!state.pushedAt) state.pushedAt = {}
+          for (const rel of built.changed) state.pushedAt[rel] = started
+          delete state.op
+          // Only what went in is cleared: a file edited after it was read stays pending (addendum 16.1).
+          for (const rel of built.changed) if ((state.pending[rel] || 0) <= started && sessionId(room, key, rel) === (built.contents.get(rel) === null ? null : gitBlobSha(built.contents.get(rel)))) delete state.pending[rel]
+          // A commit of some files (quilt_git_commit) leaves the rest pending: they are still the session's, uncommitted.
+          for (const rel of Object.keys(state.pending)) if ((!only || only.includes(rel)) && !built.skipped.claimed.includes(rel) && !built.skipped.held.includes(rel) && !(built.skipped.renameWait || []).includes(rel) && !built.changed.includes(rel) && state.pending[rel] <= started) delete state.pending[rel]
+          delete state.paused
+          clearTimeout(retryTimers.get(key)); retryTimers.delete(key)
+          const back = !!rec.gone
+          if (!live) { relayAt(room, key, rec, built.sha); delete rec.problem; delete rec.gone }
+          if (back && room.postChat) room.postChat({ by: RELAY_BY, text: `${rec.ref} had been deleted on GitHub: it is back, with the session's work (${built.sha.slice(0, 7)}).`, kind: 'commit' })
+          await keepRefs(dir, room.name, key, { base: state.base, others: [...keptObjects(state), ...(live ? [built.sha] : [])] })
+          notePublished(room.doc, new Map([...built.contents].filter(([, b]) => b)), 'relay-publish')
+          notePushedMerges(room, key, built.sha, built.changed)
+          const full = `${repo.owner}/${repo.name}`
+          log(`[${room.name}] ${key}: pushed ${built.sha.slice(0, 7)} to ${full} ${live || rec.ref} (${plural(built.changed.length, 'file')}, by ${built.author})`)
+          if (room.postChat) room.postChat({ by: RELAY_BY, text: `${built.author}'s edits went to ${full} ${live || rec.ref} as ${built.sha.slice(0, 7)}: ${built.changed.slice(0, 8).join(', ')}${built.changed.length > 8 ? ` and ${built.changed.length - 8} more` : ''}${built.coAuthors.length ? ` (with ${built.coAuthors.join(', ')})` : ''}. https://github.com/${full}/commit/${built.sha}`, kind: 'commit' })
+          room.saveMeta(); room.broadcastBranches()
+          if (!live && room.tellPushed) room.tellPushed(key, built.sha)
+          gcMirror(dir).catch(() => {})
+          if (Object.keys(state.pending).length) schedule(key)
+          if (live) { state.protected.basedOn = base; try { await keepLivePull(key, state, rec, repo, token) } catch (err) { log(`[${room.name}] ${key}: could not keep the live pull request: ${err.message}`) } }
+          if (!live && state.pr) noteTaskRevision(room, state.pr.number, built.sha)
+          // An agent's own branch (quilt/<agent>/…): its pull request to the branch it was cut from opens with the first push, tied to its task (relay-commit.js).
+          const agent = Object.values(room.meta.members || {}).find((m) => m && m.kind === 'agent' && m.name && rec.ref.startsWith(agentPrefix(m.name)))
+          if (agent && rec.cutFrom && !state.pr && !live) {
+            openPullOnPush(room, { who: { name: agent.name, kind: 'agent', access: {} }, key, branch: rec.ref, files: built.changed, subject: built.subject, revision: built.sha }, { fetch: room.githubFetch, log })
+              .then((pr) => { if (pr) { state.pr = { number: pr.number, url: pr.url }; room.saveMeta() } })
+              .catch((err) => log(`[${room.name}] ${key}: pushed, but could not open the pull request: ${err.message}`))
+          }
+          return { state: 'pushed', sha: built.sha, changed: built.changed, skipped: built.skipped, author: built.author, subject: built.subject, ...(live ? { live } : {}) }
+        }
+        if (r.state === 'protected') { return protectedMode(key, state, rec, r) }
+        if (r.state === 'refused') { log(`[${room.name}] ${key}: push refused: ${r.why}`); return { state: 'error', why: r.why } }
+        if (live) {
+          // The live branch moved under us (someone pushed to it by hand): take its head as ours and build again on it.
+          state.protected.head = r.head || null
+          log(`[${room.name}] ${key}: ${live} moved on GitHub while pushing (now ${String(r.head || '').slice(0, 7)}); building on it (${attempt}/${PUSH_RETRIES})`)
+          continue
+        }
+        // The remote moved: bring it in (inbound first), then build again on the new head.
+        log(`[${room.name}] ${key}: ${rec.ref} moved on GitHub while pushing (now ${String(r.head || '').slice(0, 7)}); bringing it in first (${attempt}/${PUSH_RETRIES})`)
+        const inb = await bringInFirst(room, key, log)
+        if (!['brought', 'up-to-date'].includes(inb.state) || state.base === base) { rec.problem = `${rec.ref} moved on GitHub and the relay couldn't bring it in (${inb.state}); it tries again with the next change`; room.saveMeta(); return { state: 'moved', inbound: inb } }
+      }
+      schedule(key)
+      return { state: 'moved' }
+    })
+  }
+
+  const paused = (key, state, rec, err) => {
+    const why = err.kind === 'auth' ? 'auth' : err.kind === 'missing' ? 'missing' : 'unreachable'
+    const was = state.paused
+    const start = Number.isFinite(cfg.backoffStartMs) ? cfg.backoffStartMs : OUTAGE_START_MS
+    const max = Number.isFinite(cfg.backoffMaxMs) ? cfg.backoffMaxMs : OUTAGE_MAX_MS
+    const backoffMs = why === 'unreachable' ? Math.min(max, was && was.why === 'unreachable' && was.backoffMs ? was.backoffMs * 2 : start) : 5 * 60 * 1000
+    state.paused = { why, at: was && was.why === why ? was.at : Date.now(), text: err.message, backoffMs, until: Date.now() + backoffMs }
+    const full = rec.repo
+    rec.problem = why === 'auth' ? `GitHub refused the relay's sign-in for ${full} (app not installed on the repository, or its token revoked): commits wait in the session until a member connects GitHub again`
+      : why === 'missing' ? `${full} isn't on GitHub (renamed, removed, or Quilt isn't installed on it): commits wait in the session`
+        : `GitHub unreachable since ${new Date(state.paused.at).toISOString().slice(11, 16)} UTC: the session keeps working, and commits asked for go when it answers`
+    log(`[${room.name}] ${key}: ${rec.problem}${why === 'unreachable' ? ` (next try in ${Math.round(backoffMs / 1000)} s)` : ''}`)
+    const owner = room.meta && room.meta.ownerName
+    if (owner && room.postChat && why !== 'unreachable' && (!state.told || Date.now() - state.told > 6 * 60 * 60 * 1000)) {
+      state.told = Date.now()
+      room.postChat({ by: RELAY_BY, to: owner, text: `Commits from ${key} to ${full} are paused: ${rec.problem}. Files keep syncing between everyone here meanwhile.`, kind: 'commit' })
+    }
+    // The next try comes by itself for a commit someone asked for (or with the relay's own timer on): on recovery, what GitHub has comes in first, then the commit goes out.
+    if (cfg.syncAuto === true || (Array.isArray(state.asked) && state.asked.length)) {
+      clearTimeout(retryTimers.get(key))
+      const t = setTimeout(() => { retryTimers.delete(key); recover(key).catch(() => {}) }, backoffMs)
+      t.unref?.()
+      retryTimers.set(key, t)
+    }
+    room.saveMeta(); room.broadcastBranches()
+    return { state: 'paused', why, retryIn: backoffMs }
+  }
+
+  /** The commits asked for and not made yet (GitHub out of reach, or the push budget spent), in the order asked. */
+  const runAsked = async (key) => {
+    const state = syncStateOf(room, key)
+    let r = null
+    for (const a of [...(Array.isArray(state.asked) ? state.asked : [])]) {
+      r = await flush(key, { message: a.message, by: a.by, only: a.only, own: a.own })
+      if (r.state === 'paused' || r.state === 'queued') return r
+      if (r.state !== 'pushed' && r.state !== 'nothing') log(`[${room.name}] ${key}: the commit "${a.message}" asked for earlier couldn't be made (${r.state}${r.why ? `: ${r.why}` : ''})`)
+    }
+    return r
+  }
+
+  /** After an outage: inbound first, then outbound (plan §11). */
+  const recover = async (key) => {
+    const state = syncStateOf(room, key)
+    if (!state.paused) return null
+    state.paused.until = 0
+    const inb = await bringInBranch(room, key, { log })
+    if (['error', 'private', 'token-refused', 'missing'].includes(inb.state)) return paused(key, state, upstreamsOf(room)[key], Object.assign(new Error(inb.state), { kind: inb.state === 'error' ? 'unreachable' : 'auth' }))
+    // The commits asked for meanwhile, in order; then the relay's own batch when its timer is on.
+    const r = await runAsked(key)
+    if (r && (r.state === 'paused' || r.state === 'queued')) return r
+    delete state.paused
+    if (cfg.syncAuto === true) return flush(key, { auto: true })
+    room.saveMeta(); room.broadcastBranches()
+    return r || { state: 'nothing' }
+  }
+
+  /**
+   * Where the live branch stands (addendum 16.5), told apart from the target's head, the live head, the session and
+   * what is pending: 'merged' (its work is in the target: it restarts from the target's head), 'gone' (deleted on
+   * GitHub: it starts again from the target's head), 'closed' (its pull request closed unmerged: the branch keeps the
+   * work, and a new pull request opens), or 'open'. GitHub's pull request says which once the target has moved past
+   * the live branch's start; a merge commit or fast-forward that took the live head whole needs no asking.
+   */
+  const liveFate = async (key, state, rec, repo, dir, token, base) => {
+    const p = state.protected
+    if (!p.head) return 'open'
+    if ((await runGit(dir, ['merge-base', '--is-ancestor', p.head, base])).ok) return 'merged'
+    if (p.merged) return 'merged'
+    let there
+    try { there = (await remoteHead(dir, p.branch || liveBranchOf(rec.ref), { token })).sha } catch { there = undefined }
+    if (there === null) return 'gone'
+    const moved = !(await runGit(dir, ['merge-base', '--is-ancestor', base, p.head])).ok
+    if (p.pr && moved && p.askedFor !== base && !p.closed) {
+      try {
+        const gh = githubWriter({ fetch: room.githubFetch || globalThis.fetch, token, owner: repo.owner, name: repo.name })
+        const pr = await gh.pullRequest(p.pr.number)
+        p.askedFor = base
+        if (pr.merged) { p.merged = { at: Date.now(), ...(pr.sha ? { sha: pr.sha } : {}) }; return 'merged' }
+        if (pr.state !== 'open') p.closed = Date.now()
+      } catch (err) { log(`[${room.name}] ${key}: could not ask GitHub about pull request #${p.pr.number}: ${err.message}`) }
+    }
+    return p.closed ? 'closed' : 'open'
+  }
+
+  /** One pull request from the live branch into the protected branch ("Live work on <branch>"), opened once, and the panel's line. */
+  const keepLivePull = async (key, state, rec, repo, token) => {
+    if (!state.protected) return
+    const live = state.protected.branch || liveBranchOf(rec.ref)
+    const leased = !!state.protected.leased
+    const name = room.meta.name || room.name
+    if (!state.protected.pr) {
+      const gh = githubWriter({ fetch: room.githubFetch || globalThis.fetch, token, owner: repo.owner, name: repo.name })
+      const pr = await gh.pull({ title: leased ? `Live work from the session ${name} on ${rec.ref}` : `Live work on ${rec.ref}`, head: live, base: rec.ref, body: leased ? `${rec.ref} syncs with GitHub in another Quilt session, so this session's commits go through this pull request (one session per branch). Quilt keeps it open and adds each commit made in the session.` : `Commits from the Quilt session on \`${rec.ref}\`, which is protected: they go through this pull request. Quilt keeps it open and adds each commit made in the session; merge it when it is good.` })
+      state.protected.pr = { number: pr.number, url: pr.url }
+      if (!pr.existed && room.postChat) room.postChat({ by: RELAY_BY, text: leased ? `${rec.ref} syncs with GitHub in another session, so this session's commits go through pull request #${pr.number} (${live} → ${rec.ref}): ${pr.url}` : `${rec.ref} is protected on GitHub, so the session's commits go through pull request #${pr.number} (${live} → ${rec.ref}): ${pr.url}`, kind: 'commit' })
+    }
+    rec.problem = leased ? `${rec.ref} syncs with GitHub in another session: this session's commits go through PR #${state.protected.pr.number}` : `${rec.ref} is protected: work goes through PR #${state.protected.pr.number}`
+    room.saveMeta(); room.broadcastBranches()
+  }
+
+  const protectedMode = (key, state, rec, r) => {
+    state.protected = { at: Date.now(), why: r.why }
+    rec.problem = `${rec.ref} is protected on GitHub (${r.why}): direct pushes are refused`
+    log(`[${room.name}] ${key}: ${rec.problem}`)
+    room.saveMeta(); room.broadcastBranches()
+    return { state: 'protected', why: r.why }
+  }
+
+  /** Paths left out of a commit are said once each, to whoever last changed them. */
+  const tellSkipped = (key, state, skipped) => {
+    if (!state.told_paths) state.told_paths = {}
+    const e = room.branchDoc(key)
+    const history = e.doc.getArray('history').toArray()
+    const lastBy = (rel) => { for (let i = history.length - 1; i >= 0; i--) if (history[i] && history[i].path === rel && !history[i].pulled && history[i].by && !isRelay(history[i].by)) return history[i].by; return null }
+    const say = (rels, why) => {
+      for (const rel of rels) {
+        const k = `${why}\0${rel}`
+        if (state.told_paths[k]) continue
+        state.told_paths[k] = Date.now()
+        delete state.pending[rel]
+        const to = lastBy(rel)
+        if (to && room.postChat) room.postChat({ by: RELAY_BY, to, kind: 'nudge', text: `${rel} isn't pushed to GitHub: ${why}.` })
+      }
+    }
+    // Said each time (it is news each time), and the file goes in the commit: it stays pending until pushed.
+    const tell = (rels, what) => {
+      for (const rel of rels) {
+        const to = lastBy(rel)
+        if (to && room.postChat) room.postChat({ by: RELAY_BY, to, kind: 'nudge', text: `${rel}: ${what}.` })
+      }
+    }
+    say(skipped.ignored, 'git ignores it (the repository\'s .gitignore, .quiltignore or Quilt\'s own list)')
+    say(skipped.markers, 'it holds conflict markers that aren\'t a whole merge (a <<<<<<< without its ======= and >>>>>>>), so Quilt can\'t settle them; it goes with the next commit once they are gone')
+    tell(skipped.settled || [], 'it held conflict markers from a git merge, so Quilt settled them: both sides\' lines are kept (where git recorded the base, the lines both sides changed are the first side\'s). It goes to GitHub as it is now')
+    say(skipped.special, 'it is a symlink, a submodule or a Git LFS file on GitHub, which the relay never rewrites; change it from a folder with git')
+    say(skipped.large, 'it is larger than Quilt syncs')
+    say(skipped.filtered || [], 'the repository\'s .gitattributes put it through a filter, and the relay never runs a repository\'s filters (only text and line-ending rules); commit it from a folder with git')
+    say(skipped.encrypted || [], 'it is a large file kept end-to-end encrypted, and the session owner hasn\'t let the relay read large files (Let the relay commit large files, in the commit panel); commit it from a folder with git')
+    say(skipped.unreadable || [], 'the relay couldn\'t read it from storage (missing, or not the file the session has); it goes with the next commit once a member\'s app has stored it again')
+    say(skipped.lfs || [], 'it is over GitHub\'s 100 MB limit for a file (or Git LFS refused it): set up Git LFS for it (git lfs track, which adds it to .gitattributes), and the relay sends it through LFS')
+  }
+
+  /** Stops every batch timer (the room is closing, or a test replaces the controller). */
+  const stop = () => { for (const key of [...timers.keys()]) clear(key); for (const t of retryTimers.values()) clearTimeout(t); retryTimers.clear(); clearTimeout(tellTimer); tellTimer = null }
+
+  return { note, schedule, flush, recover, clear: (key) => clear(key), stop, pending: (key) => Object.keys(syncStateOf(room, key).pending) }
+}
+
+/** While a folder on the branch has local commits ahead of GitHub, the relay's own batch waits this long at most, so the person's commit (message and all) goes first (plan §6). */
+export const FOLDER_AHEAD_WAIT_MS = 30 * 1000
+/** The largest bundle of local commits a folder may hand to the relay. */
+export const MAX_BUNDLE_BYTES = 50 * 1024 * 1024
+
+/**
+ * A person's folder hands its local commits to the relay (it can't push them itself, or its branch
+ * diverged): `bundle` is `git bundle create` of them. Each commit goes onto the branch's head on
+ * GitHub with its own message and author: as it is when it already sits on the head (same commit,
+ * same id), else replayed (git merge-tree, the same change on the new head). A commit whose change
+ * GitHub already has (the relay pushed the session's copy of it) is skipped. A commit that changed
+ * the same lines as GitHub is combined by Quilt (replayMerge: the newer edit keeps those lines).
+ * Resolves { state: 'pushed', sha, published: [{ original, published }], skipped: [shas], merged } or
+ * { state: 'nothing' | 'refused', ... }; 'nothing' says the `head` of GitHub's the session is at
+ * (the folder follows that commit, never a newer one the session has yet to bring in: session.js publishLocal).
+ */
+export async function replayBundle (room, key, { who, bundle, head, ref = '' }, { log = room.log || (() => {}) } = {}) {
+  if (!liveSyncOn(room, key)) return { state: 'refused', why: 'this branch doesn\'t sync live with GitHub' }
+  const buf = Buffer.isBuffer(bundle) ? bundle : Buffer.from(String(bundle || ''), 'base64')
+  if (!buf.length || buf.length > MAX_BUNDLE_BYTES) return { state: 'refused', why: `a bundle of local commits is 1 byte to ${MAX_BUNDLE_BYTES / 1048576} MB` }
+  if (!/^[0-9a-f]{40}$/.test(String(head || ''))) return { state: 'refused', why: 'say which commit the bundle ends at' }
+  if (!/^refs\/heads\/[^\s~^:?*[\\]+$/.test(String(ref || ''))) return { state: 'refused', why: 'say which branch the bundle carries' }
+  const rec = upstreamsOf(room)[key]
+  const state = syncStateOf(room, key)
+  const repo = parseRepo(`https://${rec.repo}`)
+  const token = await room.gitToken(repo, { access: 'write' })
+  const dir = (await room.mirrors.ensure(repo, { url: room.gitRemoteUrl(repo) })).dir
+  return room.mirrors.queue(repo.slug, rec.ref, async () => {
+    const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'quilt-bundle-'))
+    try {
+      const file = path.join(scratch, 'local.bundle')
+      fs.writeFileSync(file, buf)
+      const incoming = `refs/quilt/incoming/${room.name}/${Date.now()}`
+      // What GitHub has that the session doesn't yet comes in first, before the folder's commits are in the mirror
+      // (so they can't be taken for GitHub's): the base moves past it only once the session has it.
+      await room.mirrors.fetch(dir, rec.ref, { token })
+      const remoteHead = (await runGit(dir, ['rev-parse', '--verify', '-q', `refs/remotes/origin/${rec.ref}`])).out.trim()
+      if (!remoteHead) return { state: 'refused', why: `${rec.ref} isn't on GitHub` }
+      if (state.base !== remoteHead) {
+        const inb = await bringInFirst(room, key, log)
+        if (state.base !== remoteHead && !['brought', 'up-to-date', 'recovered'].includes(inb.state)) return { state: 'refused', why: `GitHub moved and the relay couldn't bring it in yet (${inb.state}): try again` }
+      }
+      // The bundle's prerequisites (the folder's view of GitHub) are in the mirror now.
+      const f = await runGit(dir, ['fetch', '-q', file, `${ref}:${incoming}`])
+      if (!f.ok) return { state: 'refused', why: `the bundle didn't apply to the mirror: ${f.err.trim().split('\n').pop()}` }
+      if ((await runGit(dir, ['rev-parse', incoming])).out.trim() !== head) { await runGit(dir, ['update-ref', '-d', incoming]); return { state: 'refused', why: 'the bundle doesn\'t end at the commit it says' } }
+      return replayIncoming(room, key, { who, dir, incoming, head, remoteHead, token, log })
+    } finally { fs.rmSync(scratch, { recursive: true, force: true }) }
+  })
+}
+
+/**
+ * A folder's commits, in the mirror at ref `incoming` (ending at `head`), onto GitHub's head
+ * `remoteHead` of the session branch `key`: each one on the head already goes as it is; one whose
+ * change GitHub has already is skipped; any other is replayed with git merge-tree, keeping its author
+ * and message; lines both it and GitHub changed are combined (replayMerge). Then one fast-forward
+ * push. Resolves { state: 'pushed', sha, published, skipped, merged }, 'nothing', 'refused',
+ * 'protected' or 'moved'. Runs in the branch's queue.
+ */
+async function replayIncoming (room, key, { who, dir, incoming, head, remoteHead, token, log }) {
+  const rec = upstreamsOf(room)[key]
+  const state = syncStateOf(room, key)
+  {
+    {
+      const list = (await runGit(dir, ['rev-list', '--reverse', '--topo-order', `${remoteHead}..${incoming}`])).out.split('\n').filter(Boolean)
+      await runGit(dir, ['update-ref', '-d', incoming])
+      if (!list.length) return { state: 'nothing', head: remoteHead, why: 'GitHub already has those commits' }
+      // On GitHub's head already (merge commits and all): they go as they are, a fast-forward.
+      const ff = (await runGit(dir, ['merge-base', '--is-ancestor', remoteHead, head])).ok
+      if (!ff && (await runGit(dir, ['rev-list', '--merges', `${remoteHead}..${head}`])).out.trim()) return { state: 'refused', why: 'merge commits aren\'t replayed onto a newer head: merge GitHub\'s branch into yours and push again, or let the session sync the files' }
+      let tip = remoteHead
+      const published = []
+      const skipped = []
+      const merged = [] // files Quilt combined on the way: { path, lost, deleted, at: the local commit, github }
+      if (ff) { tip = head; for (const c of list) published.push({ original: c, published: c }) }
+      for (const c of ff ? [] : list) {
+        const parent = (await runGit(dir, ['rev-parse', `${c}^`])).out.trim()
+        if (parent === tip) { tip = c; published.push({ original: c, published: c }); continue } // already on the head: the commit itself
+        const mt = await runGit(dir, ['merge-tree', '--write-tree', '--name-only', '--no-messages', `--merge-base=${parent}`, tip, c])
+        let tree = mt.out.split('\n')[0].trim()
+        if (!/^[0-9a-f]{40}$/.test(tree)) return { state: 'refused', why: `git couldn't replay ${c.slice(0, 7)} onto GitHub's head` }
+        if (!mt.ok) {
+          // Lines this commit and GitHub both changed: Quilt combines them (the newer edit keeps those lines), nobody is asked.
+          const files = [...new Set(mt.out.split('\n').slice(1).map((l) => l.trim()).filter(Boolean))]
+          const r = await replayMerge(room, dir, { parent, tip, commit: c, tree, files })
+          if (!r) return { state: 'refused', why: `could not combine ${c.slice(0, 7)} with GitHub's changes` }
+          tree = r.tree
+          merged.push(...r.merged)
+        }
+        const tipTree = (await runGit(dir, ['rev-parse', `${tip}^{tree}`])).out.trim()
+        if (tree === tipTree) { skipped.push(c); continue } // GitHub has this change already (the relay pushed the session's copy)
+        const meta = (await runGit(dir, ['log', '-1', '--format=%an%x1f%ae%x1f%aI%x1f%B', c])).out
+        const [an, ae, ad, ...msg] = meta.split('\x1f')
+        const committer = (room.cfg && room.cfg.committer) || COMMITTER
+        const made = await runGit(dir, ['commit-tree', tree, '-p', tip, '-F', '-'], { input: msg.join('\x1f').replace(/\n+$/, '') + '\n', env: { GIT_AUTHOR_NAME: an, GIT_AUTHOR_EMAIL: ae, GIT_AUTHOR_DATE: ad, GIT_COMMITTER_NAME: committer.name, GIT_COMMITTER_EMAIL: committer.email } })
+        if (!made.ok) return { state: 'refused', why: `could not replay ${c.slice(0, 7)}` }
+        tip = made.out.trim()
+        published.push({ original: c, published: tip })
+      }
+      if (tip === remoteHead) return { state: 'nothing', head: remoteHead, skipped, why: 'GitHub already has every change in those commits' }
+      crashPoint(room, 'replay') // tests: the relay dies with the commits replayed, before pushing them
+      const r = await room.mirrors.push(dir, { branch: rec.ref, sha: tip, expected: remoteHead, token })
+      if (r.state !== 'accepted') return { state: r.state === 'protected' ? 'protected' : 'moved', why: r.why || 'GitHub moved meanwhile: try again' }
+      crashPoint(room, 'replay-ack') // tests: GitHub took them, and the relay dies before it notes so
+      // The branch moved by the person's commits: the session's base follows; what they changed is in the session already.
+      state.base = tip; state.pushed = tip; state.baseAt = Date.now()
+      relayAt(room, key, rec, tip)
+      if (!Array.isArray(state.replays)) state.replays = []
+      state.replays.push({ by: who.name, at: Date.now(), published, skipped })
+      state.replays = state.replays.slice(-50)
+      room.saveMeta(); room.broadcastBranches()
+      if (merged.length) sessionTakesMerges(room, key, { who, rec, tip, remoteHead, merged })
+      if (room.tellPushed) room.tellPushed(key, tip)
+      log(`[${room.name}] ${key}: pushed ${published.length} local commit${published.length === 1 ? '' : 's'} of ${who.name} (${tip.slice(0, 7)})${skipped.length ? `, ${skipped.length} already on GitHub` : ''}${merged.length ? `; combined ${merged.map((m) => m.path).join(', ')} with GitHub's changes` : ''}`)
+      if (room.postChat && !who.quiet) room.postChat({ by: RELAY_BY, text: `${who.name}'s ${published.length} local commit${published.length === 1 ? '' : 's'} went to ${rec.repo.replace(/^github\.com\//, '')} ${rec.ref} (${tip.slice(0, 7)}).`, kind: 'commit' })
+      return { state: 'pushed', sha: tip, published, skipped, ...(merged.length ? { merged: merged.map((m) => ({ path: m.path, lost: m.lost.length ? m.lost[0].side : null })) } : {}) }
+    }
+  }
+}
+
+/** A blob's key as planCatchUp keys files: text, "bin:<sha1>", or null when absent. */
+const keyOfBuf = (buf) => buf === null || buf === undefined ? null : looksBinary(buf) ? `bin:${crypto.createHash('sha1').update(buf).digest('hex')}` : buf.toString('utf8')
+
+/**
+ * The files git merge-tree couldn't merge while replaying `commit` onto `tip`, combined by Quilt
+ * (upstream.js combine) against `parent`: lines only one side changed are kept, lines both changed
+ * go to the newer edit (the local commit's time against GitHub's newest commit to the file), an
+ * edit beats a deletion, a binary is the newer version. Returns { tree, merged: [{ path, lost,
+ * deleted, at, key, github }] } with `tree` merge-tree's with those files replaced, or null.
+ */
+async function replayMerge (room, dir, { parent, tip, commit, tree, files }) {
+  const [atBase, atTip, atMine] = await Promise.all([filesAt(dir, parent, files), filesAt(dir, tip, files), filesAt(dir, commit, files)])
+  const mineAt = Number((await runGit(dir, ['log', '-1', '--format=%ct', commit])).out.trim()) * 1000 || 0
+  const modes = new Map()
+  for (const at of [tip, commit]) {
+    const r = await runGit(dir, ['ls-tree', '-z', at, '--', ...files])
+    for (const entry of r.out.split('\0')) { const tab = entry.indexOf('\t'); if (tab > 0 && !modes.has(entry.slice(tab + 1))) modes.set(entry.slice(tab + 1), entry.slice(0, tab).split(' ')[0]) }
+  }
+  const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'quilt-replay-'))
+  const env = { GIT_DIR: dir, GIT_INDEX_FILE: path.join(scratch, 'index') }
+  const merged = []
+  try {
+    if (!(await runGit(scratch, ['read-tree', tree], { env })).ok) return null
+    for (const rel of files) {
+      const bufs = { base: atBase.get(rel), tip: atTip.get(rel), mine: atMine.get(rel) }
+      if ([bufs.base, bufs.tip, bufs.mine].some((b) => b === undefined)) return null
+      const top = (await upstreamCommits(dir, parent, tip, rel))[0] || null
+      const mineNewer = mineAt >= ((top || {}).ts || 0)
+      // The local commit is "ours": its lines lost are told to whoever handed it over.
+      const r = combine(keyOfBuf(bufs.base), keyOfBuf(bufs.mine), keyOfBuf(bufs.tip), { oursNewer: mineNewer })
+      let out = null
+      if (r.key !== null) out = r.key === keyOfBuf(bufs.mine) ? bufs.mine : r.key === keyOfBuf(bufs.tip) ? bufs.tip : Buffer.from(r.key, 'utf8')
+      if (out === null) {
+        if (!(await runGit(scratch, ['update-index', '--force-remove', '--', rel], { env })).ok) return null
+      } else {
+        const blob = await runGit(scratch, ['hash-object', '-w', '--stdin'], { input: out, env })
+        if (!blob.ok) return null
+        if (!(await runGit(scratch, ['update-index', '--add', '--cacheinfo', `${modes.get(rel) || '100644'},${blob.out.trim()},${rel}`], { env })).ok) return null
+      }
+      merged.push({ path: rel, lost: r.lost, deleted: r.deleted || null, at: commit, key: r.key, mine: keyOfBuf(bufs.mine), bins: out && r.key && r.key.startsWith('bin:') ? out : null, github: top ? { name: top.name, email: top.email, ts: top.ts, sha: top.sha, member: memberForAuthor(room, top) } : null })
+    }
+    // A conflict merge-tree records at more than one stage (rename and delete, say) is gone once each path is set above.
+    const w = await runGit(scratch, ['write-tree'], { env })
+    if (!w.ok) return null
+    return { tree: w.out.trim(), merged }
+  } finally { fs.rmSync(scratch, { recursive: true, force: true }) }
+}
+
+/**
+ * After a replay that combined files (replayMerge): the session takes the combined version of each
+ * one it still has as the local commit had it (else it would push that back over GitHub's lines),
+ * and whoever's lines lost is told: the person who handed the commits over, or the activity log.
+ */
+function sessionTakesMerges (room, key, { who, rec, tip, remoteHead, merged }) {
+  const e = room.branchDoc ? room.branchDoc(key) : null
+  if (!e) return
+  const writes = new Map()
+  const bins = new Map()
+  for (const m of merged) {
+    const now = docKey(e, m.path)
+    if (now === undefined || now === m.key) continue
+    if (now === m.mine) { writes.set(m.path, m.key); if (m.bins) bins.set(m.key, m.bins); continue }
+    // Edited in the session since: that edit and the combined file, the session's edit kept where they overlap.
+    const r = combine(m.mine, now, m.key, { oursNewer: true })
+    if (r.key !== now) { writes.set(m.path, r.key); if (m.bins && r.key === m.key) bins.set(m.key, m.bins) }
+  }
+  if (writes.size) applyWrites(room, e, writes, { bins, now: Date.now() })
+  for (const m of merged) tellAutoMerge(room, key, { path: m.path, lost: m.lost, deleted: m.deleted, session: { name: who.name }, github: m.github, upstream: rec.name, head: remoteHead, keptIn: `your commit ${m.at.slice(0, 7)}` })
+}
+
+/**
+ * A push into the session's git view (relay-githttp.js), checked before git moves any ref (plan §9):
+ * branches only, never a deletion or a rewrite; an agent within the owner's policy ('off': nothing;
+ * 'branches': quilt/<agent>/… only; 'any': everything); no newly added file the repository's
+ * .gitignore ignores; credentials for whoever pushes (the workspace's access mode, the org's Require
+ * GitHub). Then the commits go to GitHub: onto a session branch's head through replayIncoming (GitHub
+ * moved: replayed), or straight to any other branch, fast-forward only. `env` is the hook's git
+ * environment (the pushed objects are in its quarantine). Resolves { ok, message, published: Map ref -> sha }.
+ */
+export async function receiveAgentPush (room, { who, name, updates, env }, { log = room.log || (() => {}) } = {}) {
+  const say = (message) => ({ ok: false, message: `Quilt: ${message}` })
+  const kind = String(who).startsWith('agent:') ? 'agent' : 'human'
+  const recs = upstreamsOf(room)
+  const def = recs[room.defaultKey] || Object.values(recs).find((r) => r && r.repo)
+  if (!def || !/^github\.com\//.test(def.repo || '')) return say('this session doesn\'t follow a GitHub repository')
+  const repo = parseRepo(`https://${def.repo}`)
+  const dir = (await room.mirrors.ensure(repo, { url: room.gitRemoteUrl(repo) })).dir
+  const t = room.gitTokenState ? await room.gitTokenState(repo, { access: 'write', actingFor: who }) : { token: await room.gitToken(repo, { access: 'write' }) }
+  if (!t.token) return say(t.state === 'not-allowed' ? `${t.why || `this workspace doesn't allow ${def.repo}`}, so nothing goes to GitHub from here` : t.require ? `the org requires GitHub: the person ${kind === 'agent' ? 'you work for' : 'pushing'} must connect a GitHub account that may write to ${def.repo.replace(/^github\.com\//, '')}` : `nobody in this session has connected GitHub with write access to ${def.repo.replace(/^github\.com\//, '')} (Connect GitHub in the app)`)
+  const token = t.token
+  // The push's objects are read from its quarantine (GIT_OBJECT_DIRECTORY); GIT_QUARANTINE_PATH itself stays out, or the mirror would refuse to take them.
+  const qenv = Object.fromEntries(Object.entries(env || {}).filter(([k, v]) => /^GIT_(DIR|OBJECT_DIRECTORY|ALTERNATE_OBJECT_DIRECTORIES)$/.test(k) && typeof v === 'string' && v))
+  const published = new Map()
+  const lines = []
+  for (const u of updates) {
+    if (!/^refs\/heads\/./.test(u.ref)) return say(`only branches are pushed through Quilt (not ${u.ref})`)
+    const branch = u.ref.slice('refs/heads/'.length)
+    if (!u.new) return say(`Quilt never deletes ${branch} on GitHub from a folder: ask a person to delete it there`)
+    const policy = agentCommitsOf(room)
+    // Git off is off for everyone (git for everyone): people's pushes too.
+    if (policy === 'off') return say(kind === 'agent' ? 'git is off for everyone in this session, so agents don\'t push here: ask a person for the commit with quilt_request_commit' : 'git is off for everyone in this session')
+    if (kind === 'agent') {
+      if (policy === 'branches' && !branch.startsWith(agentPrefix(name))) return say(`the session owner lets agents push only to branches of their own: ${agentPrefix(name)}<topic> (not ${branch}). Push there (git push origin HEAD:${agentPrefix(name)}<topic>); its pull request opens with the push`)
+    }
+    // The pushed commits into the mirror, from the push's quarantine, at a ref of their own.
+    const incoming = `refs/quilt/incoming/${room.name}/${Date.now()}-${published.size}`
+    const moved = await runGit(qenv.GIT_DIR || dir, ['push', '-q', dir, `${u.new}:${incoming}`], { env: qenv })
+    if (!moved.ok) { log(`[${room.name}] ${name}'s push: copying the commits into the mirror failed: ${moved.err.trim()}`); return say(`the relay couldn't take the commits (${moved.err.trim().split('\n').filter((l) => /error|fatal|rejected/i.test(l))[0] || 'git failed'})`) }
+    try {
+      // No file git ignores comes in by a push (a git add -f): the repository's .gitignore files as the pushed commit has them.
+      const base = u.old || (await runGit(dir, ['merge-base', u.new, `refs/remotes/origin/${def.ref}`])).out.trim() || null
+      const added = base ? (await runGit(dir, ['diff', '--name-only', '--no-renames', '--diff-filter=A', '-z', base, u.new])).out.split('\0').filter(Boolean) : (await runGit(dir, ['ls-tree', '-r', '--name-only', '-z', u.new])).out.split('\0').filter(Boolean)
+      const ignored = await ignoredInCommit(dir, u.new, added)
+      if (ignored.length) return say(`${ignored.slice(0, 5).join(', ')}${ignored.length > 5 ? ', …' : ''} ${ignored.length === 1 ? 'is' : 'are'} ignored by the repository's .gitignore: take ${ignored.length === 1 ? 'it' : 'them'} out of the commit (git rm --cached) and push again`)
+      const key = room.resolveKey ? room.resolveKey(branch) : branch
+      const rec = recs[key]
+      if (rec && rec.ref === branch && rec.repo === def.repo && liveSyncOn(room, key)) {
+        // A branch of the session: GitHub's newer commits come in first, then these go on its head.
+        const state = syncStateOf(room, key)
+        const r = await room.mirrors.queue(repo.slug, rec.ref, async () => {
+          await room.mirrors.fetch(dir, rec.ref, { token })
+          const remoteHead = (await runGit(dir, ['rev-parse', '--verify', '-q', `refs/remotes/origin/${rec.ref}`])).out.trim()
+          if (!remoteHead) return { state: 'refused', why: `${rec.ref} isn't on GitHub` }
+          if (state.base !== remoteHead) {
+            const inb = await bringInFirst(room, key, log)
+            if (state.base !== remoteHead && !['brought', 'up-to-date', 'recovered'].includes(inb.state)) return { state: 'refused', why: `GitHub moved and the relay couldn't bring it in yet (${inb.state}): try again` }
+          }
+          if (u.old && !(await runGit(dir, ['merge-base', '--is-ancestor', u.old, u.new])).ok) return { state: 'refused', why: 'that push would rewrite the branch' }
+          return replayIncoming(room, key, { who: { name, quiet: true }, dir, incoming, head: u.new, remoteHead, token, log })
+        })
+        if (r.state === 'nothing') { published.set(u.ref, (await runGit(dir, ['rev-parse', `refs/remotes/origin/${rec.ref}`])).out.trim()); lines.push(`${branch}: GitHub already has these changes`); continue }
+        if (r.state !== 'pushed') return say(r.state === 'protected' ? `${branch} is protected on GitHub: push to a branch of your own and open a pull request` : r.why || `GitHub didn't take it (${r.state}): fetch and push again`)
+        published.set(u.ref, r.sha)
+        lines.push(r.sha === u.new ? `${branch} on GitHub is at ${r.sha.slice(0, 7)}` : `${branch}: GitHub had moved, so your commits went on its head as ${r.sha.slice(0, 7)}${r.merged ? ` (Quilt combined ${r.merged.map((m) => m.path).join(', ')} with GitHub's changes: where both changed the same lines, the newer edit is kept)` : ''}; your folder follows it`)
+        continue
+      }
+      // Any other branch (an agent's own, new or not yet in the session): straight to GitHub, fast-forward only.
+      const r = await room.mirrors.queue(repo.slug, branch, async () => {
+        const remote = (await room.mirrors.fetch(dir, branch, { token }).catch(() => ({ sha: null }))).sha || null
+        if (remote && !(await runGit(dir, ['merge-base', '--is-ancestor', remote, u.new])).ok) return { state: 'moved', why: `${branch} moved on GitHub: fetch, merge or rebase onto it, and push again (never a force-push)` }
+        if (remote === u.new) return { state: 'accepted' }
+        return room.mirrors.push(dir, { branch, sha: u.new, expected: remote, token })
+      })
+      if (r.state !== 'accepted') return say(r.state === 'protected' ? `${branch} is protected on GitHub: ${r.why}` : r.why || `GitHub didn't take ${branch} (${r.state})`)
+      published.set(u.ref, u.new)
+      if (!room.meta.viewBranches || typeof room.meta.viewBranches !== 'object') room.meta.viewBranches = {}
+      room.meta.viewBranches[branch] = u.new
+      room.saveMeta()
+      lines.push(`${branch} on GitHub is at ${u.new.slice(0, 7)}`)
+    } finally { await runGit(dir, ['update-ref', '-d', incoming]) }
+  }
+  log(`[${room.name}] ${name} pushed through the relay: ${lines.join('; ')}`)
+  return { ok: true, message: `Quilt: ${lines.join('; ')}.`, published }
+}
+
+/** Which of `paths` (added in commit `sha`) the repository's .gitignore files, as that commit has them, ignore. */
+async function ignoredInCommit (dir, sha, paths) {
+  if (!paths.length) return []
+  const files = (await runGit(dir, ['ls-tree', '-r', '--name-only', '-z', sha])).out.split('\0').filter((f) => f === '.gitignore' || f.endsWith('/.gitignore'))
+  if (!files.length) return []
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'quilt-push-ignore-'))
+  try {
+    for (const f of files) {
+      const r = await runGit(dir, ['cat-file', 'blob', `${sha}:${f}`], { buffer: true })
+      if (!r.ok) continue
+      fs.mkdirSync(path.dirname(path.join(tmp, f)), { recursive: true })
+      fs.writeFileSync(path.join(tmp, f), r.out)
+    }
+    const r = await runGit(tmp, ['check-ignore', '-z', '--stdin', '--no-index'], { input: paths.join('\0') + '\0', env: { GIT_DIR: dir, GIT_WORK_TREE: tmp } })
+    return (r.out || '').split('\0').filter(Boolean)
+  } finally { fs.rmSync(tmp, { recursive: true, force: true }) }
+}
+
+/**
+ * A person adopts an agent's work (policy "off", or any agent branch): every file the agent's
+ * branch `from` changed since it was cut (or its base) is written into branch `key` as the
+ * person's own edit, and pushed now as one commit, "<agent>'s work from <from>, adopted by
+ * <person>" (an explicit publication boundary, addendum 16.7). Resolves the push's result.
+ */
+export async function adoptBranch (room, key, { who, from }) {
+  if (who.kind === 'agent') throw new Error('A person adopts an agent\'s work.')
+  const src = room.resolveKey ? room.resolveKey(from) : from
+  if (!room.meta.branches[src]) throw new Error(`${from} isn't in this session.`)
+  if (src === key) throw new Error('Adopt from another branch than the one you are on.')
+  const recs = upstreamsOf(room)
+  const srec = recs[src] || {}
+  const sstate = syncStateOf(room, src)
+  const base = srec.cutAt || sstate.base || srec.sha || (recs[key] && recs[key].sha) // everything since the branch started
+  if (!base) throw new Error(`Quilt doesn't know what ${from} started from.`)
+  const rec = recs[key]
+  if (!rec || !rec.repo) throw new Error('This branch doesn\'t follow a GitHub repository.')
+  const repo = parseRepo(`https://${rec.repo}`)
+  const dir = (await room.mirrors.ensure(repo, { url: room.gitRemoteUrl(repo) })).dir
+  const token = await room.gitToken(repo)
+  if (!(await haveCommit(room, dir, base, [rec.ref, srec.ref, srec.cutFrom && recs[srec.cutFrom] ? recs[srec.cutFrom].ref : null], token))) throw new Error(`${base.slice(0, 7)}, where ${from} started, isn't on GitHub.`)
+  const tree = await treeOf(dir, base)
+  const se = room.branchDoc(src)
+  const te = room.branchDoc(key)
+  const changes = new Map()
+  for (const rel of new Set([...se.files.keys(), ...se.blobs.keys()])) {
+    const b = sessionBytes(se, rel)
+    if (b === undefined) continue
+    const was = tree.get(rel)
+    if (!was || was.sha !== gitBlobSha(b)) changes.set(rel, b)
+  }
+  for (const rel of tree.keys()) if (!se.files.has(rel) && !se.blobs.has(rel)) changes.set(rel, null)
+  if (!changes.size) return { state: 'nothing', why: `${from} has no changes since it started` }
+  const { HistoryLog } = await import('./history.js')
+  const Y = await import('yjs')
+  const { applyTextDiff } = await import('./textdiff.js')
+  const history = te.historyLog || (te.historyLog = new HistoryLog(te.doc, te.doc.getArray('history'), { origin: 'relay-adopt' }))
+  te.doc.transact(() => {
+    for (const [rel, b] of changes) {
+      const before = te.files.get(rel)?.toString()
+      if (b === null) { te.files.delete(rel); te.blobs.delete(rel); history.record({ by: who.name, path: rel, kind: 'deleted', before, after: '' }); continue }
+      if (b.includes(0)) { te.files.delete(rel); te.blobs.set(rel, { hash: crypto.createHash('sha1').update(b).digest('hex'), data: b.toString('base64') }); history.record({ by: who.name, path: rel, kind: before === undefined ? 'created' : 'edited', detail: `${b.length} bytes` }); continue }
+      let y = te.files.get(rel)
+      if (!y) { y = new Y.Text(); te.files.set(rel, y) }
+      applyTextDiff(y, b.toString('utf8'))
+      history.record({ by: who.name, path: rel, kind: before === undefined ? 'created' : 'edited', before: before ?? '', after: b.toString('utf8') })
+    }
+  }, 'relay-adopt')
+  for (const rel of changes.keys()) room.outbound.note(key, rel)
+  const owner = agentOwnerOf(room, src)
+  return room.outbound.flush(key, { message: `${owner ? `${owner}'s work` : 'The work'} from ${src}, adopted by ${who.name}`, by: who.name, only: [...changes.keys()] })
+}