heyquilt 0.0.1 → 0.3.90

package/src/relay-clash.js

@@ -0,0 +1,597 @@
+// Merge conflicts, automatically (plan §7.3, step 3 onwards; addendum 16.2, 16.3, 16.8). A file
+// whose lines GitHub and the session both changed is held (relay-sync.js): inbound doesn't write
+// it, outbound keeps the remote version. The two parties resolve it together:
+//
+// - Who: the session side is the member whose edit it is (the branch's history); the GitHub side
+//   is the upstream commit's author, a member when their linked GitHub account or noreply address
+//   says so. The merger is the party online who made the more recent of the two edits (with no
+//   party online, any agent that may change the file); the reviewer is the other party.
+// - Agreement first: both are told, in a direct message, with the base, both versions and the
+//   upstream commit messages on the clash task.
+// - Merge: the merger proposes the merged file (quilt_clash propose, never markers) with the checks
+//   it ran on exactly that content. The proposal is kept apart from the live file (a blob in the
+//   mirror), so nothing half-merged reaches any node; agents can't write a held file at all. The
+//   reviewer accepts (quilt_clash accept), and only then is the file written and pushed. A
+//   reviewer who doesn't answer in 15 minutes is told it went through, when the owner's policy
+//   says so (the default); a reviewer who is offline, outside Quilt or the same member isn't waited for.
+// - Escalation: a merger with no proposal after 15 minutes hands it to the reviewer, then to any
+//   agent; with nobody to take it, the people in the session are told. A person's save of the
+//   file without markers settles it; whoever holds it can keep one side in one action.
+// - Recovery: each clash keeps its own base, ours (a blob) and theirs (commits) under the mirror's
+//   keep refs while it is open and for RESOLVED_KEEP_MS after.
+//
+// Quilt never runs an AI itself: the merger and reviewer are members working a task.
+import crypto from 'node:crypto'
+import * as Y from 'yjs'
+import { syncStateOf, runGit } from './relay-git.js'
+import { upstreamsOf, docKey, hasMarkers, fingerprint, RELAY_ORIGIN } from './relay-upstream.js'
+import { applyTextDiff } from './textdiff.js'
+import { HistoryLog, lineDiff } from './history.js'
+import { readTasks, addTask, updateTask } from './tasks.js'
+import { addComment, MAX_COMMENT } from './task-comments.js'
+import { changeRefusal } from './session-access.js'
+import { RELAY_BY, isRelay } from './branches.js'
+import { slug } from './github-commit.js'
+import { updateMerge } from './merges.js'
+import { isSafeRelPath } from './pathrules.js'
+
+export const CLASH_REVIEW_MS = 15 * 60 * 1000
+export const CLASH_MERGER_IDLE_MS = 15 * 60 * 1000
+export const RESOLVED_KEEP_MS = 30 * 24 * 60 * 60 * 1000
+export const CLASH_ACTIONS = ['propose', 'accept', 'keep_session', 'keep_github', 'keep_offline', 'revert', 'status']
+
+const sha1 = (s) => crypto.createHash('sha1').update(s).digest('hex')
+const isText = (k) => typeof k === 'string' && !k.startsWith('bin:')
+const clip = (s, n) => (s.length > n ? `${s.slice(0, n - 1)}…` : s)
+
+/** Everyone in the session: its members and its owner (who may not be in the members list): [{ id, name, kind, github? }]. */
+export function everyone (room) {
+  const out = Object.entries(room.meta.members || {}).filter(([, m]) => m && m.name).map(([id, m]) => ({ id, ...m }))
+  if (room.meta.ownerName && !out.some((m) => m.name === room.meta.ownerName)) out.push({ id: room.meta.ownerSub || '', name: room.meta.ownerName, kind: 'human', ...(room.meta.ownerGithub ? { github: room.meta.ownerGithub } : {}) })
+  return out
+}
+
+/** Whether `name` (a member, a hosted agent, or a person's AI session) is online in the room now. */
+export function isOnline (room, name) {
+  if (!name) return false
+  for (const ws of (room.conns ? room.conns.keys() : [])) if (room.names && room.names.get(ws) === name) return true
+  if (room.awareness) for (const st of room.awareness.getStates().values()) if (st && Array.isArray(st.personas) && st.personas.some((p) => p && p.name === name)) return true
+  if (room.hostedOnline) for (const h of room.hostedOnline()) if (h.name === name) return true
+  return false
+}
+
+/** A git author as a member: by the agents' or people's noreply address, or the GitHub account a person linked. */
+export function memberForAuthor (room, { name = '', email = '' }) {
+  const e = String(email || '').toLowerCase()
+  const members = everyone(room)
+  let m
+  if ((m = /^([a-z0-9-]+)@agents\.noreply\.heyquilt\.com$/.exec(e))) return members.find((x) => x.kind === 'agent' && slug(x.name, 40) === m[1])?.name || null
+  if ((m = /^([a-z0-9-]+)@people\.noreply\.heyquilt\.com$/.exec(e))) return members.find((x) => x.kind !== 'agent' && slug(x.name, 40) === m[1])?.name || null
+  if ((m = /^(?:\d+\+)?([a-z0-9-]+)@users\.noreply\.github\.com$/.exec(e))) return members.find((x) => x.github && String(x.github.login).toLowerCase() === m[1])?.name || null
+  return null
+}
+
+/** The commits between `base` and `head` that changed `rel`, newest first: [{ sha, name, email, ts, subject }]. */
+export async function upstreamCommits (dir, base, head, rel) {
+  const r = await runGit(dir, ['log', '--format=%H%x1f%an%x1f%ae%x1f%ct%x1f%s', `${base}..${head}`, '--', rel])
+  if (!r.ok) return []
+  return r.out.split('\n').filter(Boolean).map((l) => { const [sha, name, email, ct, subject] = l.split('\x1f'); return { sha, name, email, ts: Number(ct) * 1000, subject } })
+}
+
+/** The session's side: the member who last changed `rel` on the branch (not the relay, not a pull). */
+function sessionParty (e, rel, { except = null } = {}) {
+  // By time, not position: a save soon after the same person's last one folds into that entry where it was (history.js).
+  let best = null
+  for (const h of e.doc.getArray('history').toArray()) {
+    if (h && h.path === rel && !h.pulled && !h.seed && h.by && !isRelay(h.by) && h.by !== except && (!best || (h.ts || 0) >= best.ts)) best = { name: h.by, ts: h.ts || 0 }
+  }
+  return best
+}
+
+/** Agents online that may change `rel` on branch `key`: hosted ones on the branch first, then connected agents. */
+function agentsFor (room, key, rel) {
+  const out = []
+  const ok = (a) => a && a.role && a.role !== 'viewer' && !changeRefusal(a, rel)
+  for (const h of (room.hostedOnline ? room.hostedOnline() : [])) {
+    const m = room.meta.members[h.id] || {}
+    if ((m.kind || 'agent') === 'agent' && !h.chat && ok({ ...m, role: m.role || 'editor' })) out.push(h.name)
+  }
+  for (const ws of (room.conns ? room.conns.keys() : [])) {
+    const a = room.access && room.access.get(ws)
+    if (a && a.kind === 'agent' && ok(a) && room.names && room.names.get(ws)) out.push(room.names.get(ws))
+  }
+  return [...new Set(out)]
+}
+
+/**
+ * Who merges and who reviews a clash: { merger, reviewer, mode } with mode 'same' (both edits by
+ * one member: no reviewer), 'two' (the reviewer is a member), 'outside' (the GitHub side is not a
+ * member), or 'none' (nobody to merge: people are told).
+ */
+export function chooseRoles (room, key, h, { except = [] } = {}) {
+  const s = h.parties.session
+  // The other side: GitHub's author (a member, or someone outside Quilt), or a member back from editing offline.
+  const g = h.parties.github
+  const off = h.parties.offline
+  const o = g ? { name: g.member || null, ts: g.ts, outside: !g.member } : off ? { name: off.name, ts: off.ts, outside: false } : null
+  const om = o && o.name
+  if (s && om && s.name === om) {
+    if (!except.includes(s.name) && isOnline(room, s.name)) return { merger: s.name, reviewer: null, mode: 'same' }
+    const any = agentsFor(room, key, h.path).find((n) => !except.includes(n))
+    return any ? { merger: any, reviewer: s.name, mode: 'same' } : { merger: null, reviewer: s.name, mode: 'none' }
+  }
+  const parties = [s ? { name: s.name, ts: s.ts } : null, om ? { name: om, ts: o.ts } : null].filter(Boolean)
+  const online = parties.filter((p) => !except.includes(p.name) && isOnline(room, p.name)).sort((a, b) => b.ts - a.ts)
+  let merger = online[0] ? online[0].name : null
+  if (!merger) merger = agentsFor(room, key, h.path).find((n) => !except.includes(n)) || null
+  const reviewer = parties.map((p) => p.name).find((n) => n !== merger) || null
+  if (!merger) return { merger: null, reviewer, mode: 'none' }
+  return { merger, reviewer, mode: o && o.outside ? 'outside' : 'two' }
+}
+
+/** Stores `text` as a blob in the mirror (kept by the clash's keep refs): its sha, or null. */
+async function storeBlob (dir, text) {
+  const r = await runGit(dir, ['hash-object', '-w', '--stdin'], { input: Buffer.from(text, 'utf8') })
+  return r.ok ? r.out.trim() : null
+}
+async function readBlob (dir, sha) {
+  const r = await runGit(dir, ['cat-file', 'blob', sha], { buffer: true })
+  return r.ok ? r.out.toString('utf8') : null
+}
+async function fileAt (dir, commit, rel) {
+  const r = await runGit(dir, ['cat-file', 'blob', `${commit}:${rel}`], { buffer: true })
+  return r.ok ? r.out.toString('utf8') : null
+}
+
+const post = (room, taskId, text) => { try { addComment(room.doc, room.taskComments || room.doc.getMap('taskComments'), readTasks(room.tasks || room.doc.getMap('tasks')), { taskId, by: RELAY_BY, text: clip(text, MAX_COMMENT) }, RELAY_ORIGIN) } catch {} }
+const dm = (room, to, text, kind = 'nudge') => { if (to && room.postChat) room.postChat({ by: RELAY_BY, to, kind, text }) }
+
+/**
+ * A file just held for a clash (relay-sync.js): its parties, merger and reviewer, the clash task
+ * with the thread's material on it, and both parties told. `texts`: { base, ours, theirs } (keys as
+ * the branch document has them). Mutates `h` (a state.held entry) and returns it.
+ */
+export async function openClash (room, key, rec, h, { dir, texts, now = Date.now() }) {
+  const e = room.branchDoc(key)
+  const commits = await upstreamCommits(dir, h.base, h.theirs, h.path)
+  const top = commits[0] || null
+  h.parties = {
+    session: sessionParty(e, h.path),
+    github: top ? { name: top.name, email: top.email, ts: top.ts, sha: top.sha, subject: top.subject, member: memberForAuthor(room, top) } : null
+  }
+  h.binary = !isText(texts.ours) || !isText(texts.theirs)
+  Object.assign(h, chooseRoles(room, key, h), { assignedAt: now, candidate: null })
+  if (isText(texts.ours)) h.oursBlob = await storeBlob(dir, texts.ours)
+  const tasks = room.tasks || room.doc.getMap('tasks')
+  const sideS = h.parties.session ? h.parties.session.name : 'the session'
+  const sideG = h.parties.github ? (h.parties.github.member || `${h.parties.github.name} (on GitHub, not in this session)`) : 'GitHub'
+  const title = clip(`Merge ${h.path} on ${key}: ${sideS} and ${sideG} changed the same lines`, 200)
+  let task = null
+  try {
+    task = addTask(room.doc, tasks, { title, by: RELAY_BY, assignee: h.merger || '', forAi: false, tool: '', files: [h.path] }, RELAY_ORIGIN)
+  } catch (err) { room.log && room.log(`[${room.name}] ${key}: could not put the clash on ${h.path} on the board: ${err.message}`) }
+  h.task = task ? task.id : null
+  if (task) {
+    const lines = [
+      `${h.path} is held on \`${key}\`: the session and GitHub changed the same lines. Nothing half-merged reaches anyone; everything else keeps syncing.`,
+      `- Session side: ${sideS}${h.parties.session ? ` (${new Date(h.parties.session.ts).toISOString().slice(0, 16)}Z)` : ''}`,
+      `- GitHub side: ${sideG}${commits.length ? `, in ${commits.length} commit${commits.length === 1 ? '' : 's'}: ${commits.slice(0, 5).map((c) => `${c.sha.slice(0, 7)} "${clip(c.subject, 80)}"`).join('; ')}` : ''}`,
+      `- Merger: ${h.merger || 'nobody yet (no party or agent online)'}; reviewer: ${h.reviewer || (h.mode === 'outside' ? 'none (the GitHub side is outside Quilt: they get a comment on their commit)' : 'none')}.`,
+      '- Checks: the merger runs the project\'s own checks (its test command) in its own folder or tool, on exactly the content it proposes, and says how they went; a changed proposal needs them again. The relay never runs code or an AI.',
+      '',
+      h.binary
+        ? 'A binary file can\'t be merged: pick one side with quilt_clash keep_session or keep_github.'
+        : 'Agree on what each change was for first (quilt_message each other). Then the merger proposes the merged file with quilt_clash (action "propose", the full content without conflict markers, and the checks you ran on exactly that content); the reviewer accepts with quilt_clash accept. Only then is it written and pushed. Writing the file directly is refused while it is held.'
+    ]
+    post(room, task.id, lines.join('\n'))
+    if (isText(texts.base) || texts.base === null) {
+      const b = isText(texts.base) ? texts.base : ''
+      if (isText(texts.ours)) post(room, task.id, `The session's change (base → session):\n\`\`\`diff\n${lineDiff(b, texts.ours, { max: MAX_COMMENT - 200 })}\n\`\`\``)
+      if (isText(texts.theirs)) post(room, task.id, `GitHub's change (base → ${h.theirs.slice(0, 7)}):\n\`\`\`diff\n${lineDiff(b, texts.theirs, { max: MAX_COMMENT - 200 })}\n\`\`\``)
+    }
+  }
+  tellRoles(room, key, h, { fresh: true })
+  room.log && room.log(`[${room.name}] ${key}: clash on ${h.path}: merger ${h.merger || 'none'}, reviewer ${h.reviewer || 'none'} (${h.mode})`)
+  return h
+}
+
+/** Tells the merger and the reviewer what is theirs to do (or the people, when nobody can merge). */
+function tellRoles (room, key, h, { fresh = false, why = '' } = {}) {
+  const ref = h.task ? ` (task ${h.task})` : ''
+  if (h.merger) {
+    const person = (everyone(room).find((m) => m.name === h.merger) || {}).kind !== 'agent'
+    const how = person
+      ? `merge it in your editor and save it without conflict markers (that settles it), or have your AI propose it with quilt_clash`
+      : 'propose the merged file with quilt_clash propose (no markers), with the checks you ran on it'
+    dm(room, h.merger, `${why ? `${why} ` : ''}You merge ${h.path} on ${key}${ref}: ${h.reviewer ? `${h.reviewer} reviews` : 'nobody needs to review'}.${h.binary ? ' It is a binary file: keep one side with quilt_clash keep_session or keep_github.' : ` ${h.reviewer && h.mode !== 'same' ? `Agree with ${h.reviewer} on intent first, then` : 'Then'} ${how}.`}`)
+  }
+  if (h.reviewer && fresh) dm(room, h.reviewer, `${h.path} on ${key} clashes with your work${ref}. ${h.merger ? `${h.merger} merges it; you review the result (quilt_clash accept), and nothing is pushed until you do${h.mode === 'two' ? ' or 15 minutes pass' : ''}.` : 'Nobody is online to merge it yet.'}`)
+  if (!h.merger && !h.toldNone) {
+    h.toldNone = Date.now()
+    if (room.postChat) room.postChat({ by: RELAY_BY, kind: 'nudge', text: `${key} has 1 clash in ${h.path}, waiting for an AI or you${ref}. Everything else keeps syncing.` })
+  }
+}
+
+/** The held clash entry for `rel` on `key`, or null. */
+export const clashOf = (room, key, rel) => syncStateOf(room, key).held.find((x) => x.path === rel && (x.why === 'clash' || x.why === 'checks')) || null
+
+/** Writes `text` (or deletes, with null) into branch `key` as `by`, recorded in its history, and marks it pending for the next commit. */
+function writeResolved (room, key, rel, text, by) {
+  const e = room.branchDoc(key)
+  const history = e.historyLog || (e.historyLog = new HistoryLog(e.doc, e.doc.getArray('history'), { origin: RELAY_ORIGIN }))
+  const before = e.files.get(rel)?.toString()
+  e.doc.transact(() => {
+    if (text === null) { e.files.delete(rel); e.blobs.delete(rel); history.record({ by, path: rel, kind: 'deleted', before, after: '' }); return }
+    e.blobs.delete(rel)
+    let y = e.files.get(rel)
+    if (!y) { y = new Y.Text(); e.files.set(rel, y) }
+    applyTextDiff(y, text)
+    history.record({ by, path: rel, kind: before === undefined ? 'created' : 'edited', before: before ?? '', after: text })
+  }, RELAY_ORIGIN)
+  if (room.outbound) room.outbound.note(key, rel)
+}
+
+/** Ends the clash on `rel`: released from held, kept as resolved (for recovery and undo), its task Done. */
+export function finishClash (room, key, h, opts) { return finish(room, key, h, opts) }
+function finish (room, key, h, { how, by, text = null, now = Date.now(), mergeHow = 'agent' }) {
+  const state = syncStateOf(room, key)
+  state.held = state.held.filter((x) => x !== h)
+  if (h.kind === 'offline' && h.mergeId) {
+    // The returning member's merge record (merges.js) closes with it.
+    try { const e = room.branchDoc(key); updateMerge(e.doc, e.doc.getMap('merges'), h.mergeId, { state: 'done', how: mergeHow, resolvedBy: String(by).slice(0, 80) }, RELAY_ORIGIN) } catch {}
+    // GitHub changed the file while it was held: that comes in now, against the base it was measured from (relay-sync.js).
+    if (h.upstreamMoved) state.held.push({ path: h.path, why: 'clash', base: h.upstreamMoved.base, theirs: h.upstreamMoved.theirs, head: h.upstreamMoved.theirs, was: null, regions: [], since: now })
+  }
+  if (!Array.isArray(state.resolved)) state.resolved = []
+  state.resolved.push({ path: h.path, kind: h.kind || 'upstream', base: h.base, theirs: h.theirs, oursBlob: h.oursBlob || null, otherBlob: h.otherBlob || null, baseBlob: h.baseBlob || null, candidateBlob: h.candidate ? h.candidate.blob : null, how, by, merger: h.merger, reviewer: h.reviewer, parties: h.parties, at: now, task: h.task })
+  state.resolved = state.resolved.filter((r) => now - r.at < RESOLVED_KEEP_MS).slice(-100)
+  if (h.task) {
+    try { updateTask(room.doc, room.tasks || room.doc.getMap('tasks'), { id: h.task, column: 'done', verified: `Clash on ${h.path} settled (${how}) by ${by}.` }, RELAY_ORIGIN) } catch {}
+    post(room, h.task, `Settled: ${how} by ${by}. ${text === null ? '' : 'The merged file is in the session and goes to GitHub with the next commit. '}Both sides stay recoverable: the session's version in the history${h.kind === 'offline' ? `, ${h.parties.offline.name}'s in the merge record` : h.theirs ? `, GitHub's in ${h.theirs.slice(0, 7)}` : ''}.`)
+  }
+  room.saveMeta()
+  room.broadcastBranches && room.broadcastBranches()
+}
+
+/** Sends the merged result to the GitHub side when they are outside Quilt: a comment on their commit (REST metadata). */
+async function commentUpstream (room, key, h) {
+  const g = h.parties && h.parties.github
+  if (!g || g.member || !g.sha) return false
+  const rec = upstreamsOf(room)[key]
+  try {
+    const [owner, name] = String(rec.repo).replace(/^github\.com\//, '').split('/')
+    const token = await room.gitToken({ owner, name, slug: rec.repo }, { access: 'write' })
+    if (!token) return false
+    const res = await (room.githubFetch || globalThis.fetch)(`https://api.github.com/repos/${owner}/${name}/commits/${g.sha}/comments`, {
+      method: 'POST',
+      headers: { 'user-agent': 'quilt-relay', 'x-github-api-version': '2022-11-28', accept: 'application/vnd.github+json', authorization: `Bearer ${token}`, 'content-type': 'application/json' },
+      body: JSON.stringify({ body: `This commit changed the same lines of \`${h.path}\` as work in a Quilt session on \`${key}\`. ${h.merger} merged the two in the session; the merged file reaches \`${key}\` with the session's next commit.` })
+    })
+    return res.ok
+  } catch { return false }
+}
+
+/** The project's checks as the merger reported them for content `fp`: whether they let the merge through. */
+const checksOk = (c, fp) => !!c && c.fp === fp && (c.result === 'passed' || c.result === 'none')
+
+/**
+ * quilt_clash, for `who` ({ name, kind, access }) on branch `key`. Resolves { ok, text } or throws
+ * an Error with what to do. Actions:
+ * - propose { path, content, checks: { result: passed|failed|none, command } }: the merger's merged file.
+ * - accept { path, force }: the reviewer takes the proposal (force: a person, past failing checks).
+ * - keep_session / keep_github { path }: whoever holds it, or a person: one side, the other recoverable.
+ * - revert { path }: the reviewer (or a person) after it went through: their side back.
+ * - status: the clashes on this branch.
+ */
+export async function clashAction (room, { who, key, action, path: rel = '', content = null, checks = null, force = false }, { now = Date.now() } = {}) {
+  if (!CLASH_ACTIONS.includes(action)) throw new Error(`action is one of ${CLASH_ACTIONS.join(', ')}`)
+  const state = syncStateOf(room, key)
+  const person = who.kind !== 'agent'
+  if (action === 'status') {
+    const open = state.held.filter((h) => h.why === 'clash')
+    if (!open.length) return { ok: true, text: `No clashes on ${key}.` }
+    return { ok: true, text: open.map((h) => `- ${h.path}: merger ${h.merger || 'nobody yet'}, reviewer ${h.reviewer || 'none'}${h.candidate ? `; proposed by ${h.candidate.by} (checks ${h.candidate.checks ? h.candidate.checks.result : 'not reported'})` : '; no proposal yet'}${h.task ? ` (task ${h.task})` : ''}`).join('\n') }
+  }
+  if (action === 'revert') {
+    const r = [...(state.resolved || [])].reverse().find((x) => x.path === rel)
+    if (!r) throw new Error(`No settled clash on ${rel} to revert.`)
+    if (!person && who.name !== r.reviewer) throw new Error(`Only ${r.reviewer || 'a person'} (the reviewer) or a person can revert it.`)
+    const dir = await mirrorDirOf(room, key)
+    const reviewerSide = r.parties && r.parties.github && r.parties.github.member === r.reviewer ? 'github' : r.parties && r.parties.offline && r.parties.offline.name === r.reviewer ? 'offline' : 'session'
+    const text = reviewerSide === 'github' ? await fileAt(dir, r.theirs, rel) : reviewerSide === 'offline' ? (r.otherBlob ? await readBlob(dir, r.otherBlob) : null) : (r.oursBlob ? await readBlob(dir, r.oursBlob) : null)
+    if (text === null) throw new Error(`That version of ${rel} isn't kept any more.`)
+    writeResolved(room, key, rel, text, who.name)
+    r.reverted = { by: who.name, at: now }
+    room.saveMeta()
+    if (r.merger && r.merger !== who.name) dm(room, r.merger, `${who.name} reverted your merge of ${rel} on ${key} to ${reviewerSide === 'github' ? 'GitHub\'s' : 'the session\'s'} version.`)
+    return { ok: true, text: `Reverted ${rel} on ${key} to ${reviewerSide === 'github' ? 'GitHub\'s' : reviewerSide === 'offline' ? 'your offline' : 'the session\'s'} version; it goes to GitHub with the next commit.` }
+  }
+  const h = clashOf(room, key, rel)
+  if (!h) throw new Error(`${rel} isn't held for a clash on ${key}.`)
+  const dir = await mirrorDirOf(room, key)
+  if (action === 'keep_session' || action === 'keep_github' || action === 'keep_offline') {
+    if (h.kind === 'offline' && action === 'keep_github') throw new Error(`${rel} clashes with ${h.parties.offline.name}'s offline edits, not GitHub: keep_session or keep_offline.`)
+    if (h.kind !== 'offline' && action === 'keep_offline') throw new Error(`${rel} clashes with GitHub: keep_session or keep_github.`)
+    if (!person && who.name !== h.merger) throw new Error(`${h.merger} holds ${rel}: only they or a person can pick a side.`)
+    if (action === 'keep_offline') {
+      const text = h.otherDeleted ? null : h.otherBlob ? await readBlob(dir, h.otherBlob) : null
+      if (text === null && !h.otherDeleted) throw new Error(`${h.parties.offline.name}'s version isn't kept any more.`)
+      writeResolved(room, key, rel, text, who.name)
+      finish(room, key, h, { how: `kept ${h.parties.offline.name}'s version`, by: who.name, text, now, mergeHow: 'mine' })
+      if (h.reviewer && h.reviewer !== who.name) dm(room, h.reviewer, `${who.name} settled the clash on ${rel} on ${key} by keeping ${h.parties.offline.name}'s version; the session's is recoverable (quilt_clash revert).`)
+      return { ok: true, text: `Kept ${h.parties.offline.name}'s version of ${rel}; the session's is recoverable.` }
+    }
+    if (h.why === 'checks') throw new Error(`${rel} is held because checks failed after its merge, not for a clash: propose a fix, or a person accepts the failure (quilt_clash accept).`)
+    const text = action === 'keep_github' ? await fileAt(dir, h.theirs, rel) : docKey(room.branchDoc(key), rel)
+    if (action === 'keep_github') writeResolved(room, key, rel, text, who.name)
+    else if (room.outbound) room.outbound.note(key, rel)
+    finish(room, key, h, { how: action === 'keep_github' ? 'kept GitHub\'s version' : 'kept the session\'s version', by: who.name, text, now, mergeHow: action === 'keep_github' ? 'agent' : 'theirs' })
+    if (h.reviewer && h.reviewer !== who.name) dm(room, h.reviewer, `${who.name} settled the clash on ${rel} on ${key} by keeping ${action === 'keep_github' ? 'GitHub\'s' : 'the session\'s'} version; the other is recoverable (quilt_clash revert).`)
+    return { ok: true, text: `Kept ${action === 'keep_github' ? 'GitHub\'s' : 'the session\'s'} version of ${rel}; the other side is recoverable.` }
+  }
+  if (action === 'propose') {
+    if (who.name !== h.merger && !person) throw new Error(`${h.merger || 'Another member'} merges ${rel}${h.task ? ` (task ${h.task})` : ''}: you can't propose for it.`)
+    if (h.binary) throw new Error(`${rel} is binary: keep one side (keep_session or keep_github).`)
+    if (typeof content !== 'string') throw new Error('Give the merged file\'s full content.')
+    if (hasMarkers(content)) throw new Error('The proposal still has conflict markers: resolve them first.')
+    const c = checks && typeof checks === 'object' ? checks : null
+    if (!c || !['passed', 'failed', 'none'].includes(c.result)) throw new Error('Say how the project\'s checks went on exactly this content: checks.result passed, failed or none (the project has none), and checks.command.')
+    const fp = sha1(content)
+    const blob = await storeBlob(dir, content)
+    h.candidate = { by: who.name, at: now, fp, blob, checks: { result: c.result, command: String(c.command || '').slice(0, 300), fp } }
+    if (who.name !== h.merger) h.merger = who.name
+    room.saveMeta()
+    // Not waited for: the same member, a GitHub side outside Quilt, or a reviewer who is offline.
+    const wait = h.reviewer && h.reviewer !== who.name && h.mode !== 'same' && isOnline(room, h.reviewer)
+    if (!wait) {
+      if (!checksOk(h.candidate.checks, fp)) return { ok: false, text: `Proposed, but the checks failed (${h.candidate.checks.command || 'the project\'s checks'}): fix the merge and propose again, or a person accepts it past them.` }
+      await accept(room, key, h, { by: who.name, now, dir })
+      if (h.reviewer && h.reviewer !== who.name) dm(room, h.reviewer, `While you were away, ${who.name} merged ${rel} on ${key} with your work (task ${h.task}); it is pushed. If it isn't right, quilt_clash revert puts your version back.`)
+      return { ok: true, text: `Merged ${rel}: written to the session; it goes to GitHub with the next commit${h.parties.github && !h.parties.github.member ? '; the GitHub side gets a comment on their commit' : ''}.` }
+    }
+    dm(room, h.reviewer, `${who.name} proposed the merge of ${rel} on ${key} (task ${h.task}; checks: ${h.candidate.checks.result}${h.candidate.checks.command ? `, ${h.candidate.checks.command}` : ''}). Review it with quilt_clash status and accept with quilt_clash accept${room.meta.clashTimeout === 'publish' ? '; without an answer in 15 minutes it goes through (the owner\'s setting)' : ''}.`)
+    if (h.task) post(room, h.task, `${who.name} proposed:\n\`\`\`diff\n${lineDiff(docKey(room.branchDoc(key), rel) || '', content, { max: MAX_COMMENT - 200 })}\n\`\`\``)
+    return { ok: true, text: `Proposed. ${h.reviewer} reviews it; nothing is written or pushed until then.` }
+  }
+  // accept
+  if (h.candidate && isRelay(h.candidate.by) && checks && ['passed', 'none'].includes(checks.result)) {
+    // A merge the relay suggested (word by word): whoever accepts it ran the checks on it.
+    if (!person && who.name !== h.merger && who.name !== h.reviewer) throw new Error(`${h.merger} or ${h.reviewer} accepts the suggested merge of ${rel}.`)
+    h.candidate.checks = { result: checks.result, command: String(checks.command || '').slice(0, 300), fp: h.candidate.fp, by: who.name }
+  }
+  if (h.why === 'checks' && !h.candidate) {
+    if (!person) throw new Error(`Checks failed after the merge of ${rel}: propose a fix (quilt_clash propose, with the checks passing), or a person accepts the failure.`)
+    finish(room, key, h, { how: `the failing checks accepted by ${who.name}`, by: who.name, text: null, now })
+    if (room.outbound) room.outbound.note(key, rel)
+    return { ok: true, text: `Accepted the failing checks on ${rel}; it syncs to GitHub again.` }
+  }
+  if (!h.candidate) throw new Error(`Nothing is proposed for ${rel} yet: ${h.merger || 'the merger'} proposes first.`)
+  if (who.name === h.candidate.by && !person) throw new Error('The reviewer accepts, not the merger.')
+  if (isRelay(h.candidate.by) && !checksOk(h.candidate.checks, h.candidate.fp) && !(person && force)) throw new Error(`The relay suggested a word-by-word merge of ${rel}: accept it with checks (how the project's checks went on it), or propose another.`)
+  if (!person && h.reviewer && who.name !== h.reviewer && !isRelay(h.candidate.by)) throw new Error(`${h.reviewer} reviews ${rel}.`)
+  if (!checksOk(h.candidate.checks, h.candidate.fp)) {
+    const overridable = person && force && room.meta.clashOverride !== false
+    if (!overridable) throw new Error(`The checks on the proposal ${h.candidate.checks.result === 'failed' ? 'failed' : 'aren\'t for this content'}: the merger fixes it and proposes again${person ? ', or accept with force: true to take it as it is' : ''}.`)
+  }
+  await accept(room, key, h, { by: who.name, now, dir })
+  return { ok: true, text: `Accepted ${h.candidate.by}'s merge of ${rel}: written to the session; it goes to GitHub with the next commit.` }
+}
+
+async function accept (room, key, h, { by, now, dir }) {
+  const text = await readBlob(dir, h.candidate.blob)
+  if (text === null) throw new Error('The proposal isn\'t kept any more: propose again.')
+  writeResolved(room, key, h.path, text, h.candidate.by)
+  noteMerged(room, key, h.path, h.parties || {}, { now })
+  finish(room, key, h, { how: `merged by ${h.candidate.by}, accepted by ${by}`, by, text, now })
+  // GitHub's side, outside Quilt, hears where its change went. Nothing is pushed here: the merged file goes with the session's next commit.
+  if (h.parties.github && !h.parties.github.member) commentUpstream(room, key, h).catch(() => {})
+}
+
+async function mirrorDirOf (room, key) {
+  const rec = upstreamsOf(room)[key]
+  const { parseRepo } = await import('./relay-upstream.js')
+  const repo = parseRepo(`https://${rec.repo}`)
+  return (await room.mirrors.ensure(repo, { url: room.gitRemoteUrl(repo) })).dir
+}
+
+/**
+ * The relay's look at the open clashes on `key` (each look, and as people come and go): a proposal
+ * nobody reviewed in 15 minutes goes through (owner's policy 'publish', the default); a merger with
+ * no proposal after 15 minutes hands it on (the reviewer, then any agent); a clash nobody could take
+ * is given to whoever is online now. Returns what changed.
+ */
+export async function reviewClashes (room, key, { now = Date.now(), reviewMs = CLASH_REVIEW_MS, idleMs = CLASH_MERGER_IDLE_MS } = {}) {
+  const state = syncStateOf(room, key)
+  const out = []
+  for (const h of [...state.held]) {
+    if (h.why !== 'clash' || !h.parties) continue
+    if (h.candidate && h.reviewer && now - h.candidate.at >= reviewMs && room.meta.clashTimeout === 'publish' && checksOk(h.candidate.checks, h.candidate.fp)) {
+      const dir = await mirrorDirOf(room, key)
+      await accept(room, key, h, { by: RELAY_BY, now, dir })
+      dm(room, h.reviewer, `${h.reviewer}, the merge of ${h.path} on ${key} by ${h.candidate.by} went through after 15 minutes without your review (task ${h.task}). If it isn't right, quilt_clash revert puts your version back.`)
+      out.push({ path: h.path, timedOut: true })
+      continue
+    }
+    if (!h.candidate && h.merger && now - (h.assignedAt || 0) >= idleMs) {
+      const tried = [...(h.tried || []), h.merger]
+      const next = h.reviewer && !tried.includes(h.reviewer) && isOnline(room, h.reviewer) ? h.reviewer : agentsFor(room, key, h.path).find((n) => !tried.includes(n)) || null
+      if (next) {
+        const was = h.merger
+        h.tried = tried; h.merger = next; h.assignedAt = now
+        if (h.reviewer === next) h.reviewer = was
+        if (h.task) { try { updateTask(room.doc, room.tasks || room.doc.getMap('tasks'), { id: h.task, assignee: next, forAi: false, tool: '' }, RELAY_ORIGIN) } catch {} ; post(room, h.task, `Handed to ${next}: ${was} made no proposal in 15 minutes.`) }
+        tellRoles(room, key, h, { why: `${was} made no proposal for 15 minutes.` })
+        out.push({ path: h.path, handedTo: next })
+      }
+      continue
+    }
+    if (!h.merger) {
+      const r = chooseRoles(room, key, h)
+      if (r.merger) {
+        Object.assign(h, { merger: r.merger, reviewer: r.reviewer || h.reviewer, mode: r.mode, assignedAt: now })
+        if (h.task) { try { updateTask(room.doc, room.tasks || room.doc.getMap('tasks'), { id: h.task, assignee: r.merger, forAi: false, tool: '' }, RELAY_ORIGIN) } catch {} }
+        tellRoles(room, key, h, { why: `${r.merger} is online now.` })
+        out.push({ path: h.path, handedTo: r.merger })
+      }
+    }
+  }
+  if (out.length) room.saveMeta()
+  return out
+}
+
+/** Whether `rel` on branch `key` is held for a clash (agents may not write it; relay-mcp.js, server.js checkChange). */
+export const heldForClash = (room, key, rel) => !!(room.meta.sync && room.meta.sync[key] && Array.isArray(room.meta.sync[key].held) && room.meta.sync[key].held.some((h) => h.path === rel && (h.why === 'clash' || h.why === 'checks')))
+
+export const CLASH_DESCRIPTION = 'Resolve a file held because the session and GitHub changed the same lines (see the clash task). ' +
+  'The merger proposes the merged file (action "propose": the full content without conflict markers, and the result of the project\'s checks you ran on exactly that content); the reviewer accepts it ("accept"); only then is it written to the session, to go to GitHub with the next commit. ' +
+  'Whoever holds the file (or a person) can keep one side ("keep_session" or "keep_github"); the other stays recoverable. The reviewer can undo a merge that went through ("revert"). "status" lists the clashes on your branch. Writing a held file directly is refused.'
+export const clashSchema = (z) => ({
+  action: z.enum(CLASH_ACTIONS).describe('propose, accept, keep_session, keep_github, revert or status'),
+  path: z.string().max(1024).optional().describe('The held file'),
+  content: z.string().max(1024 * 1024).optional().describe('propose: the merged file, in full, without conflict markers'),
+  checks: z.object({ result: z.enum(['passed', 'failed', 'none']), command: z.string().max(300).optional() }).optional().describe('propose (or accept, for a merge the relay suggested): how the project\'s checks went on exactly this content (none: the project has no checks)'),
+  force: z.boolean().optional().describe('accept, people only: take the proposal past failing checks')
+})
+
+/**
+ * A merged file (an automatic merge on the way in, or a clash settled) is on record until it is
+ * pushed: then the commit it went in is, with both parties, so failing checks on that commit can
+ * pull them back in (plan §7.3, conflicts with no textual overlap).
+ */
+export function noteMerged (room, key, rel, parties, { now = Date.now() } = {}) {
+  const state = syncStateOf(room, key)
+  if (!state.merged || typeof state.merged !== 'object') state.merged = {}
+  state.merged[rel] = { parties, at: now }
+}
+
+/** Called by the outbound push: the merged files that went in `sha`. */
+export function notePushedMerges (room, key, sha, changed) {
+  const state = syncStateOf(room, key)
+  if (!state.merged) return
+  const files = changed.filter((rel) => state.merged[rel])
+  if (!files.length) return
+  if (!state.mergeCommits || typeof state.mergeCommits !== 'object') state.mergeCommits = {}
+  state.mergeCommits[sha] = { files, parties: files.map((rel) => state.merged[rel].parties), at: Date.now() }
+  for (const rel of files) delete state.merged[rel]
+  const keys = Object.keys(state.mergeCommits)
+  for (const k of keys.slice(0, Math.max(0, keys.length - 20))) delete state.mergeCommits[k]
+}
+
+/** The failing check runs' annotations on `sha` (REST metadata): [{ path, line }], or [] when GitHub doesn't say. */
+async function failingLines (room, key, sha) {
+  const rec = upstreamsOf(room)[key]
+  try {
+    const [owner, name] = String(rec.repo).replace(/^github\.com\//, '').split('/')
+    const token = await room.gitToken({ owner, name, slug: rec.repo })
+    const f = room.githubFetch || globalThis.fetch
+    const headers = { 'user-agent': 'quilt-relay', 'x-github-api-version': '2022-11-28', accept: 'application/vnd.github+json', ...(token ? { authorization: `Bearer ${token}` } : {}) }
+    const runs = await (await f(`https://api.github.com/repos/${owner}/${name}/commits/${sha}/check-runs?per_page=50`, { headers })).json()
+    const out = []
+    for (const r of (runs && runs.check_runs) || []) {
+      if (r.conclusion !== 'failure' || !r.id) continue
+      const ann = await (await f(`https://api.github.com/repos/${owner}/${name}/check-runs/${r.id}/annotations?per_page=50`, { headers })).json()
+      for (const a of Array.isArray(ann) ? ann : []) if (a && a.path) out.push({ path: a.path, line: a.start_line || 0, message: String(a.message || '').slice(0, 200) })
+    }
+    return out
+  } catch { return [] }
+}
+
+/**
+ * GitHub's checks on `sha` (a check_suite) finished. Failing on a commit that carried merged files:
+ * the files the failing lines are in (all its merged files when GitHub names none) are held, and
+ * both parties of their merges are pulled into one task: the merger proposes a fix with the checks
+ * passing, or a person accepts the failure. Passing on a commit at or after one that held files:
+ * they are let go of. Returns what changed.
+ */
+export async function noteMergeChecks (room, key, { sha, conclusion }, { now = Date.now() } = {}) {
+  const state = syncStateOf(room, key)
+  const out = []
+  if (conclusion === 'success') {
+    const holds = state.held.filter((h) => h.why === 'checks')
+    if (!holds.length) return out
+    const dir = await mirrorDirOf(room, key)
+    for (const h of holds) {
+      if (h.sha !== sha && !(await runGit(dir, ['merge-base', '--is-ancestor', h.sha, sha])).ok) continue
+      finish(room, key, h, { how: `checks passed on ${sha.slice(0, 7)}`, by: RELAY_BY, text: null, now })
+      if (room.outbound) room.outbound.note(key, h.path)
+      out.push({ path: h.path, released: true })
+    }
+    return out
+  }
+  if (conclusion !== 'failure' && conclusion !== 'timed_out') return out
+  const mc = state.mergeCommits && state.mergeCommits[sha]
+  if (!mc) return out
+  const lines = await failingLines(room, key, sha)
+  const named = mc.files.filter((rel) => lines.some((l) => l.path === rel))
+  const files = named.length ? named : mc.files
+  const parties = mc.parties[mc.files.indexOf(files[0])] || {}
+  const names = [parties.session && parties.session.name, parties.github && (parties.github.member || null)].filter(Boolean)
+  const merger = names.find((n) => isOnline(room, n)) || agentsFor(room, key, files[0])[0] || null
+  const reviewer = names.find((n) => n !== merger) || null
+  const tasks = room.tasks || room.doc.getMap('tasks')
+  let task = null
+  try { task = addTask(room.doc, tasks, { title: clip(`Checks fail after merging ${files.join(', ')} on ${key}`, 200), by: RELAY_BY, assignee: merger || '', forAi: false, tool: '', files }, RELAY_ORIGIN) } catch {}
+  for (const rel of files) {
+    if (state.held.some((h) => h.path === rel)) continue
+    state.held.push({ path: rel, why: 'checks', sha, base: sha, theirs: sha, parties, merger, reviewer, mode: reviewer ? 'two' : 'outside', task: task ? task.id : null, since: now, assignedAt: now, candidate: null })
+    out.push({ path: rel, held: true })
+  }
+  if (task) post(room, task.id, [`GitHub's checks failed on ${sha.slice(0, 7)}, which carried the merge of ${files.join(', ')}. ${files.length === 1 ? 'It is' : 'They are'} held (not pushed again) until a fix passes the checks, or a person accepts the failure.`, ...lines.filter((l) => files.includes(l.path)).slice(0, 10).map((l) => `- ${l.path}:${l.line} ${l.message}`), '', `Merger: ${merger || 'nobody online yet'}; reviewer: ${reviewer || 'none'}. Propose the fix with quilt_clash propose (with the checks you ran passing).`].join('\n'))
+  for (const n of names) dm(room, n, `GitHub's checks failed after the merge of ${files.join(', ')} on ${key} (task ${task ? task.id : '?'}): ${n === merger ? 'you fix it' : `${merger || 'an agent'} fixes it and you review`}.`)
+  room.saveMeta()
+  return out
+}
+
+/** For tests: who is told what when a clash has nobody to merge it. */
+export const tellClashRoles = tellRoles
+
+/**
+ * A member came back with offline edits that clash with the session's (plan §7.1; session.js
+ * openConflict): the session's version stays, theirs is kept in the mirror, and the clash goes the
+ * same way as one with GitHub (merger, reviewer, proposal, acceptance). `ours` is the returning
+ * member's text (null: they deleted it); `base` what they last had.
+ */
+export async function openOfflineClash (room, key, { who, path: rel, mergeId = null, base = null, ours = null, oursDeleted = false, binary = false }, { now = Date.now() } = {}) {
+  if (!isSafeRelPath(rel)) throw new Error('not a path in the project')
+  const state = syncStateOf(room, key)
+  const had = state.held.find((h) => h.path === rel)
+  if (had) return had
+  const dir = await mirrorDirOf(room, key)
+  const e = room.branchDoc(key)
+  const session = docKey(e, rel)
+  const h = {
+    path: rel, why: 'clash', kind: 'offline', since: now, mergeId, base: null, theirs: null,
+    binary: !!binary || (session !== null && !isText(session)),
+    baseBlob: typeof base === 'string' ? await storeBlob(dir, base) : null,
+    otherBlob: typeof ours === 'string' ? await storeBlob(dir, ours) : null,
+    otherDeleted: !!oursDeleted,
+    oursBlob: isText(session) ? await storeBlob(dir, session) : null,
+    was: fingerprint(session),
+    parties: { session: sessionParty(e, rel, { except: who.name }), github: null, offline: { name: who.name, ts: now } }
+  }
+  Object.assign(h, chooseRoles(room, key, h), { assignedAt: now, candidate: null })
+  state.held.push(h)
+  const tasks = room.tasks || room.doc.getMap('tasks')
+  const sideS = h.parties.session ? h.parties.session.name : 'the session'
+  let task = null
+  try { task = addTask(room.doc, tasks, { title: clip(`Merge ${rel} on ${key}: ${who.name} edited it offline, and ${sideS} in the session`, 200), by: RELAY_BY, assignee: h.merger || '', forAi: false, tool: '', files: [rel] }, RELAY_ORIGIN) } catch {}
+  h.task = task ? task.id : null
+  if (task) {
+    post(room, task.id, `${rel} is held on \`${key}\`: ${who.name} changed it while offline, and ${sideS} changed the same lines in the session. The session's version stays as it is; ${who.name}'s is kept. Merger: ${h.merger || 'nobody yet'}; reviewer: ${h.reviewer || 'none'}. Propose the merged file with quilt_clash propose; the reviewer accepts. Or keep one side: keep_session, keep_offline.`)
+    const b = typeof base === 'string' ? base : ''
+    if (isText(session)) post(room, task.id, `The session's change (base → session):\n\`\`\`diff\n${lineDiff(b, session, { max: MAX_COMMENT - 200 })}\n\`\`\``)
+    if (typeof ours === 'string') post(room, task.id, `${who.name}'s offline change (base → theirs):\n\`\`\`diff\n${lineDiff(b, ours, { max: MAX_COMMENT - 200 })}\n\`\`\``)
+  }
+  tellRoles(room, key, h, { fresh: true })
+  room.saveMeta()
+  room.log && room.log(`[${room.name}] ${key}: ${who.name}'s offline edits to ${rel} clash with the session's: merger ${h.merger || 'none'}, reviewer ${h.reviewer || 'none'}`)
+  return h
+}
+
+/** A merge the relay worked out word by word (merge3.js mergeSmart): suggested, never landed by itself (addendum 16.8). */
+export async function suggestCandidate (room, key, h, text, { dir, now = Date.now(), how = 'words' } = {}) {
+  const blob = await storeBlob(dir, text)
+  h.candidate = { by: RELAY_BY, at: now, fp: sha1(text), blob, checks: null, generated: how }
+  if (h.task) post(room, h.task, `The relay can merge ${h.path} ${how === 'words' ? 'word by word' : how}, but a merge like that can change what the code means, so it is only a suggestion: ${h.merger || 'the merger'} or ${h.reviewer || 'the reviewer'} accepts it with quilt_clash accept (with how the project's checks went on it), or proposes another.\n\`\`\`\n${clip(text, MAX_COMMENT - 400)}\n\`\`\``)
+  return h
+}