heyquilt 0.0.1 → 0.3.90

package/src/project-rules.js

@@ -0,0 +1,178 @@
+// The project's own rules for AI, gathered from whichever tool's files hold them, so every
+// agent reads the same thing whatever tool it runs in (quilt_project_rules, on the local and
+// hosted MCP): AGENTS.md at the root and in folders (or CLAUDE.md when there is none), the
+// Cursor rules that always apply, and the design system.
+//
+// Pure: `list` is the session's file paths, `read(path)` their text (or null).
+
+const START = '<!-- quilt:start -->'
+const END = '<!-- quilt:end -->'
+const MAX_FILE = 20000
+const MAX_TOTAL = 60000
+const SKIP = /(^|\/)(node_modules|\.git|\.quilt|dist|build|vendor)\//
+// The design system: named in AGENTS.md ("Design system: docs/brand.md"), else a usual name.
+const DESIGN_NAMES = ['DESIGN.md', 'design.md', 'DESIGN_SYSTEM.md', 'design-system.md', 'docs/DESIGN.md', 'docs/design.md', 'docs/design-system.md']
+const DESIGN_LINE = /^\s*(?:[-*]\s*)?\**design system\**\s*:\s*`?([^\s`]+\.(?:md|mdx|txt))`?/im
+
+/** A rules file without Quilt's own guide block (agents have that from Quilt already). */
+export function withoutQuiltBlock (text) {
+  const s = String(text || '')
+  const a = s.indexOf(START)
+  const b = s.indexOf(END)
+  if (a === -1 || b === -1 || b < a) return s.trim()
+  return (s.slice(0, a) + s.slice(b + END.length)).replace(/\n{3,}/g, '\n\n').trim()
+}
+
+/** A Cursor rule's front matter: { alwaysApply, globs, description } and its body. */
+export function parseCursorRule (text) {
+  const s = String(text || '')
+  const m = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(s)
+  const meta = { alwaysApply: false, globs: [], description: '' }
+  if (!m) return { meta, body: s.trim() }
+  for (const line of m[1].split(/\r?\n/)) {
+    const kv = /^(\w+)\s*:\s*(.*)$/.exec(line.trim())
+    if (!kv) continue
+    const [, k, v] = kv
+    if (k === 'alwaysApply') meta.alwaysApply = /^true$/i.test(v.trim())
+    else if (k === 'description') meta.description = v.trim().replace(/^["']|["']$/g, '')
+    else if (k === 'globs') meta.globs = v.replace(/^\[|\]$/g, '').split(',').map((g) => g.trim().replace(/^["']|["']$/g, '')).filter(Boolean)
+  }
+  return { meta, body: s.slice(m[0].length).trim() }
+}
+
+/** Whether a CLAUDE.md (or GEMINI.md) only points at AGENTS.md, with nothing of its own. */
+export const onlyPointer = (text) => withoutQuiltBlock(text).replace(/^\s*@AGENTS\.md\s*$/m, '').trim() === ''
+
+/**
+ * The rules: { files: [{ path, kind, text }], design: { path, text } | null, missing: [] }.
+ * `kind`: 'agents' (AGENTS.md), 'claude' (CLAUDE.md, when there is no AGENTS.md), 'cursor'.
+ */
+export function projectRules ({ list = [], read = () => null } = {}) {
+  const paths = [...new Set(list)].filter((p) => typeof p === 'string' && !SKIP.test(p)).sort((a, b) => depth(a) - depth(b) || a.localeCompare(b))
+  const files = []
+  let total = 0
+  const add = (path, kind, text) => {
+    const t = String(text || '').trim()
+    if (!t || total >= MAX_TOTAL) return
+    const cut = t.length > MAX_FILE ? `${t.slice(0, MAX_FILE)}\n\n… (cut: read ${path} for the rest)` : t
+    total += cut.length
+    files.push({ path, kind, text: cut })
+  }
+  const agents = paths.filter((p) => p === 'AGENTS.md' || p.endsWith('/AGENTS.md'))
+  for (const p of agents) add(p, 'agents', withoutQuiltBlock(read(p)))
+  // No AGENTS.md: a CLAUDE.md holds the rules (Claude Code's own file), at the root and in folders.
+  if (!files.length) for (const p of paths.filter((x) => x === 'CLAUDE.md' || x.endsWith('/CLAUDE.md'))) add(p, 'claude', withoutQuiltBlock(read(p)))
+  // Cursor's rules that apply everywhere; ones for some files only are named, to read when working on those.
+  const scoped = []
+  for (const p of paths.filter((x) => /^\.cursor\/rules\/.+\.mdc?$/.test(x))) {
+    const { meta, body } = parseCursorRule(read(p))
+    if (meta.alwaysApply) add(p, 'cursor', body)
+    else if (body) scoped.push({ path: p, globs: meta.globs, description: meta.description })
+  }
+  if (paths.includes('.cursorrules')) add('.cursorrules', 'cursor', read('.cursorrules'))
+  // The design system: named in the rules, else a usual file name.
+  let design = null
+  const named = files.map((f) => DESIGN_LINE.exec(f.text)?.[1]).find(Boolean)
+  const designPath = [named, ...DESIGN_NAMES].find((p) => p && paths.includes(p.replace(/^\.\//, '')))
+  if (designPath) {
+    const t = String(read(designPath.replace(/^\.\//, '')) || '').trim()
+    if (t) design = { path: designPath.replace(/^\.\//, ''), text: t.length > MAX_FILE ? `${t.slice(0, MAX_FILE)}\n\n… (cut: read ${designPath} for the rest)` : t }
+  }
+  return { files, scoped, design }
+}
+
+const depth = (p) => p.split('/').length
+
+/** The rules as one text for an agent. */
+export function renderRules (r) {
+  if (!r.files.length && !r.design && !r.scoped.length) {
+    return 'This project has no rules for AI yet (no AGENTS.md, CLAUDE.md or Cursor rules) and no design system file. Follow the code around what you change.'
+  }
+  const out = ['The project\'s rules for AI, the same for every tool. Folder AGENTS.md files apply to the files under that folder.', '']
+  for (const f of r.files) out.push(`## ${f.path}`, '', f.text, '')
+  if (r.scoped.length) {
+    out.push('## Rules for some files only (Cursor)', '')
+    for (const s of r.scoped) out.push(`- ${s.path}${s.globs.length ? ` (for ${s.globs.join(', ')})` : ''}${s.description ? `: ${s.description}` : ''}`)
+    out.push('', 'Read one with your file tools when you work on files it covers.', '')
+  }
+  if (r.design) out.push(`## Design system (${r.design.path})`, '', r.design.text, '')
+  return out.join('\n').trim()
+}
+
+// ------------------------------------------------- gathering into AGENTS.md --
+
+/** The one folder every glob of a Cursor rule is under ("src/api/**\/*.ts" → "src/api"), or null. */
+export function globFolder (globs) {
+  const dirs = (globs || []).map((g) => {
+    const parts = String(g).replace(/^\.\//, '').split('/')
+    const fixed = []
+    for (const p of parts.slice(0, -1)) { if (/[*?[{]/.test(p)) break; fixed.push(p) }
+    return fixed.join('/')
+  })
+  if (!dirs.length || dirs.some((d) => !d)) return null
+  return dirs.every((d) => d === dirs[0]) ? dirs[0] : null
+}
+
+const section = (title, body) => `## ${title}\n\n${String(body).trim()}\n`
+const joinTo = (before, parts) => [String(before || '').replace(/\s*$/, ''), ...parts.map((p) => p.trim())].filter(Boolean).join('\n\n').replace(/^\n+/, '') + '\n'
+
+/**
+ * What gathering the project's rules into AGENTS.md would change, for the person to look at
+ * before it is applied: { changes: [{ path, before, after }] (after null: the file goes),
+ * manual: [{ path, why }] }. CLAUDE.md and GEMINI.md keep only a pointer at AGENTS.md (and
+ * Quilt's guide); Cursor rules that always apply, and .cursorrules, move into AGENTS.md; a
+ * rule for files in one folder moves into that folder's AGENTS.md; anything else is listed for
+ * the person to place by hand.
+ */
+export function gatherPlan ({ list = [], read = () => null } = {}) {
+  const paths = [...new Set(list)].filter((p) => typeof p === 'string' && !SKIP.test(p)).sort()
+  const has = new Set(paths)
+  const writes = new Map() // path -> { before, parts: [] }
+  const removes = new Map() // path -> before
+  const pointers = new Map() // path -> { before, after }
+  const manual = []
+  const into = (folder, title, body) => {
+    const p = folder ? `${folder}/AGENTS.md` : 'AGENTS.md'
+    if (!writes.has(p)) writes.set(p, { before: has.has(p) ? String(read(p) ?? '') : null, parts: [] })
+    writes.get(p).parts.push(section(title, body))
+    return p
+  }
+  // A tool's own file (CLAUDE.md, GEMINI.md) at the root or in a folder: its rules go to that folder's AGENTS.md.
+  for (const p of paths.filter((x) => /(^|\/)(CLAUDE|GEMINI)\.md$/.test(x))) {
+    const before = String(read(p) ?? '')
+    const own = withoutQuiltBlock(before).replace(/^\s*@AGENTS\.md\s*$/m, '').trim()
+    if (!own) continue
+    const folder = p.includes('/') ? p.slice(0, p.lastIndexOf('/')) : ''
+    into(folder, `From ${p.split('/').pop()}`, own)
+    const block = before.match(/<!-- quilt:start -->[\s\S]*?<!-- quilt:end -->/)
+    pointers.set(p, { before, after: `@AGENTS.md\n${block ? `\n${block[0]}\n` : ''}` })
+  }
+  for (const p of paths.filter((x) => /^\.cursor\/rules\/.+\.mdc?$/.test(x))) {
+    const before = String(read(p) ?? '')
+    const { meta, body } = parseCursorRule(before)
+    if (!body) continue
+    const title = meta.description || p.split('/').pop().replace(/\.mdc?$/, '')
+    if (meta.alwaysApply) { removes.set(p, { before, to: into('', title, body) }); continue }
+    const folder = globFolder(meta.globs)
+    if (folder) { removes.set(p, { before, to: into(folder, title, body) }); continue }
+    manual.push({ path: p, why: meta.globs.length ? `it applies to ${meta.globs.join(', ')}, which isn't one folder` : 'Cursor applies it when asked for, not to a folder' })
+  }
+  if (has.has('.cursorrules')) {
+    const before = String(read('.cursorrules') ?? '')
+    if (before.trim()) removes.set('.cursorrules', { before, to: into('', 'From .cursorrules', before) })
+  }
+  const changes = []
+  for (const [p, w] of writes) changes.push({ path: p, before: w.before, after: joinTo(w.before, w.parts) })
+  for (const [p, c] of pointers) if (c.after !== c.before) changes.push({ path: p, before: c.before, after: c.after })
+  for (const [p, r] of removes) changes.push({ path: p, before: r.before, after: null, to: r.to })
+  changes.sort((a, b) => (a.path === 'AGENTS.md' ? -1 : b.path === 'AGENTS.md' ? 1 : a.path.localeCompare(b.path)))
+  return { changes, manual }
+}
+
+/** A short fingerprint of a plan, so what is applied is what was shown. */
+export function planKey (plan) {
+  let h = 0x811c9dc5
+  const s = JSON.stringify(plan.changes.map((c) => [c.path, c.before, c.after]))
+  for (let i = 0; i < s.length; i++) h = Math.imul(h ^ s.charCodeAt(i), 0x01000193)
+  return `${s.length}:${(h >>> 0).toString(36)}`
+}

package/src/protocol.js

@@ -0,0 +1,92 @@
+// Wire protocol shared by the relay server and clients.
+// Compatible with the standard y-websocket message layout.
+import * as encoding from 'lib0/encoding'
+import * as decoding from 'lib0/decoding'
+import * as syncProtocol from 'y-protocols/sync'
+import * as awarenessProtocol from 'y-protocols/awareness'
+
+export const MSG_SYNC = 0
+export const MSG_AWARENESS = 1
+export const MSG_QUERY_AWARENESS = 3
+// quilt extensions (ignored by plain y-websocket clients):
+export const MSG_AUTH = 10 // relay -> client: nonce; client -> relay: signature
+export const MSG_CLAIM = 11 // client -> relay: JSON { id, op: 'claim'|'release', pattern, note }
+export const MSG_CLAIMS = 12 // relay -> client: JSON { claims, reply?: { id, ok, error, released } }
+export const MSG_ACCESS = 13 // relay -> client: JSON { state: 'pending'|'approved', role, scopes, scopesExcept, talk, owner, controlled, refresh?, refused?, why? }
+export const MSG_ADMIN = 14 // client (owner) -> relay: JSON { id, op: 'approve'|'deny'|'set'|'remove'|'end'|'name', key, role, scopes, access?, typeId?, name }
+export const MSG_MEMBERS = 15 // relay -> client: JSON { members, sessionName, pending?, reply?: { id, ok, error } }
+export const MSG_PASS = 16 // client -> relay: JSON { pass }: a fresh session pass, sent at least every 5 minutes
+export const MSG_BRANCH = 17 // client -> relay: JSON { id, op: 'join'|'confirm'|'remove', branch, base?, adopt?, sv? }
+export const MSG_BRANCHES = 18 // relay -> client: JSON { branches, reply?: { id, op, ok, error?, branch?, created?, base? } }
+
+// Every sync message names its document: the room's (chat, tasks, the feed, commit requests,
+// activity) is '', a branch's (its files) is the branch key. Git never allows an empty branch name.
+export const ROOM_DOC = ''
+
+// What this app can do, sent when it connects. The relay turns away apps without what a session needs.
+export const FEATURES = 'large-files,branches'
+
+// WebSocket close codes the relay uses to refuse a client for good.
+export const CLOSE_AUTH_FAILED = 4401
+export const CLOSE_NAME_TAKEN = 4403
+export const CLOSE_DENIED = 4406 // the owner said no, or removed you
+
+// WebSocket close code the relay uses when a room is over its size quota.
+export const CLOSE_ROOM_FULL = 4413
+
+export const CLOSE_ENDED = 4410 // the owner ended the session and it was deleted
+
+// The connection's session pass ran out without a new one. Clients reconnect with a fresh pass.
+export const CLOSE_PASS_EXPIRED = 4419
+
+// Sent to apps too old for a session that now stores large files. It reuses
+// 4401 because every app that knows close codes stops on it and shows the
+// reason; the oldest ones reconnect instead, and the relay refuses that
+// reconnect with the same message.
+export const CLOSE_NEEDS_UPDATE = CLOSE_AUTH_FAILED
+
+// Largest file that can be sent in chat.
+export const MAX_SHARED_FILE_BYTES = 100 * 1024 * 1024
+
+export { encoding, decoding, syncProtocol, awarenessProtocol }
+
+/** An encoder with a sync message's header written: the type and the document it is for. */
+export function syncHeader (docId = ROOM_DOC) {
+  const enc = encoding.createEncoder()
+  encoding.writeVarUint(enc, MSG_SYNC)
+  encoding.writeVarString(enc, docId)
+  return enc
+}
+
+export function syncStep1Message (doc, docId = ROOM_DOC) {
+  const enc = syncHeader(docId)
+  syncProtocol.writeSyncStep1(enc, doc)
+  return encoding.toUint8Array(enc)
+}
+
+export function updateMessage (update, docId = ROOM_DOC) {
+  const enc = syncHeader(docId)
+  syncProtocol.writeUpdate(enc, update)
+  return encoding.toUint8Array(enc)
+}
+
+export function awarenessMessage (awareness, clients) {
+  const enc = encoding.createEncoder()
+  encoding.writeVarUint(enc, MSG_AWARENESS)
+  encoding.writeVarUint8Array(enc, awarenessProtocol.encodeAwarenessUpdate(awareness, clients))
+  return encoding.toUint8Array(enc)
+}
+
+export function bytesMessage (type, bytes) {
+  const enc = encoding.createEncoder()
+  encoding.writeVarUint(enc, type)
+  encoding.writeVarUint8Array(enc, bytes)
+  return encoding.toUint8Array(enc)
+}
+
+export function jsonMessage (type, value) {
+  const enc = encoding.createEncoder()
+  encoding.writeVarUint(enc, type)
+  encoding.writeVarString(enc, JSON.stringify(value))
+  return encoding.toUint8Array(enc)
+}

package/src/quiet-warnings.js

@@ -0,0 +1,9 @@
+// Node prints "SQLite is an experimental feature" the moment node:sqlite loads, which
+// Quilt does to read Cursor's chat database. The warning is known and harmless, so it is
+// kept off people's terminals; every other warning is still printed as Node would.
+const printers = process.listeners('warning')
+process.removeAllListeners('warning')
+process.on('warning', (warning) => {
+  if (warning && warning.name === 'ExperimentalWarning' && /sqlite/i.test(String(warning.message))) return
+  for (const print of printers) print.call(process, warning)
+})

package/src/relay-ai-vm.js

@@ -0,0 +1,82 @@
+// The relay wakes a person's cloud AI (routes/ai-vm.js on the API) when something waits for it
+// and it isn't connected (its machine suspends when idle): an @mention, a direct message or a
+// task for it, or for "<person>'s AI" while none of the person's AI sessions on a computer is
+// live. A room remembers each cloud AI that joined it (meta.cloudAis, keyed by its person's
+// account) with what it has been told of, so a wake is asked for once per new event, and the
+// machine's own inbox finds the event when it is back.
+import { scanInbox } from './inbox.js'
+import { readTasks } from './tasks.js'
+import { cloudReader } from './cloud-ai.js'
+
+const PERSON = /^person:[A-Za-z0-9_-]{1,64}$/
+
+/** Notes the cloud AI a pass is for in `meta.cloudAis`; returns whether anything changed. */
+export function noteCloudAi (meta, pass, name) {
+  if (!pass || pass.kind !== 'agent' || !PERSON.test(String(pass.of || '')) || typeof pass.ofName !== 'string') return false
+  meta.cloudAis ||= {}
+  const old = meta.cloudAis[pass.of]
+  const agent = `agent:${pass.sub}`
+  if (old && old.agent === agent && old.name === name && old.ofName === pass.ofName) return false
+  meta.cloudAis[pass.of] = { agent, name, ofName: pass.ofName, inbox: old && old.agent === agent ? old.inbox : null }
+  return true
+}
+
+/** Whether a connection in `room` is `account` ('agent:<id>'). */
+const connected = (room, account) => [...room.conns.keys()].some((ws) => ws.pass && `${ws.pass.kind}:${ws.pass.sub}` === account)
+
+/**
+ * Looks at `room` for each cloud AI it knows: what is new for it. Returns the cloud AIs to wake
+ * ([{ agent, room }]); `changed` says whether meta needs saving. Pure but for the room it reads.
+ */
+export function cloudAisToWake (room) {
+  const out = []
+  let changed = false
+  const list = room.meta.cloudAis || {}
+  if (!Object.keys(list).length) return { wake: out, changed }
+  const states = [...room.awareness.getStates().values()]
+  const chat = room.doc.getArray('chat').toArray()
+  const tasks = readTasks(room.doc.getMap('tasks'))
+  for (const entry of Object.values(list)) {
+    if (!entry || !entry.agent) continue
+    const reader = cloudReader({ name: entry.name, person: entry.ofName, states })
+    const messages = chat.filter((m) => m && m.id && (!m.to || m.to === entry.name || reader.aliases.includes(m.to) || m.by === entry.name))
+    const got = scanInbox({ messages, tasks, reader }, entry.inbox || null)
+    const seeded = !entry.inbox
+    entry.inbox = got.state
+    changed = true
+    if (seeded || !got.events.length) continue
+    if (!connected(room, entry.agent)) out.push({ agent: entry.agent.slice('agent:'.length), room: room.name })
+  }
+  return { wake: out, changed }
+}
+
+/**
+ * Watches rooms' chat and boards and asks the API (`apiUrl`, signed with `secret`) to wake each
+ * cloud AI something waits for. `fetch` is for tests.
+ */
+export function cloudAiWaker ({ apiUrl, secret, fetch: fetchImpl = globalThis.fetch, log = () => {} }) {
+  const watched = new WeakSet()
+  const base = String(apiUrl).replace(/\/+$/, '')
+  const ask = (w) => fetchImpl(`${base}/v1/relay/ai-vm/wake`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', authorization: `Bearer ${secret}` },
+    body: JSON.stringify(w),
+    signal: AbortSignal.timeout(30_000)
+  }).then((res) => { if (!res.ok) log(`[${w.room}] could not wake a cloud AI (${res.status})`) }, (err) => log(`[${w.room}] could not wake a cloud AI: ${err.message}`))
+
+  const check = (room) => {
+    const { wake, changed } = cloudAisToWake(room)
+    if (changed) room.saveMeta()
+    return Promise.all(wake.map(ask))
+  }
+
+  const watch = (room) => {
+    if (watched.has(room)) return
+    watched.add(room)
+    const run = () => { try { check(room) } catch (err) { log(`[${room.name}] cloud AI wake: ${err.message}`) } }
+    room.doc.getArray('chat').observe(run)
+    room.doc.getMap('tasks').observeDeep(run)
+  }
+
+  return { watch, check }
+}

package/src/relay-ask.js

@@ -0,0 +1,141 @@
+// Questions for the relay, "Quilt" in chat. Anyone in a session can @mention @Quilt (or message it directly)
+// and it answers from what it knows: how the session's branches stand against git, who is
+// connected, which branches it keeps, and (for the owner) trimming branches nobody uses. No
+// model runs here: each question is matched by its words and answered by code. Pure but for
+// `room`, which the relay passes in (server.js answerRelay).
+
+import { RELAY_BY, isRelay } from './branches.js'
+import { mentioned } from './inbox.js'
+import { RELAY_QUESTIONS, RELAY_OLD_NAMES } from './ui/chat.js'
+
+export { RELAY_QUESTIONS }
+
+/** A branch nobody has been on for this long, with nobody on it now, is unused (trim). */
+export const TRIM_IDLE_MS = 24 * 60 * 60 * 1000
+
+/** Whether chat message `m` is for the relay: sent to it directly, or @mentioning it. */
+export function asksRelay (m) {
+  if (!m || typeof m !== 'object' || typeof m.text !== 'string' || isRelay(m.by)) return false
+  if (m.to) return isRelay(m.to)
+  return mentioned(m.text, [RELAY_BY, ...RELAY_OLD_NAMES]).length > 0
+}
+
+/** Which question `text` asks (an id of RELAY_QUESTIONS), or 'help' when it is none of them. */
+export function questionOf (text) {
+  const t = String(text || '').replace(/@(the relay|quilt)\b/gi, ' ').toLowerCase()
+  if (/\b(trim|prune|clean ?up|remove)\b/.test(t)) return 'trim'
+  if (/\b(git|github|upstream|commits?|behind|synced?)\b/.test(t)) return 'git'
+  if (/\b(members?|connected|online|who|people|agents?)\b/.test(t)) return 'members'
+  if (/\bbranch(es)?\b/.test(t)) return 'branches'
+  return 'help'
+}
+
+const plural = (n, w) => `${n} ${w}${n === 1 ? '' : /(ch|sh|s|x)$/.test(w) ? 'es' : 's'}`
+
+/** "3 min ago", "2 h ago", "4 days ago". */
+export function ago (ts, now = Date.now()) {
+  const s = Math.max(0, Math.round((now - ts) / 1000))
+  if (s < 60) return 'just now'
+  if (s < 3600) return `${Math.round(s / 60)} min ago`
+  if (s < 86400) return `${Math.round(s / 3600)} h ago`
+  return plural(Math.round(s / 86400), 'day') + ' ago'
+}
+
+const list = (names) => names.length <= 2 ? names.join(' and ') : `${names.slice(0, -1).join(', ')} and ${names[names.length - 1]}`
+
+/** Who is on each branch now: Map key -> [names], from connected apps and hosted agents active now. */
+function whoIsOn (room) {
+  const on = new Map()
+  const add = (k, n) => { if (k && n && !(on.get(k) || []).includes(n)) on.set(k, [...(on.get(k) || []), n]) }
+  for (const ws of room.conns.keys()) add(ws.branch, room.names.get(ws))
+  for (const h of room.hostedOnline()) add(room.hostedBranch(h.id), h.name)
+  return on
+}
+
+function gitAnswer (room, now) {
+  const ups = room.meta.upstreams || {}
+  const lines = []
+  for (const key of Object.keys(room.meta.branches)) {
+    const r = ups[key]
+    if (!r || !r.name) continue
+    const parts = [`${key} follows ${r.name}${r.repo ? ` (${r.repo})` : ''}`]
+    if (r.sha) parts.push(`at ${r.sha.slice(0, 7)}${r.checkedAt ? `, checked ${ago(r.checkedAt, now)}` : ''}`)
+    if (r.brought && r.brought.at) parts.push(`brought in ${plural(r.brought.count || 0, 'commit')} ${ago(r.brought.at, now)}`)
+    if (r.clash && r.clash.task) parts.push(`waiting on merge task ${r.clash.task}`)
+    if (r.problem) parts.push(`problem: ${typeof r.problem === 'string' ? r.problem : r.problem.message || 'see the branch menu'}`)
+    const why = r.github && GITHUB_BLOCKED[r.github.state]
+    if (why) parts.push(`agents can't commit: ${why}`)
+    lines.push(parts.join('; '))
+  }
+  if (!lines.length) return 'No branch here follows a GitHub repository yet. It starts when a member with a git folder joins.'
+  return lines.length === 1 ? `${lines[0]}.` : `Against git:\n${lines.map((l) => `- ${l}`).join('\n')}`
+}
+
+// Why agents can't commit to a branch's repository, by its GitHub connection's state (relay-upstream.js noteConnection).
+const GITHUB_BLOCKED = {
+  'not-connected': 'nobody here has connected GitHub',
+  'not-installed': 'the Quilt app isn\'t installed on the repository',
+  'no-access': 'the connected GitHub account can\'t write to it'
+}
+
+function membersAnswer (room) {
+  const people = new Set()
+  for (const ws of room.conns.keys()) { const n = room.names.get(ws); if (n) people.add(n) }
+  for (const h of room.hostedOnline()) people.add(h.name)
+  const total = Object.keys(room.meta.members || {}).length + 1 // members, and the owner
+  const names = [...people].sort()
+  if (!names.length) return `Nobody is connected right now (${plural(total, 'member')} in the session).`
+  return `${plural(names.length, 'member')} connected of ${total}: ${list(names)}.`
+}
+
+function branchesAnswer (room, now) {
+  const on = whoIsOn(room)
+  const keys = Object.keys(room.meta.branches)
+  const lines = keys.sort((a, b) => (b === room.defaultKey) - (a === room.defaultKey) || a.localeCompare(b)).map((k) => {
+    const b = room.meta.branches[k]
+    const here = on.get(k) || []
+    const tag = k === room.defaultKey ? ' (default)' : ''
+    return `- ${k}${tag}: ${here.length ? `${list(here)} on it` : `nobody on it${b.used ? `, last used ${ago(b.used, now)}` : ''}`}`
+  })
+  return keys.length === 1 ? `1 branch tracked: ${lines[0].slice(2)}.` : `${plural(keys.length, 'branch')} tracked:\n${lines.join('\n')}`
+}
+
+/**
+ * The branches trim would remove: not the default, nobody on it or holding a file there, no
+ * hosted agent's choice, and no member on it for TRIM_IDLE_MS. A branch from before `used` was
+ * kept counts from its last `seen` (the relay's own saves move that too, so it only waits longer).
+ */
+export function unusedBranches (room, now = Date.now()) {
+  const on = whoIsOn(room)
+  const claimed = new Set(Object.values(room.meta.claims || {}).map((c) => room.branchOf(c)))
+  const chosen = new Set(Object.values(room.meta.hostedBranch || {}))
+  return Object.entries(room.meta.branches)
+    .filter(([k, b]) => k !== room.defaultKey && !on.has(k) && !claimed.has(k) && !chosen.has(k) && now - (b.used || b.seen || b.at || 0) >= TRIM_IDLE_MS)
+    .map(([k]) => k)
+}
+
+function trimAnswer (room, asker, now) {
+  if (!asker.mayTrim) return 'Only the session owner can trim branches.'
+  const gone = unusedBranches(room, now)
+  if (!gone.length) return 'Nothing to trim: every branch is in use or was used in the last day.'
+  for (const k of gone) room.removeBranch(k, { save: false })
+  room.saveMeta()
+  room.broadcastBranches()
+  room.log(`[${room.name}] ${asker.name} trimmed ${plural(gone.length, 'unused branch')}: ${gone.join(', ')}`)
+  return `Trimmed ${plural(gone.length, 'branch')} nobody used for a day: ${list(gone)}. Git keeps them, and a branch comes back when someone checks it out.`
+}
+
+const HELP = `I can answer:\n${RELAY_QUESTIONS.map((q) => `- ${q.text}${q.owner ? ' (owner only)' : ''}`).join('\n')}`
+
+/**
+ * The relay's answer to message `m`. `asker`: { name, mayTrim }. Returns the text.
+ */
+export function relayAnswer (room, m, asker, now = Date.now()) {
+  switch (questionOf(m.text)) {
+    case 'git': return gitAnswer(room, now)
+    case 'members': return membersAnswer(room)
+    case 'branches': return branchesAnswer(room, now)
+    case 'trim': return trimAnswer(room, asker, now)
+    default: return HELP
+  }
+}

package/src/relay-ci.js

@@ -0,0 +1,111 @@
+// CI on GitHub becomes work on the board: checks failing on a branch the session follows open one task,
+// "CI failing on <branch>", for the member whose commit it is (when they are in the session); a newer commit
+// failing too is noted on it; checks passing again move it to Done. One task per branch (its id comes from the
+// branch), so a run reported twice never adds a second.
+import crypto from 'node:crypto'
+import { readTasks, addTask, updateTask } from './tasks.js'
+import { addComment } from './task-comments.js'
+import { githubWriter } from './github-commit.js'
+import { credentialsFor } from './relay-commit.js'
+import { upstreamsOf, parseRepo } from './relay-upstream.js'
+import { memberForAuthor, everyone } from './relay-clash.js'
+import { runGit } from './relay-git.js'
+import { RELAY_BY } from './branches.js'
+
+const ORIGIN = 'relay-publish'
+// What GitHub calls a check suite that failed (check_suite.conclusion).
+const FAILED = new Set(['failure', 'timed_out', 'action_required', 'startup_failure'])
+
+/** The task id for CI on `branch` of this session: the same every time. */
+export const ciTaskId = (room, branch) => crypto.createHash('sha256').update(`ci\0${room.name}\0${branch}`).digest('hex').slice(0, 16)
+
+/** Who made commit `sha` (from the relay's mirror): the member it maps to, or ''. */
+async function authorOf (room, rec, sha) {
+  if (!room.mirrors) return ''
+  try {
+    const repo = parseRepo(`https://${rec.repo}`)
+    const dir = (await room.mirrors.ensure(repo, { url: room.gitRemoteUrl(repo) })).dir
+    const r = await runGit(dir, ['log', '-1', '--format=%an%x1f%ae', sha])
+    if (!r.ok) return ''
+    const [name, email] = r.out.trim().split('\x1f')
+    // By their noreply address, else by name: a member on record, or one connected now.
+    const online = room.names ? [...room.names.values()] : []
+    return memberForAuthor(room, { name, email }) || everyone(room).find((m) => m.name === name)?.name || online.find((n) => n === name) || ''
+  } catch { return '' }
+}
+
+/**
+ * A check suite on `repo` finished at commit `sha` of `branch` with `conclusion`. When the session follows that
+ * branch: failing opens (or reopens, or notes) its CI task; passing moves an open one to Done. Returns what it did
+ * ('opened', 'noted', 'closed') or null. Never throws.
+ */
+export function noteCiResult (room, result, opts = {}) {
+  // One at a time per branch, in the order GitHub's results arrive: a failure takes longer to note (GitHub is asked
+  // which checks failed), and a pass right after it must not be noted first.
+  if (!room.ciQueue) room.ciQueue = new Map()
+  const k = String(result && result.branch)
+  const next = (room.ciQueue.get(k) || Promise.resolve()).then(() => noteCiResultNow(room, result, opts))
+  room.ciQueue.set(k, next.catch(() => null))
+  return next
+}
+
+/** Whether commit `older` is an ancestor of `newer` in the relay's mirror of `rec`'s repository (false when it can't say). */
+async function before (room, rec, older, newer) {
+  try {
+    const repo = parseRepo(`https://${rec.repo}`)
+    const dir = (await room.mirrors.ensure(repo, { url: room.gitRemoteUrl(repo) })).dir
+    return (await runGit(dir, ['merge-base', '--is-ancestor', older, newer])).ok
+  } catch { return false }
+}
+
+async function noteCiResultNow (room, { repo, sha, branch, conclusion }, { fetch = globalThis.fetch, log = () => {} } = {}) {
+  try {
+    const want = String(repo).toLowerCase().replace(/^github\.com\//, '')
+    const rec = Object.values(upstreamsOf(room)).find((r) => r && r.repo && r.ref === branch && String(r.repo).toLowerCase().replace(/^github\.com\//, '') === want)
+    if (!rec || !/^[0-9a-f]{40}$/.test(sha || '')) return null
+    const failed = FAILED.has(String(conclusion))
+    if (!failed && conclusion !== 'success') return null
+    // A failure on an older commit than one that passed since (GitHub's results can come out of order) is old news.
+    if (!room.ciPassed) room.ciPassed = new Map()
+    const passed = room.ciPassed.get(branch)
+    if (!failed) room.ciPassed.set(branch, sha)
+    else if (passed && passed !== sha && room.mirrors && await before(room, rec, sha, passed)) return null
+    const map = room.doc.getMap('tasks')
+    const id = ciTaskId(room, branch)
+    const task = readTasks(map).find((t) => t.id === id)
+    const open = task && !task.archived && task.column !== 'done'
+    const comment = (text) => addComment(room.doc, room.doc.getMap('taskComments'), readTasks(map), { taskId: id, by: RELAY_BY, text }, ORIGIN)
+    if (!failed) {
+      if (!open) return null
+      comment(`CI passes again on ${branch} at ${sha.slice(0, 7)}.`)
+      updateTask(room.doc, map, { id, column: 'done' }, ORIGIN)
+      return 'closed'
+    }
+    // Which checks failed, when GitHub says (a failing suite is enough to act on).
+    let names = []
+    try {
+      const r = parseRepo(`https://${rec.repo}`)
+      const c = await githubWriter({ fetch, token: await credentialsFor(room, r), owner: r.owner, name: r.name }).checks(sha)
+      names = c.failing || []
+    } catch (err) { log(`[${room.name}] ${branch}: could not read which checks failed on ${sha.slice(0, 7)}: ${err.message}`) }
+    const what = names.length ? names.slice(0, 5).join(', ') : 'checks'
+    // The relay shut down while GitHub was asked: the room notes it when it is back (server.js runCi).
+    if (room.destroyed) return null
+    const url = `https://${rec.repo}/commit/${sha}`
+    if (open) {
+      comment(`Still failing at ${sha.slice(0, 7)}: ${what}. ${url}`)
+      return 'noted'
+    }
+    const who = await authorOf(room, rec, sha)
+    if (room.destroyed) return null
+    const title = `CI failing on ${branch}: ${what}`
+    if (task) updateTask(room.doc, map, { id, title, column: 'todo', archived: false, ...(who ? { assignee: who } : {}) }, ORIGIN)
+    else addTask(room.doc, map, { id, title, by: RELAY_BY, assignee: who, column: 'todo' }, ORIGIN)
+    comment(`GitHub's checks failed on ${branch} at ${sha.slice(0, 7)}: ${what}. ${url}${who ? ` The commit is ${who}'s.` : ''}`)
+    log(`[${room.name}] ${branch}: CI failing at ${sha.slice(0, 7)} (${what}): task ${id}${who ? ` for ${who}` : ''}`)
+    return 'opened'
+  } catch (err) {
+    log(`[${room.name}] ${branch}: could not note CI on ${String(sha).slice(0, 7)}: ${err.message}`)
+    return null
+  }
+}