heyquilt 0.0.1 → 0.3.90

package/src/relay-commit.js

@@ -0,0 +1,887 @@
+// quilt_commit, on the relay: a member's finished work committed to GitHub from the session's
+// copy of the files (github-commit.js), for an agent on any tool or a person, from a folder
+// (through its connection) or over HTTP (hosted agents). The relay is always there, so an
+// agent's work is never held up waiting for a person to be online.
+import { parseRepo, upstreamsOf, validToken } from './relay-upstream.js'
+import { RELAY_BY, isRelay } from './branches.js'
+import { DEFAULT_KEY } from './branchdocs.js'
+import { appCredentials, noCredentialsText } from './relay-github.js'
+import crypto from 'node:crypto'
+import { notePublished, notePublishedIds, publishedOf } from './upstream.js'
+import { mayChange } from './session-access.js'
+import { isSafeRelPath, makeIgnore, scopeIgnore, isIgnored } from './pathrules.js'
+import {
+  CommitRefused, commitTarget, commitOnGitHub, githubWriter, gitBlobSha, messageFor, noreply, othersEditing, othersInChange, writeProblem,
+  AGENT_COMMITS, DEFAULT_AGENT_COMMITS, MAX_COMMIT_FILES, MAX_COMMIT_BYTES, agentPrefix, slug, ruleSetter, gitForEveryoneWords
+} from './github-commit.js'
+import { readTasks, addTask, updateTask } from './tasks.js'
+import { addComment } from './task-comments.js'
+
+export { CommitRefused }
+
+// The origin of the relay's own writes to the room's record of what was published.
+const RELAY_PUBLISH = 'relay-publish'
+
+/** How strict each mode is: a rule over a session is a ceiling, and the strictest holds. */
+export const POLICY_RANK = { off: 0, branches: 1, any: 2 }
+
+/**
+ * Git for this session (docs/superpowers/specs/2026-10-17-git-for-everyone.md): 'off' (for everyone, people
+ * included), or on with what agents may push: 'branches' (their own) or 'any'. A rule over the session (its
+ * org's, a team's, its workspace's: server.js refreshPolicy) is a ceiling: the owner's own choice holds only
+ * when it is stricter. Neither set: the default (branches).
+ */
+export const agentCommitsOf = (room) => {
+  const set = room.meta.agentCommitsSet
+  const rule = set && AGENT_COMMITS.includes(set.mode) ? set.mode : null
+  const own = AGENT_COMMITS.includes(room.meta.agentCommits) ? room.meta.agentCommits : null
+  if (rule && own) return POLICY_RANK[own] < POLICY_RANK[rule] ? own : rule
+  return rule || own || DEFAULT_AGENT_COMMITS
+}
+
+export { ruleSetter }
+
+export const POLICY_WORDS = {
+  off: 'git is off for everyone here: nobody pushes through Quilt, and agents ask a person to commit (quilt_request_commit)',
+  branches: 'git is on for everyone here: people push any branch, agents push to branches of their own (quilt/<agent>/…) and open pull requests; people merge them',
+  any: 'git is on for everyone here: people and agents push to any branch, the session\'s own included'
+}
+
+const cleanList = (files) => {
+  const out = []
+  for (const f of Array.isArray(files) ? files : []) {
+    const p = String(f || '').trim().replace(/\\/g, '/').replace(/^\.\//, '')
+    if (isSafeRelPath(p) && !out.includes(p)) out.push(p)
+  }
+  return out
+}
+
+/**
+ * What the relay commits to owner/name with: the session owner's GitHub connection (relay-github.js),
+ * or a token the owner set by hand (quilt_github_token). Throws CommitRefused saying what the owner
+ * can do when there is neither.
+ */
+export async function credentialsFor (room, repo, { actingFor = '' } = {}) {
+  const full = `${repo.owner}/${repo.name}`
+  const r = await appCredentials(room, full, { access: 'write', actingFor })
+  if (r.token) return r.token
+  if (validToken(room.meta.githubToken)) return room.meta.githubToken
+  tellOwner(room, full, r)
+  throw new CommitRefused(noCredentialsText(r, full))
+}
+
+// An agent was held up for want of a GitHub connection: the session owner hears it once (a direct
+// message in chat that needs no reply), at most every six hours per repository, with the one click that fixes it.
+const TOLD_MS = 6 * 60 * 60 * 1000
+function tellOwner (room, full, r) {
+  const owner = room.meta && room.meta.ownerName
+  if (!owner || !room.postChat || !['not-connected', 'not-installed', 'no-access'].includes(r.state)) return
+  if (!room.toldConnect) room.toldConnect = new Map()
+  const at = room.toldConnect.get(full) || 0
+  if (Date.now() - at < TOLD_MS) return
+  room.toldConnect.set(full, Date.now())
+  const what = r.state === 'not-installed' ? `Quilt isn't installed on ${full} on GitHub` : r.state === 'no-access' ? `no connected GitHub account (@${r.login}) may write to ${full}` : `nobody here has connected GitHub for ${full}`
+  room.postChat({ by: RELAY_BY, to: owner, text: `An agent tried to commit, but ${what}. Click Connect GitHub in the commit panel (one click, once): agents then commit and merge on their own, and pushes come in within seconds.`, kind: 'commit' })
+}
+
+/** The session branch's repository on GitHub, or throws CommitRefused saying why the relay can't act on it. */
+/**
+ * The branch record that says where work on `key` lands on GitHub: the branch's own when the relay
+ * follows it there (a member's folder has it as its upstream), otherwise the room's default
+ * branch's (a branch an agent made in its folder for a feature has no upstream yet; its work is
+ * measured against, and merges into, the default branch). Null when neither is known.
+ */
+export function repoRecordFor (room, key) {
+  const recs = upstreamsOf(room)
+  const k = room.resolveKey ? room.resolveKey(key) : key
+  const own = recs[k]
+  // An agent's branch (quilt/<agent>/…) always measures against, and merges into, the default
+  // branch, even once the relay has a record of the branch itself (its folder pushed it).
+  const agents = /^quilt\//.test(k)
+  if (own && own.repo && own.ref && !agents) return { key: k, rec: own }
+  const d = room.resolveKey ? room.resolveKey(DEFAULT_KEY) : DEFAULT_KEY
+  const main = recs[d]
+  if (main && main.repo && main.ref) return { key: d, rec: main }
+  // No default named yet: main or master, else the room's one followed branch that isn't an agent's.
+  for (const name of ['main', 'master']) if (recs[name] && recs[name].repo && recs[name].ref) return { key: name, rec: recs[name] }
+  const followed = Object.entries(recs).filter(([n, r]) => r && r.repo && r.ref && !/^quilt\//.test(n))
+  if (followed.length === 1) return { key: followed[0][0], rec: followed[0][1] }
+  if (own && own.repo && own.ref) return { key: k, rec: own }
+  return null
+}
+
+export function githubRepoOf (room, key) {
+  const found = repoRecordFor(room, key)
+  if (!found) throw new CommitRefused(`Quilt doesn't know which GitHub repository \`${room.resolveKey ? room.resolveKey(key) : key}\` follows yet: a member's folder on it that is a git clone tells it once it is online.`)
+  const { rec } = found
+  const repo = parseRepo(`https://${rec.repo}`)
+  if (!repo || !repo.github) throw new CommitRefused(`\`${found.key}\` follows ${rec.repo}, which isn't on GitHub: commit from a folder with git, or ask a person (quilt_request_commit).`)
+  return { key: found.key, rec, repo, full: `${repo.owner}/${repo.name}` }
+}
+
+/** git's ignore rules for a branch: every .gitignore in the session's copy, scoped to its folder, plus Quilt's own. */
+function gitIgnoreOf (e) {
+  const texts = []
+  e.files.forEach((t, rel) => {
+    if (rel !== '.gitignore' && !rel.endsWith('/.gitignore')) return
+    const dir = rel.includes('/') ? rel.slice(0, rel.lastIndexOf('/')) : ''
+    texts.push(scopeIgnore(t.toString(), dir))
+  })
+  return makeIgnore(texts)
+}
+
+/** The session's copy of a file on a branch: its bytes, null when it isn't there, or throws for one 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) throw new CommitRefused(`${rel} is a large file kept encrypted in storage, which the relay can't read: commit it from a folder with git.`)
+  if (b) return Buffer.from(b.data || '', 'base64')
+  return null
+}
+
+/**
+ * The committer's boxes on files now in git open (docs/superpowers/specs/2026-10-16-git-boxes-design.md):
+ * committed, they're no longer unfinished work, so they reach everyone's folder. Returns how many opened.
+ */
+export function openBoxesCommitted (room, who, key, rels) {
+  if (!room.claimFor || !room.dropClaims) return 0
+  const boxes = [...new Set(rels || [])].map((rel) => room.claimFor(rel, key)).filter((c) => c && c.box && c.pattern && c.by === who.name && !/[*?[]/.test(c.pattern))
+  if (!boxes.length) return 0
+  const n = room.dropClaims((c) => boxes.includes(c), (c) => `${c.by} committed it.`)
+  if (room.saveMeta) room.saveMeta()
+  if (room.broadcastClaims) room.broadcastClaims()
+  return n
+}
+
+/**
+ * Commits `files` (or, without them, the files `who` changed on record, or a task's) from
+ * branch `key` of the session to GitHub. `who`: { name, kind ('agent' | 'human'), access }.
+ * Resolves { sha, branch, created, changed, same, url, pr, nothing } or throws (CommitRefused, or
+ * an Error saying what GitHub refused).
+ */
+export async function commitForMember (room, { who, key, files = null, message = '', branch: target = '', pullRequest = false, withOthers = false, task = null }, { fetch = globalThis.fetch, log = () => {} } = {}) {
+  const a = who.access || {}
+  if (a.state && a.state !== 'approved') throw new CommitRefused('You are not let into this session yet.')
+  if (a.role === 'viewer') throw new CommitRefused('You can only view this session, so you can\'t commit.')
+  key = room.resolveKey ? room.resolveKey(key) : key
+  // The files come from `key` (the member's branch document); where they land on GitHub is that
+  // branch's record, or the default branch's for a branch the relay has no record of yet (an agent's own).
+  const found = repoRecordFor(room, key)
+  const rec = found ? found.rec : null
+  if (!rec) throw new CommitRefused(`Quilt doesn't know which GitHub repository \`${key}\` follows yet: a member's folder on it that is a git clone tells it once it is online.`)
+  if (!rec.sha) throw new CommitRefused(`Quilt doesn't know which commit the session's files on \`${key}\` are at yet: a member's folder on it, in step with the session, tells it.`)
+  const repo = parseRepo(`https://${rec.repo}`)
+  if (!repo || !repo.github) throw new CommitRefused(`\`${key}\` follows ${rec.repo}, which isn't on GitHub: commit from a folder with git, or ask a person (quilt_request_commit).`)
+  // The commit is for `who`: when the org requires GitHub, their (or their agent's person's) GitHub permissions count (plan §2).
+  const actor = Object.entries((room.meta && room.meta.members) || {}).find(([k, m]) => m && m.name === who.name && /^(person|agent):/.test(k))
+  const token = await credentialsFor(room, repo, { actingFor: actor ? actor[0] : '' })
+  const t = task ? room.doc.getMap('tasks').get(String(task)) : null
+  if (task && !t) throw new CommitRefused(`No task ${task} on the board.`)
+  message = String(message || (t && t.title) || '').trim().slice(0, 2000)
+  if (!message) throw new CommitRefused('Say what the commit does (message).')
+  const where = commitTarget({ policy: agentCommitsOf(room), kind: who.kind, name: who.name, sessionBranch: rec.ref, target, message })
+
+  const e = room.branchDoc(key)
+  const history = e.doc.getArray('history').toArray()
+  let list = cleanList(files)
+  if (Array.isArray(files) && files.length && !list.length) throw new CommitRefused('None of those are files in the project (give paths relative to its top folder).')
+  if (!list.length) {
+    // What was changed for the task, or by this member, on record (pulls from git are nobody's).
+    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.name) { if (!list.includes(h.path)) list.push(h.path) }
+    }
+    if (t) for (const f of Array.isArray(t.files) ? t.files : []) if (!list.includes(f)) list.push(f)
+    list = cleanList(list)
+  }
+  if (!list.length) throw new CommitRefused(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.')
+  if (list.length > MAX_COMMIT_FILES) throw new CommitRefused(`That is ${list.length} files; commit at most ${MAX_COMMIT_FILES} at a time.`)
+  // What git ignores never goes in: the repository's .gitignore files (as the session has them, each
+  // scoped to its folder) and Quilt's own list (.env and the like), whatever a member wrote.
+  const ig = gitIgnoreOf(e)
+  const ignored = list.filter((rel) => isIgnored(ig, rel))
+  if (ignored.length && ignored.length === list.length) throw new CommitRefused(`${ignored.slice(0, 5).join(', ')}${ignored.length > 5 ? ', …' : ''} ${ignored.length === 1 ? 'is' : 'are'} ignored by the repository's .gitignore (or is a secrets file such as .env), so ${ignored.length === 1 ? 'it isn\'t' : 'they aren\'t'} committed.`)
+  list = list.filter((rel) => !ignored.includes(rel))
+  const outside = list.filter((rel) => !mayChange(a, rel))
+  if (outside.length) throw new CommitRefused(`You may not change ${outside.slice(0, 5).join(', ')}${outside.length > 5 ? ', …' : ''} in this session, so you can't commit ${outside.length === 1 ? 'it' : 'them'}.`)
+  const content = new Map()
+  let bytes = 0
+  for (const rel of list) {
+    const b = sessionBytes(e, rel)
+    bytes += b ? b.length : 0
+    content.set(rel, b)
+  }
+  if (bytes > MAX_COMMIT_BYTES) throw new CommitRefused(`Those files come to ${Math.round(bytes / 1048576)} MB; commit at most ${MAX_COMMIT_BYTES / 1048576} MB at a time.`)
+
+  const gh = githubWriter({ fetch, token, owner: repo.owner, name: repo.name })
+  const full = `${repo.owner}/${repo.name}`
+  try {
+    // Other people's unfinished work in these files would go in with them: said, not swept in.
+    const base = await gh.commit(rec.sha)
+    const baseBlobs = await gh.blobs(base.tree)
+    const differ = baseBlobs ? list.filter((rel) => (content.get(rel) ? gitBlobSha(content.get(rel)) : null) !== (baseBlobs.get(rel) || null)) : list
+    // Each changed line is put down to whoever added or removed it last (the session's history);
+    // a file the relay can't read as text falls back to who edited it since the session's commit.
+    const others = new Map()
+    for (const rel of differ) {
+      const now = content.get(rel)
+      const text = !e.blobs.get(rel) && (now === null || e.files.get(rel))
+      let names
+      if (text) {
+        const was = baseBlobs && baseBlobs.get(rel) ? await gh.content(rec.sha, rel) : null
+        names = othersInChange({ before: was ? was.toString('utf8') : '', after: now ? now.toString('utf8') : '', entries: history.filter((h) => h && h.path === rel), me: who.name })
+      } else names = othersEditing([rel], history, { me: who.name, since: base.ts }).get(rel) || []
+      names = names.filter((n) => !isRelay(n))
+      if (names.length) others.set(rel, names)
+    }
+    if (others.size && !withOthers) {
+      const lines = [...others].map(([rel, names]) => `${rel} (${names.join(', ')})`)
+      throw new CommitRefused(`These files also hold changes by others that are not in git yet: ${lines.join('; ')}. ` +
+        'Leave them out (files), ask those people to commit first, or commit them together with with_others: true (they are named as co-authors).')
+    }
+    const coAuthors = [...new Set([...others.values()].flat())]
+    const r = await commitOnGitHub(gh, {
+      files: content,
+      branch: where.branch,
+      from: rec.sha,
+      base: where.own ? null : rec.sha,
+      message: messageFor({ message, by: who.name, task: t ? { id: t.id, title: t.title } : null, coAuthors: withOthers ? coAuthors : [] }),
+      author: who.kind === 'agent' ? { name: who.name, email: noreply(who.name) } : null
+    })
+    const out = { ...r, repo: full, url: `https://github.com/${full}/commit/${r.sha}`, ...(ignored.length ? { ignored } : {}) }
+    const pr = () => gh.pull({ title: message.split('\n')[0].slice(0, 200), head: where.branch, base: rec.ref, body: `Made in Quilt by ${who.name}${t ? ` for task ${t.id}: ${t.title}` : ''}.\n\n${message}` })
+    // Already committed: a pull request can still be asked for, for a branch that is there.
+    // What git has now as the session does (committed, or already so) is no longer the committer's unfinished work.
+    openBoxesCommitted(room, who, key, [...(r.changed || []), ...(r.same || [])])
+    if (r.nothing) {
+      if (pullRequest && where.own && r.exists) { out.pr = await pr(); if (t) linkTaskPull(room, t.id, { number: out.pr.number, url: out.pr.url, branch: where.branch, base: rec.ref }, { log }) }
+      return out
+    }
+    if (pullRequest && where.own) {
+      out.pr = await pr()
+      if (t) linkTaskPull(room, t.id, { number: out.pr.number, url: out.pr.url, branch: where.branch, base: rec.ref }, { log })
+    }
+    if (where.own && r.sha) for (const x of readTasks(room.doc.getMap('tasks'))) if (x.pr && x.pr.branch === where.branch) noteTaskRevision(room, x.pr.number, r.sha)
+    // What went to GitHub, by content: when that branch is merged (or squashed, or rebased) into the
+    // session's branch, pulling it down keeps the session's copy, which is that or newer (upstream.js).
+    notePublished(room.doc, new Map(r.changed.map((rel) => [rel, content.get(rel)])), RELAY_PUBLISH)
+    log(`[${room.name}] ${key}: ${who.name} committed ${r.sha.slice(0, 7)} to ${full} ${where.branch} (${r.changed.length} files)`)
+    // Everyone sees what went into git, and by whom; it wakes nobody.
+    if (room.postChat) {
+      room.postChat({ by: RELAY_BY, text: `${who.name} committed ${r.sha.slice(0, 7)} to ${where.branch}${r.created ? ' (a new branch)' : ''}: "${message.split('\n')[0].slice(0, 200)}" (${r.changed.length} file${r.changed.length === 1 ? '' : 's'})${out.pr ? `, pull request ${out.pr.url}` : ''}.`, kind: 'commit' })
+    }
+    // The session's own branch moved. Made on the session's commit, the new one is where the session
+    // now stands (its files are the session's own): measured from it, so the next commit isn't taken
+    // for a change on GitHub. On a later commit, folders and the relay bring the rest in as usual.
+    if (!where.own) {
+      if (r.parent === rec.sha) { rec.sha = r.sha; rec.head = r.sha; room.saveMeta(); if (room.broadcastBranches) room.broadcastBranches() }
+      if (room.upstreamSoon) room.upstreamSoon(key)
+    }
+    closeRequests(room, who.name, new Set([...r.changed, ...r.same]), r.sha)
+    return out
+  } catch (err) {
+    if (err instanceof CommitRefused) throw err
+    throw new Error(writeProblem(err, full))
+  }
+}
+
+/** Open commit requests by `name` whose files are all in this commit: done, with its hash. */
+function closeRequests (room, name, files, sha) {
+  const map = room.doc.getMap('commitRequests')
+  room.doc.transact(() => {
+    for (const r of map.values()) {
+      if (!r || r.state !== 'open' || r.by !== name || !Array.isArray(r.files) || !r.files.length) continue
+      if (r.files.every((f) => files.has(f))) map.set(r.id, { ...r, state: 'done', doneBy: name, hash: sha, doneAt: Date.now(), pushed: true })
+    }
+  })
+}
+
+/** quilt_commit's answer. */
+export function describeCommit (r, { policy } = {}) {
+  if (r.nothing) return `Nothing to commit: ${r.same.length ? r.same.join(', ') : 'those files'} ${r.same.length === 1 ? 'is' : 'are'} already on ${r.branch} as they are in the session.${r.pr ? ` Pull request${r.pr.existed ? ' (already open)' : ''}: ${r.pr.url}` : ''}`
+  const lines = [`Committed ${r.sha.slice(0, 7)} to ${r.repo} ${r.branch}${r.created ? ' (new branch)' : ''}: ${r.changed.length} file${r.changed.length === 1 ? '' : 's'} (${r.changed.slice(0, 10).join(', ')}${r.changed.length > 10 ? ', …' : ''}). ${r.url}`]
+  if (r.same.length) lines.push(`Already as in the session, so not in the commit: ${r.same.slice(0, 10).join(', ')}${r.same.length > 10 ? ', …' : ''}.`)
+  if (r.ignored && r.ignored.length) lines.push(`Left out, as git ignores ${r.ignored.length === 1 ? 'it' : 'them'}: ${r.ignored.slice(0, 10).join(', ')}.`)
+  if (r.pr) lines.push(`Pull request${r.pr.existed ? ' (already open)' : ''}: ${r.pr.url}`)
+  else if (r.created && policy === 'branches') lines.push('Open a pull request for it with quilt_commit again and pull_request: true, or ask a person to merge the branch.')
+  return lines.join('\n')
+}
+
+/**
+ * The open pull requests of the session branch's repository, with how each one's checks stand:
+ * [{ number, title, head, base, url, by, draft, checks }]. Throws CommitRefused when the relay can't read it.
+ */
+export async function pullRequestsFor (room, { key }, { fetch = globalThis.fetch } = {}) {
+  const { repo, full } = githubRepoOf(room, key)
+  const token = await credentialsFor(room, repo)
+  const gh = githubWriter({ fetch, token, owner: repo.owner, name: repo.name })
+  try {
+    const list = await gh.pulls()
+    const out = []
+    for (const p of list.slice(0, 20)) out.push({ ...p, checks: p.sha ? await gh.checks(p.sha).catch(() => ({ state: 'none', failing: [] })) : { state: 'none', failing: [] } })
+    return { repo: full, pulls: out }
+  } catch (err) { throw new Error(writeProblem(err, full)) }
+}
+
+/**
+ * Merges a pull request (by number, or the branch it comes from) into its base, for a member:
+ * people always (as far as GitHub lets the session's connection), agents only when the owner lets
+ * them commit to any branch. Refused while checks fail or are still running, unless `force`
+ * (people only). The head branch is deleted afterwards when it is a Quilt agent's (quilt/…) or
+ * `deleteBranch`. Resolves { sha, number, title, head, base, deleted }.
+ */
+export async function mergeForMember (room, { who, key, number = null, branch = '', method = 'squash', deleteBranch = null, force = false }, { fetch = globalThis.fetch, log = () => {} } = {}) {
+  const a = who.access || {}
+  if (a.state && a.state !== 'approved') throw new CommitRefused('You are not let into this session yet.')
+  if (a.role === 'viewer') throw new CommitRefused('You can only view this session, so you can\'t merge.')
+  if (who.kind === 'agent' && agentCommitsOf(room) !== 'any') throw new CommitRefused('The session owner lets agents commit only to branches of their own (or not at all), so merging is for people: ask one in chat, with the pull request\'s link.')
+  if (!['merge', 'squash', 'rebase'].includes(method)) throw new CommitRefused('method is merge, squash or rebase.')
+  const { repo, full, rec } = githubRepoOf(room, key)
+  const token = await credentialsFor(room, repo)
+  const gh = githubWriter({ fetch, token, owner: repo.owner, name: repo.name })
+  try {
+    let n = Number(number) || 0
+    if (!n) {
+      const head = String(branch || '').trim().replace(/^refs\/heads\//, '')
+      if (!head) throw new CommitRefused('Say which pull request (number) or branch to merge.')
+      const open = (await gh.pulls()).find((p) => p.head === head)
+      if (!open) throw new CommitRefused(`No open pull request from ${head}. Open one first (push the branch from a folder, or quilt_git_commit on it without one: Quilt opens it).`)
+      n = open.number
+    }
+    const pr = await gh.pullRequest(n)
+    if (pr.merged) return { sha: '', number: n, title: pr.title, head: pr.head, base: pr.base, deleted: false, already: true }
+    if (pr.state !== 'open') throw new CommitRefused(`Pull request #${n} is closed.`)
+    const checks = await gh.checks(pr.sha)
+    if (checks.state === 'failing' && !(force && who.kind !== 'agent')) throw new CommitRefused(`Pull request #${n} has failing checks (${checks.failing.join(', ')}): fix them first${who.kind !== 'agent' ? ', or merge with force: true' : ''}.`)
+    if (checks.state === 'pending' && !(force && who.kind !== 'agent')) throw new CommitRefused(`Pull request #${n}'s checks are still running: try again when they have finished${who.kind !== 'agent' ? ', or merge with force: true' : ''}.`)
+    if (pr.mergeable === false) throw new CommitRefused(`Pull request #${n} can't be merged as it is (${pr.mergeableState || 'conflicts'}): bring ${pr.base} into ${pr.head} and resolve, then try again.`)
+    const r = await gh.merge(n, { method })
+    const del = deleteBranch === null ? /^quilt\//.test(pr.head) : !!deleteBranch
+    if (del && pr.head !== rec.ref) {
+      await gh.deleteBranch(pr.head)
+      const was = upstreamsOf(room)[room.resolveKey ? room.resolveKey(pr.head) : pr.head]
+      if (was) { was.gone = Date.now(); delete was.problem } // nothing more to bring into that branch; it stays in the session as it is
+    }
+    log(`[${room.name}] ${key}: ${who.name} merged #${n} (${pr.head} → ${pr.base}) as ${String(r.sha).slice(0, 7)}`)
+    if (room.postChat) room.postChat({ by: RELAY_BY, text: `${who.name} merged pull request #${n} (${pr.head} → ${pr.base}) as ${String(r.sha).slice(0, 7)}: "${pr.title}"${del ? `, and deleted ${pr.head}` : ''}.`, kind: 'commit' })
+    // The base moved: look now (GitHub's webhook says so too, when the app is on the repository).
+    if (pr.base === rec.ref && room.upstreamSoon) room.upstreamSoon(key)
+    return { sha: r.sha, number: n, title: pr.title, head: pr.head, base: pr.base, deleted: del }
+  } catch (err) {
+    if (err instanceof CommitRefused) throw err
+    throw new Error(writeProblem(err, full))
+  }
+}
+
+/**
+ * quilt_git_commit, for an agent without a folder: commits to the branch the agent is on (`key`,
+ * its branch document). A branch of its own gets its pull request opened and tied to its task; the
+ * session's branch itself is open to agents only under policy "any". Resolves commitForMember's
+ * result plus { pr } when one was opened or found.
+ */
+export async function gitCommitFor (room, { who, key, message, files = null, task = null, withOthers = false }, { fetch = globalThis.fetch, log = () => {} } = {}) {
+  const { rec } = githubRepoOf(room, key)
+  const here = room.resolveKey ? room.resolveKey(key) : key
+  const own = who.kind === 'agent' && here.startsWith(agentPrefix(who.name))
+  const policy = agentCommitsOf(room)
+  if (who.kind === 'agent' && policy === 'off') throw new CommitRefused(`${gitForEveryoneWords({ policy: 'off', by: room.meta.agentCommitsSet && room.meta.agentCommitsSet.mode === 'off' ? room.meta.agentCommitsSet : null })} Ask a person for the commit with quilt_request_commit.`)
+  if (who.kind === 'agent' && !own && policy !== 'any') {
+    throw new CommitRefused(`You are on ${here}, and the owner lets agents commit only to branches of their own (${agentPrefix(who.name)}<topic>). Take the task (quilt_move_task to doing puts you on a branch for it) or quilt_git_branch with create: true, then commit there; the pull request opens by itself.`)
+  }
+  const target = here === rec.ref ? '' : here
+  const r = await commitForMember(room, { who, key: here, message, files, branch: target, pullRequest: false, withOthers, task }, { fetch, log })
+  if (own && (r.changed.length || r.exists)) {
+    try {
+      const pr = await openPullOnPush(room, { who, key: here, branch: here, files: r.changed, subject: String(message || '').split('\n')[0], taskId: task || null }, { fetch, log })
+      if (pr) r.pr = { number: pr.number, url: pr.url, existed: !r.changed.length || undefined }
+    } catch (err) { log(`[${room.name}] ${here}: committed, but could not open the pull request: ${err.message}`) }
+  }
+  return r
+}
+
+/** quilt_git_commit's answer. */
+export function describeGitCommit (r, { policy } = {}) {
+  if (r.nothing) return `Nothing to commit: ${r.same.length ? r.same.join(', ') : 'those files'} ${r.same.length === 1 ? 'is' : 'are'} already on ${r.branch} as they are in the session.${r.pr ? ` Pull request #${r.pr.number}: ${r.pr.url}` : ''}`
+  const lines = [`Committed ${r.sha.slice(0, 7)} to ${r.repo} ${r.branch}${r.created ? ' (new branch)' : ''}: ${r.changed.length} file${r.changed.length === 1 ? '' : 's'} (${r.changed.slice(0, 10).join(', ')}${r.changed.length > 10 ? ', …' : ''}). ${r.url}`]
+  if (r.same.length) lines.push(`Already as in the session, so not in the commit: ${r.same.slice(0, 10).join(', ')}${r.same.length > 10 ? ', …' : ''}.`)
+  if (r.ignored && r.ignored.length) lines.push(`Left out, as git ignores ${r.ignored.length === 1 ? 'it' : 'them'}: ${r.ignored.slice(0, 10).join(', ')}.`)
+  if (r.pr) lines.push(`Pull request #${r.pr.number} (${r.pr.existed ? 'already open' : 'opened'}, tied to your task): ${r.pr.url}. Move the task to QA when the work is done and tested; Done merges it${policy === 'any' ? '' : ' (a person moves it)'}.`)
+  return lines.join('\n')
+}
+
+/** quilt_git_status: where an agent without a folder stands in git. */
+export async function gitStatusFor (room, { who, key }, { fetch = globalThis.fetch } = {}) {
+  const here = room.resolveKey ? room.resolveKey(key) : key
+  const policy = agentCommitsOf(room)
+  const able = agentsCanCommit(room, here)
+  let repo = null; let base = null
+  try { const g = githubRepoOf(room, here); repo = g.full; base = g.rec.ref } catch {}
+  const own = who.kind === 'agent' && here.startsWith(agentPrefix(who.name))
+  const u = able ? await unpublishedFor(room, { key: here, who: who.name }, { fetch }) : { unpublished: [], awaitingMerge: [] }
+  const tasks = readTasks(room.doc.getMap('tasks')).filter((t) => !t.archived && t.assignee === who.name && t.column !== 'done')
+  const task = tasks.find((t) => t.pr && t.pr.branch === here) || tasks.find((t) => t.column === 'doing') || null
+  let onGitHub = null
+  if (repo && able) {
+    try {
+      const { repo: r } = githubRepoOf(room, here)
+      const gh = githubWriter({ fetch, token: await credentialsFor(room, r), owner: r.owner, name: r.name })
+      onGitHub = await gh.ref(here)
+    } catch {}
+  }
+  return { branch: here, base, repo, policy, able, own, onGitHub, unpublished: u.unpublished || [], awaitingMerge: u.awaitingMerge || [], task: task ? { id: task.id, title: task.title, column: task.column, pr: task.pr || null } : null }
+}
+
+export function describeGitStatus (s) {
+  const lines = [`On ${s.branch}${s.repo ? ` of ${s.repo}` : ''}${s.base && s.base !== s.branch ? ` (merges into ${s.base})` : ''}${s.onGitHub ? `, on GitHub at ${s.onGitHub.slice(0, 7)}` : s.onGitHub === null && s.repo && s.able ? ', not on GitHub yet' : ''}.`]
+  if (!s.repo) lines.push('The session doesn\'t follow a GitHub repository yet (a member\'s folder that is a clone tells it).')
+  else if (!s.able) lines.push(s.policy === 'off' ? 'Agents may not commit here (the owner\'s setting): ask a person with quilt_request_commit.' : 'Nobody has connected GitHub for this session yet, so the relay can\'t commit for you; ask the owner to connect it.')
+  else lines.push(`Agents may push ${s.policy === 'any' ? 'to any branch' : 'to branches of their own only'}${s.own ? '; this one is yours' : s.policy === 'any' ? '' : '; this one is not (take a task, or quilt_git_branch with create: true)'}.`)
+  if (s.unpublished.length) lines.push(`Your changes not in git yet: ${s.unpublished.slice(0, 15).join(', ')}${s.unpublished.length > 15 ? `, and ${s.unpublished.length - 15} more` : ''}. quilt_git_commit puts them on this branch.`)
+  else if (s.able) lines.push('Nothing of yours is uncommitted on this branch.')
+  if (s.awaitingMerge.length) lines.push(`On this branch but not merged into ${s.base} yet: ${s.awaitingMerge.slice(0, 15).join(', ')}.`)
+  if (s.task) lines.push(`Your task: "${s.task.title}" [${s.task.id}] in ${s.task.column}${s.task.pr ? `, pull request #${s.task.pr.number} ${s.task.pr.url}` : ', no pull request yet'}.`)
+  return lines.join('\n')
+}
+
+/** quilt_git_log: the branch's newest commits on GitHub (the branch it merges into when the branch itself isn't there yet). */
+export async function gitLogFor (room, { key, n = 10 }, { fetch = globalThis.fetch } = {}) {
+  const here = room.resolveKey ? room.resolveKey(key) : key
+  const { repo, full, rec } = githubRepoOf(room, here)
+  const gh = githubWriter({ fetch, token: await credentialsFor(room, repo), owner: repo.owner, name: repo.name })
+  try {
+    const exists = here === rec.ref || !!(await gh.ref(here))
+    const branch = exists ? here : rec.ref
+    return { repo: full, branch, asked: here, commits: await gh.log(branch, n) }
+  } catch (err) { throw new Error(writeProblem(err, full)) }
+}
+
+export function describeGitLog (r) {
+  const head = r.branch === r.asked ? `Newest commits on ${r.repo} ${r.branch}:` : `${r.asked} isn't on GitHub yet; newest commits on ${r.branch}, which it starts from:`
+  if (!r.commits.length) return `${head} none.`
+  return `${head}\n${r.commits.map((c) => `- ${c.sha.slice(0, 7)} ${c.message.split('\n')[0].slice(0, 100)} (${c.author}${c.date ? `, ${c.date.slice(0, 10)}` : ''})`).join('\n')}`
+}
+
+/**
+ * quilt_git_diff: how the session's copy of files differs from GitHub (the branch's head, or the
+ * branch it merges into when it isn't on GitHub yet). `files`: those, or the agent's own changes.
+ */
+export async function gitDiffFor (room, { who, key, files = null }, { fetch = globalThis.fetch, lineDiff } = {}) {
+  const here = room.resolveKey ? room.resolveKey(key) : key
+  const { repo, full, rec } = githubRepoOf(room, here)
+  const e = room.branchDoc(here)
+  let list = cleanList(files)
+  if (!list.length) list = (await unpublishedFor(room, { key: here, who: who.name }, { fetch })).unpublished
+  if (!list.length) return { repo: full, branch: here, against: null, files: [] }
+  const gh = githubWriter({ fetch, token: await credentialsFor(room, repo), owner: repo.owner, name: repo.name })
+  try {
+    const head = (here === rec.ref ? null : await gh.ref(here)) || await gh.ref(rec.ref)
+    const against = head === (await gh.ref(rec.ref)) && here !== rec.ref ? rec.ref : here
+    const out = []
+    for (const rel of list.slice(0, 20)) {
+      let now = null
+      try { now = sessionBytes(e, rel) } catch { out.push({ path: rel, note: 'a large stored file: not compared' }); continue }
+      const was = head ? await gh.content(head, rel) : null
+      const text = (b) => b === null || b === undefined ? '' : b.toString('utf8')
+      const binary = (b) => !!b && b.includes(0)
+      if (binary(now) || binary(was)) { out.push({ path: rel, note: now && was && Buffer.compare(now, was) === 0 ? 'same' : 'binary, differs' }); continue }
+      if (!now && !was) { out.push({ path: rel, note: 'not in the session, not on GitHub' }); continue }
+      if (now && was && Buffer.compare(now, was) === 0) { out.push({ path: rel, note: 'same' }); continue }
+      out.push({ path: rel, diff: lineDiff ? lineDiff(text(was), text(now)) : `${was ? '-' : ''}${now ? '+' : ''}`, created: !was, deleted: !now })
+    }
+    return { repo: full, branch: here, against, head, files: out }
+  } catch (err) { throw new Error(writeProblem(err, full)) }
+}
+
+export function describeGitDiff (r) {
+  if (!r.files.length) return `Nothing of yours differs from GitHub on ${r.branch}.`
+  const head = `The session's copy on ${r.branch} against GitHub's ${r.against}${r.head ? ` (${r.head.slice(0, 7)})` : ''}:`
+  return `${head}\n${r.files.map((f) => f.note ? `--- ${f.path}: ${f.note}` : `--- ${f.path}${f.created ? ' (new)' : f.deleted ? ' (deleted)' : ''}\n${f.diff}`).join('\n')}`
+}
+
+export const GIT_STATUS_DESCRIPTION = 'Where you stand in git: the branch you are on and what it merges into, the repository, what agents may push here, your changes not in git yet, what is on your branch but not merged, and your task\'s pull request. Read it before committing or when unsure what shipped.'
+export const GIT_LOG_DESCRIPTION = 'The newest commits on GitHub for the branch you are on (or the branch it starts from while yours isn\'t pushed yet): who committed what, when.'
+export const GIT_DIFF_DESCRIPTION = 'How the session\'s copy of files differs from GitHub: your uncommitted changes by default, or the files you name (unified diff per text file). Read it before committing, or to review what someone changed.'
+export const GIT_REVERT_DESCRIPTION = 'Put GitHub\'s version of files back into the session (the branch\'s head, or the branch it starts from): undoes uncommitted changes to those files in the session, for everyone. Say which files; nothing else is touched.'
+
+/** quilt_pull_requests' answer. */
+export function describePulls ({ repo, pulls }) {
+  if (!pulls.length) return `No open pull requests in ${repo}.`
+  const checks = (c) => c.state === 'passing' ? 'checks passing' : c.state === 'failing' ? `checks failing: ${c.failing.join(', ')}` : c.state === 'pending' ? 'checks running' : 'no checks'
+  return `Open pull requests in ${repo}:\n${pulls.map((p) => `- #${p.number} ${p.title} (${p.head} → ${p.base}, by ${p.by || '?'}${p.draft ? ', draft' : ''}; ${checks(p.checks)}) ${p.url}`).join('\n')}`
+}
+
+/** quilt_merge's answer. */
+export function describeMerge (r) {
+  if (r.already) return `Pull request #${r.number} (${r.head} → ${r.base}) was already merged.`
+  return `Merged pull request #${r.number} (${r.head} → ${r.base}) as ${String(r.sha).slice(0, 7)}: ${r.title}.${r.deleted ? ` ${r.head} is deleted.` : ''} The session on ${r.base} brings it in now.`
+}
+
+export const PULLS_DESCRIPTION = 'The open pull requests of this branch\'s repository on GitHub, with how each one\'s checks stand (passing, failing and which, still running, or none). Read it before merging, and to find the pull request for a branch.'
+export const MERGE_DESCRIPTION = 'Merge a pull request on GitHub (by number, or by the branch it comes from) into its base. ' +
+  'Refused while its checks fail or are still running. A Quilt agent\'s branch (quilt/…) is deleted after the merge. ' +
+  'People may always merge (as far as the session\'s GitHub connection may); agents only when the session owner lets agents commit to any branch, otherwise ask a person in chat with the pull request\'s link. ' +
+  'The session on the base branch brings the merge in within seconds.'
+/** quilt_merge's arguments, the same for the local and the hosted tool (`z`: zod). */
+export const mergeSchema = (z) => ({
+  number: z.number().int().min(1).optional().describe('The pull request number'),
+  branch: z.string().max(200).optional().describe('Or the branch the pull request comes from'),
+  method: z.enum(['squash', 'merge', 'rebase']).optional().describe('How to merge (default squash)'),
+  delete_branch: z.boolean().optional().describe('Delete the merged branch (default: yes for quilt/… branches, no otherwise)'),
+  force: z.boolean().optional().describe('People only: merge even while checks fail or are still running')
+})
+
+/**
+ * Whether agents can commit on branch `key` themselves: the owner lets them, and a member's GitHub
+ * connection (or the owner's token) covers the repository. Cheap: from the relay's record.
+ */
+export function agentsCanCommit (room, key) {
+  if (agentCommitsOf(room) === 'off') return false
+  const found = repoRecordFor(room, key)
+  if (!found) return false
+  const rec = found.rec
+  return !!(validToken(room.meta.githubToken) || (rec.github && rec.github.state === 'ok'))
+}
+
+/**
+ * A folder's git pushed (its pre-push hook told its session, which tells the relay): the pushed
+ * content goes on the room's published record, so the branch comes back down clean once merged
+ * (upstream.js), and the chat hears it. `files`: [{ path, id }] (id: sha1 of the bytes); only
+ * paths the member may change are recorded. Written by the relay, so a member whose own writes
+ * are held to a folder (session-access.js) is on record all the same.
+ */
+export function notePushedFor (room, { who, key, branch = '', sha = '', count = 1, files = [], subject = '' }, { fetch = globalThis.fetch, log = () => {} } = {}) {
+  const a = who.access || {}
+  if (a.state && a.state !== 'approved') throw new CommitRefused('You are not let into this session yet.')
+  const list = (Array.isArray(files) ? files : []).filter((f) => f && typeof f.path === 'string' && isSafeRelPath(f.path) && mayChange(a, f.path)).slice(0, 2000)
+  notePublishedIds(room.doc, list.map((f) => [f.path, f.id]), RELAY_PUBLISH)
+  let full = null
+  try { full = githubRepoOf(room, key).full } catch {}
+  const where = full ? `${full} ${branch}` : branch
+  const n = Math.max(1, Number(count) || 1)
+  const names = list.map((f) => f.path)
+  log(`[${room.name}] ${key}: ${who.name} pushed ${n} commit${n === 1 ? '' : 's'} to ${where} (${names.length} files)`)
+  if (room.postChat) room.postChat({ by: RELAY_BY, text: `${who.name} pushed ${n} commit${n === 1 ? '' : 's'} to ${where}${names.length ? `: ${names.slice(0, 8).join(', ')}${names.length > 8 ? ` and ${names.length - 8} more` : ''}` : ''}${full && /^[0-9a-f]{40}$/.test(sha) ? ` https://github.com/${full}/commit/${sha}` : ''}`, kind: 'commit' })
+  // An agent's branch of its own: the pull request opens by itself (after this answer), so no push is left hanging.
+  if (who.kind === 'agent' && full && branch.startsWith(agentPrefix(who.name)) && agentCommitsOf(room) !== 'off') {
+    openPullOnPush(room, { who, key, branch, files: names, subject: String(subject || '') }, { fetch, log }).catch((err) => log(`[${room.name}] ${key}: could not open a pull request for ${who.name}'s ${branch}: ${err.message}`))
+  }
+  return { ok: true, recorded: list.length, branch, repo: full }
+}
+
+/** Sets the pull request a task's work is in ({ number, url, branch, base }) and notes it on the task. */
+/**
+ * The commit a task's pull request is meant to carry (addendum 16.5): every push to the pull request's
+ * branch for the task moves it. reviewPulls moves the task to Done only when the merge has this commit.
+ */
+export function noteTaskRevision (room, number, sha) {
+  const map = room.doc.getMap('tasks')
+  for (const t of readTasks(map)) {
+    if (!t.pr || t.pr.number !== number || t.archived || t.column === 'done' || t.pr.revision === sha) continue
+    updateTask(room.doc, map, { id: t.id, pr: { ...t.pr, revision: sha } }, RELAY_PUBLISH)
+  }
+}
+
+export function linkTaskPull (room, taskId, pr, { log = () => {} } = {}) {
+  const map = room.doc.getMap('tasks')
+  const cur = readTasks(map).find((t) => t.id === taskId)
+  if (!cur) return null
+  if (cur.pr && cur.pr.number === pr.number) return cur
+  const task = updateTask(room.doc, map, { id: taskId, pr }, RELAY_PUBLISH)
+  try { addComment(room.doc, room.doc.getMap('taskComments'), readTasks(map), { taskId, by: RELAY_BY, text: `Pull request #${pr.number} (${pr.branch} → ${pr.base}): ${pr.url}. Moving this task to Done merges it, once its checks pass.` }, RELAY_PUBLISH) } catch (err) { log(`[${room.name}] could not note the pull request on task ${taskId}: ${err.message}`) }
+  return task
+}
+
+/**
+ * The task an agent's push is for: the agent's task In progress whose title slug the branch ends
+ * with, else its only task In progress, else a task made for the push (so every push has a task,
+ * and the board's gates cover it). `by` names the agent.
+ */
+function taskForPush (room, { who, branch, files, subject, taskId = null }) {
+  const map = room.doc.getMap('tasks')
+  const tasks = readTasks(map).filter((t) => !t.archived && t.column !== 'done')
+  const named = taskId ? tasks.find((t) => t.id === taskId) : null
+  if (named) return named
+  const mine = tasks.filter((t) => t.assignee === who.name)
+  const tail = branch.slice(agentPrefix(who.name).length)
+  const linked = mine.find((t) => t.pr && t.pr.branch === branch)
+  if (linked) return linked
+  const bySlug = mine.find((t) => t.column === 'doing' && slug(t.title) === tail) || mine.find((t) => slug(t.title) === tail)
+  if (bySlug) return bySlug
+  const doing = mine.filter((t) => t.column === 'doing' && !t.pr)
+  if (doing.length === 1) return doing[0]
+  const title = (subject || '').split('\n')[0].trim().slice(0, 120) || tail.replace(/-/g, ' ')
+  return addTask(room.doc, map, { title, by: RELAY_BY, assignee: who.name, column: 'doing', files: (files || []).slice(0, 20), conv: '' }, RELAY_PUBLISH)
+}
+
+/**
+ * Opens the pull request for an agent's pushed branch into the branch its work merges into (or
+ * finds the one already open), ties it to the agent's task (made if none), and tells the chat.
+ */
+export async function openPullOnPush (room, { who, key, branch, files = [], subject = '', taskId = null, revision = null }, { fetch = globalThis.fetch, log = () => {} } = {}) {
+  const { repo, full, rec } = githubRepoOf(room, key)
+  if (branch === rec.ref) return null
+  const token = await credentialsFor(room, repo)
+  const gh = githubWriter({ fetch, token, owner: repo.owner, name: repo.name })
+  const task = taskForPush(room, { who, branch, files, subject, taskId })
+  if (task.pr && task.pr.branch === branch) { if (revision) noteTaskRevision(room, task.pr.number, revision); return task.pr }
+  const title = task.title
+  const pr = await gh.pull({ title, head: branch, base: rec.ref, body: `${who.name}'s work on task ${task.id}: ${task.title}.\n\nOpened by Quilt when the branch was pushed. Moving the task to Done in Quilt merges this once its checks pass.` })
+  const linked = { number: pr.number, url: pr.url, branch, base: rec.ref, ...(revision ? { revision } : {}) }
+  linkTaskPull(room, task.id, linked, { log })
+  if (revision) noteTaskRevision(room, pr.number, revision)
+  log(`[${room.name}] ${key}: ${pr.existed ? 'found' : 'opened'} pull request #${pr.number} for ${who.name}'s ${branch} (task ${task.id})`)
+  if (!pr.existed && room.postChat) room.postChat({ by: RELAY_BY, text: `Opened pull request #${pr.number} for ${who.name}'s ${branch} → ${rec.ref}: "${title}" ${pr.url}. Moving task ${task.id} to Done merges it once its checks pass.`, kind: 'commit' })
+  return linked
+}
+
+/**
+ * Moving a task to Done: when its work is on a branch (a pull request) and not yet on the branch
+ * it merges into, Done merges that pull request, once its checks pass. People may always; agents
+ * only when the owner lets agents push to any branch (otherwise the task waits in QA for a person).
+ * Resolves { merged: { sha, number, head, base } } or { merged: null } (nothing to merge); throws
+ * CommitRefused with what to do when it can't.
+ */
+export async function finishTaskFor (room, { who, key, task: taskId }, { fetch = globalThis.fetch, log = () => {} } = {}) {
+  const map = room.doc.getMap('tasks')
+  const task = readTasks(map).find((t) => t.id === taskId)
+  if (!task) return { merged: null }
+  // A clash task (clash.js) is the merge itself.
+  if (Object.values((room.meta && room.meta.upstreams) || {}).some((rec) => rec && rec.clash && rec.clash.task === taskId)) return { merged: null }
+  if (!agentsCanCommit(room, key) && !task.pr) return { merged: null }
+  const u = await unpublishedFor(room, { key, who: task.assignee || who.name, task: taskId, column: 'done' }, { fetch })
+  if (u.unpublished.length) throw new CommitRefused(unpublishedRefusal(task, u.unpublished, 'done', []))
+  if (!u.awaitingMerge.length && !task.pr) return { merged: null }
+  if (!task.pr) throw new CommitRefused(`Not moved to Done: "${task.title}"'s work is on a branch with no pull request yet. Push the branch (from a folder: git push, and Quilt opens it; without a folder: quilt_git_commit on your branch with task: "${task.id}"), then move the task again.`)
+  if (who.kind === 'agent' && agentCommitsOf(room) !== 'any') {
+    throw new CommitRefused(`Not moved to Done: Done merges pull request #${task.pr.number} (${task.pr.branch} → ${task.pr.base}), and here that is a person's call (the owner lets agents push only to branches of their own). Leave the task in QA: a person moves it to Done when it is good, and Quilt merges. ${task.pr.url}`)
+  }
+  const r = await mergeForMember(room, { who, key, number: task.pr.number, method: 'squash' }, { fetch, log })
+  if (r.already) return { merged: null, already: true }
+  try { addComment(room.doc, room.doc.getMap('taskComments'), readTasks(map), { taskId, by: RELAY_BY, text: `Merged pull request #${r.number} (${r.head} → ${r.base}) as ${String(r.sha).slice(0, 7)}, as ${who.name} moved the task to Done.` }, RELAY_PUBLISH) } catch {}
+  return { merged: { sha: r.sha, number: r.number, head: r.head, base: r.base } }
+}
+
+// Pull requests tied to tasks are looked at with the relay's looks (about every ten minutes) and
+// when GitHub says one changed: merged elsewhere moves the task to Done; closed is told; green and
+// waiting in QA nudges whoever may merge; failing checks nudge the agent. Each event (a pull
+// request at a commit, closed, failing at a commit) is told once: the room's saved record
+// (meta.pullTold) says which were, across restarts. One look's news goes as one message per person.
+export const PULL_TOLD_KEEP_MS = 30 * 24 * 60 * 60 * 1000
+
+/** Whether event `k` was told already; records it as told now when not. Saved with the room. */
+function firstTelling (room, k, now) {
+  const told = room.meta.pullTold && typeof room.meta.pullTold === 'object' ? room.meta.pullTold : (room.meta.pullTold = {})
+  if (told[k]) return false
+  told[k] = now
+  for (const [key, at] of Object.entries(told)) if (now - at > PULL_TOLD_KEEP_MS) delete told[key]
+  return true
+}
+
+const prLine = (pr, t) => `PR #${pr.number} "${t.title}" ${pr.url}`
+
+export async function reviewPulls (room, { fetch = globalThis.fetch, log = () => {}, now = Date.now(), only = null } = {}) {
+  const map = room.doc.getMap('tasks')
+  const tasks = readTasks(map).filter((t) => t.pr && !t.archived && t.column !== 'done' && (only == null || t.pr.number === only))
+  if (!tasks.length) return []
+  let gh
+  try {
+    const { repo } = githubRepoOf(room, DEFAULT_KEY)
+    const token = await credentialsFor(room, repo)
+    gh = githubWriter({ fetch, token, owner: repo.owner, name: repo.name })
+  } catch { return [] }
+  const once = (k) => firstTelling(room, k, now)
+  // What this look has to say, per person: { ready: [lines], failing: [lines], closed: [lines] }.
+  const news = new Map()
+  const tell = (to, kind, line) => {
+    if (!to) return
+    const n = news.get(to) || { ready: [], failing: [], closed: [] }
+    if (!n[kind].includes(line)) n[kind].push(line)
+    news.set(to, n)
+  }
+  const out = []
+  for (const t of tasks) {
+    let pr
+    try { pr = await gh.pullRequest(t.pr.number) } catch (err) { log(`[${room.name}] could not read pull request #${t.pr.number}: ${err.message}`); continue }
+    if (pr.merged) {
+      // Addendum 16.5: Done only when the merge has the task's last change. A push that reached the branch after
+      // the merge (or a merge of an older head) leaves the task where it is, and its assignee is told.
+      const rev = t.pr.revision
+      if (rev && pr.sha && rev !== pr.sha) {
+        let has = null
+        try { has = ['identical', 'ahead'].includes(await gh.compare(rev, pr.sha)) } catch (err) { log(`[${room.name}] could not compare ${rev.slice(0, 7)} with pull request #${pr.number}: ${err.message}`) }
+        if (has !== true) {
+          if (has === false && once(`missed\0${t.pr.number}\0${rev}`)) {
+            const text = `Pull request #${pr.number} was merged on GitHub without the task's last change (${rev.slice(0, 7)}, pushed to ${pr.head} after the merged ${String(pr.sha).slice(0, 7)}): "${t.title}" stays in ${t.column} until that change is merged too.`
+            try { addComment(room.doc, room.doc.getMap('taskComments'), readTasks(map), { taskId: t.id, by: RELAY_BY, text }, RELAY_PUBLISH) } catch {}
+            if (room.postChat) room.postChat({ by: RELAY_BY, ...(t.assignee ? { to: t.assignee } : {}), kind: 'nudge', text })
+          }
+          out.push({ task: t.id, merged: true, missing: rev })
+          continue
+        }
+      }
+      if (!once(`merged\0${pr.number}`)) continue
+      updateTask(room.doc, map, { id: t.id, column: 'done', verified: `Pull request #${pr.number} (${pr.head} → ${pr.base}) merged on GitHub as ${String(pr.sha || '').slice(0, 7) || 'a commit'}.` }, RELAY_PUBLISH)
+      try { addComment(room.doc, room.doc.getMap('taskComments'), readTasks(map), { taskId: t.id, by: RELAY_BY, text: `Pull request #${pr.number} was merged on GitHub: the task is Done.` }, RELAY_PUBLISH) } catch {}
+      if (room.postChat) room.postChat({ by: RELAY_BY, text: `PR #${pr.number} "${t.title}" was merged on GitHub; its task is Done.`, kind: 'commit' })
+      if (room.upstreamSoon) room.upstreamSoon(DEFAULT_KEY)
+      out.push({ task: t.id, merged: true })
+      continue
+    }
+    if (pr.state !== 'open') {
+      if (t.assignee && once(`closed\0${t.pr.number}`)) tell(t.assignee, 'closed', prLine(pr, t))
+      out.push({ task: t.id, closed: true })
+      continue
+    }
+    const checks = pr.sha ? await gh.checks(pr.sha).catch(() => ({ state: 'none', failing: [] })) : { state: 'none', failing: [] }
+    if (checks.state === 'failing') {
+      if (t.assignee && once(`failing\0${t.pr.number}\0${pr.sha}`)) {
+        tell(t.assignee, 'failing', `${prLine(pr, t)} (${checks.failing.join(', ')})`)
+        out.push({ task: t.id, failing: true })
+      }
+      continue
+    }
+    if (t.column === 'qa' && (checks.state === 'passing' || checks.state === 'none') && once(`ready\0${t.pr.number}\0${pr.sha}`)) {
+      const owner = room.meta && room.meta.ownerName
+      tell(owner, 'ready', prLine(pr, t))
+      if (agentCommitsOf(room) === 'any' && t.assignee !== owner) tell(t.assignee, 'ready', prLine(pr, t))
+      out.push({ task: t.id, ready: true })
+    }
+  }
+  if (news.size && room.saveMeta) room.saveMeta()
+  if (room.postChat) {
+    for (const [to, n] of news) {
+      const parts = []
+      if (n.ready.length) parts.push(n.ready.length === 1 ? `Ready to merge: ${n.ready[0]}. Move its task to Done to merge it.` : `Ready to merge (move each task to Done):\n${n.ready.map((l) => `- ${l}`).join('\n')}`)
+      if (n.failing.length) parts.push(n.failing.length === 1 ? `Checks failing: ${n.failing[0]}. Fix them on its branch and push again.` : `Checks failing (fix each on its branch and push again):\n${n.failing.map((l) => `- ${l}`).join('\n')}`)
+      if (n.closed.length) parts.push(`Closed on GitHub without merging: ${n.closed.join('; ')}. If the work still stands, push its branch again; if not, move the task back to To do or archive it.`)
+      room.postChat({ by: RELAY_BY, to, kind: 'nudge', text: parts.join('\n') })
+    }
+  }
+  return out
+}
+
+/**
+ * Which of `files` (or of every file `who` changed on record on the branch) are not in git as the
+ * session has them: { able, unpublished: [paths], awaitingMerge: [paths] }. `unpublished` is nowhere
+ * on GitHub; `awaitingMerge` is on a branch (pushed from a folder, or quilt_commit: the room's
+ * published record) but not on the session branch's head yet. For `column` 'qa' only `unpublished`
+ * counts (a pull request under review is in git); for 'done' and by default both. `able` is
+ * whether agents can commit here themselves (agentsCanCommit); without it nothing is checked.
+ * GitHub's file list for the head is kept until the head moves. Never throws: an error reads as nothing unpublished.
+ */
+export async function unpublishedFor (room, { key, who, files = null, task = null, column = '' }, { fetch = globalThis.fetch } = {}) {
+  const able = agentsCanCommit(room, key)
+  if (!able) return { able, unpublished: [], awaitingMerge: [] }
+  try {
+    const { repo, rec } = githubRepoOf(room, key)
+    const e = room.branchDoc(room.resolveKey ? room.resolveKey(key) : key)
+    const history = e.doc.getArray('history').toArray()
+    let list = cleanList(files)
+    if (!list.length) {
+      const t = task ? room.doc.getMap('tasks').get(String(task)) : null
+      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) { if (!list.includes(h.path)) list.push(h.path) }
+      }
+      if (t) for (const f of Array.isArray(t.files) ? t.files : []) if (!list.includes(f)) list.push(f)
+      list = cleanList(list)
+    }
+    const ig = gitIgnoreOf(e)
+    list = list.filter((rel) => !isIgnored(ig, rel))
+    if (!list.length) return { able, unpublished: [], awaitingMerge: [] }
+    const token = await credentialsFor(room, repo)
+    const gh = githubWriter({ fetch, token, owner: repo.owner, name: repo.name })
+    const head = await gh.ref(rec.ref)
+    if (!head) return { able, unpublished: [], awaitingMerge: [] }
+    if (!room.headBlobs) room.headBlobs = new Map()
+    let cached = room.headBlobs.get(rec.ref)
+    if (!cached || cached.head !== head) {
+      const blobs = await gh.blobs((await gh.commit(head)).tree)
+      if (!blobs) return { able, unpublished: [], awaitingMerge: [] }
+      cached = { head, blobs }
+      room.headBlobs.set(rec.ref, cached)
+    }
+    const published = publishedOf(room.doc)
+    const unpublished = []
+    const awaitingMerge = []
+    for (const rel of list) {
+      let now = null
+      try { now = sessionBytes(e, rel) } catch { continue } // a large stored file: committed from a folder
+      const id = now ? gitBlobSha(now) : null
+      if (id === (cached.blobs.get(rel) || null)) continue
+      if (now && (published.get(rel) || []).includes(crypto.createHash('sha1').update(now).digest('hex'))) awaitingMerge.push(rel) // the published record keeps content ids: sha1 of the bytes (upstream.js)
+      else unpublished.push(rel)
+    }
+    return { able, unpublished, awaitingMerge: column === 'qa' ? [] : awaitingMerge, head }
+  } catch { return { able, unpublished: [], awaitingMerge: [] } }
+}
+
+/**
+ * Why a task may not move on: its files are not in git yet (and the agent can get them there itself),
+ * or, for Done, they are on a branch whose pull request isn't merged into the session's branch.
+ */
+export function unpublishedRefusal (task, unpublished, column, awaitingMerge = []) {
+  const title = task && task.title ? `"${task.title}"` : 'this task'
+  const some = (l) => `${l.slice(0, 8).join(', ')}${l.length > 8 ? `, and ${l.length - 8} more` : ''}`
+  if (!unpublished.length && awaitingMerge.length) {
+    return `Not moved to Done: ${title}'s work is on a branch but not merged into the session's branch yet (${some(awaitingMerge)}). ` +
+      'Open its pull request if you haven\'t and ask a person to merge it (an agent may merge when the owner lets agents push to any branch); move the task to QA meanwhile.'
+  }
+  return `Not moved to ${column === 'qa' ? 'QA' : 'Done'}: ${title} has work that isn't in git yet (${some(unpublished)}). ` +
+    `Get it into git first: commit those files and push from your folder (a branch of your own, then a pull request, unless the owner lets agents push to the session's branch); without a folder, quilt_git_commit on your branch (files: those, and a message${task && task.id ? `, or task: "${task.id}"` : ''}). Then move the task again. Work only in the session has not shipped.`
+}
+
+// Agents that leave work uncommitted are reminded (a message that needs no reply, which wakes
+// them): once every REMIND_MS per agent and branch, for files they last changed REMIND_QUIET_MS ago or more.
+export const REMIND_MS = 30 * 60 * 1000
+export const REMIND_QUIET_MS = 5 * 60 * 1000
+/**
+ * Every agent with unpublished work on branch `key` is reminded to commit it (relay-commit.js).
+ * Run by the relay with its looks, about every ten minutes; cheap when nothing changed.
+ */
+export async function remindUnpublished (room, key, { fetch = globalThis.fetch, now = Date.now() } = {}) {
+  if (!agentsCanCommit(room, key) || !room.postChat) return []
+  const agents = new Set(Object.values((room.meta && room.meta.members) || {}).filter((m) => m && m.kind === 'agent' && m.name).map((m) => m.name))
+  // Only a branch that is open (loaded): loading every branch of a room at once, each tick, ran the relay out of
+  // memory. Its agents are reminded when it is next open.
+  const e = room.store && room.store.get ? room.store.get(room.resolveKey ? room.resolveKey(key) : key) : room.branchDoc(room.resolveKey ? room.resolveKey(key) : key)
+  if (!e) { handBackRequests(room, key, agents); return [] }
+  const history = e.doc.getArray('history').toArray()
+  const last = new Map() // agent -> ts of their newest edit
+  for (const h of history) if (h && !h.pulled && !h.seed && h.by && agents.has(h.by) && now - (h.ts || 0) < 24 * 60 * 60 * 1000) last.set(h.by, Math.max(last.get(h.by) || 0, h.ts || 0))
+  if (!room.reminded) room.reminded = new Map()
+  const told = []
+  for (const [name, ts] of last) {
+    if (now - ts < REMIND_QUIET_MS) continue // still at it
+    const k = `${name}\0${key}`
+    if (now - (room.reminded.get(k) || 0) < REMIND_MS) continue
+    const r = await unpublishedFor(room, { key, who: name }, { fetch })
+    if (!r.unpublished.length) continue
+    room.reminded.set(k, now)
+    room.postChat({ by: RELAY_BY, to: name, kind: 'nudge', text: `You changed ${r.unpublished.slice(0, 8).join(', ')}${r.unpublished.length > 8 ? ` and ${r.unpublished.length - 8} more` : ''} on ${key}, and ${r.unpublished.length === 1 ? 'it isn\'t' : 'they aren\'t'} in git. When that work is finished and tested, commit those files and push from your folder (a branch of your own with a pull request, unless the owner lets agents push to ${key}); without a folder, quilt_git_commit with the files and a message. If it is still in progress, carry on.` })
+    told.push(name)
+  }
+  handBackRequests(room, key, agents)
+  return told
+}
+
+/**
+ * Open commit requests by agents that can get their work into git themselves (asked before they
+ * could, or before GitHub was connected) are handed back: closed for people, and the agent is told
+ * to push it. So nothing of an agent's sits on a person's plate once the agent can do it.
+ */
+export function handBackRequests (room, key, agents) {
+  if (!room.postChat || !agentsCanCommit(room, key)) return []
+  const map = room.doc.getMap('commitRequests')
+  const back = [...map.values()].filter((r) => r && r.state === 'open' && agents.has(r.by) && (!r.branch || r.branch === key))
+  if (!back.length) return []
+  room.doc.transact(() => {
+    for (const r of back) map.set(r.id, { ...r, state: 'done', doneBy: RELAY_BY, doneAt: Date.now(), hash: '', committed: [], note: `handed back to ${r.by}: agents get their own work into git here` })
+  }, RELAY_PUBLISH)
+  for (const r of back) {
+    const files = Array.isArray(r.files) && r.files.length ? ` (${r.files.slice(0, 8).join(', ')}${r.files.length > 8 ? `, and ${r.files.length - 8} more` : ''})` : ''
+    room.postChat({ by: RELAY_BY, to: r.by, kind: 'nudge', text: `Your commit request "${r.message}"${files} was handed back to you: agents get their own work into git here now. Commit those files and push from your folder (a branch of your own with a pull request, unless the owner lets agents push to ${key}); without a folder, quilt_git_commit.` })
+  }
+  return back.map((r) => r.id)
+}