heyquilt 0.0.1 → 0.3.90

package/src/branchdocs.js

@@ -0,0 +1,235 @@
+// The relay's branch documents: one Yjs document per branch a room's members
+// work on, holding that branch's files (files, blobs, fileKeys) and what goes
+// with them (merge records, the chronology, per-person tallies). The room's own
+// document keeps everything room-wide. A branch document is loaded when someone
+// joins it (or a hosted agent uses it), saved a second after each change, and
+// unloaded once nobody has been on it for a while.
+import fs from 'node:fs'
+import path from 'node:path'
+import * as Y from 'yjs'
+
+// A folder without git syncs this key: the room's default branch (see Room.resolveKey).
+export const DEFAULT_KEY = '∅'
+export const MAX_BRANCH_KEY = 200
+// Branch documents a room may have at once (an empty one still costs a meta entry, a
+// broadcast to everyone on every create, and a loaded Y.Doc): refused in plain English past this.
+export const MAX_BRANCHES = 50
+export const BRANCH_IDLE_MS = 10 * 60 * 1000
+// A branch nobody has been on this long leaves the session (never the default branch).
+export const BRANCH_TTL_MS = 30 * 24 * 60 * 60 * 1000
+// A detached checkout (key starting with '@') nobody has been on this long leaves the session:
+// it has no branch name to come back to, so there's no reason to keep it around as long as a
+// real branch.
+export const DETACHED_TTL_MS = 24 * 60 * 60 * 1000
+// What a room's document keeps for everyone, whatever branch they're on. The rest is a branch's
+// (files, blobs, fileKeys; and merges, history, changes, which stay behind in whichever document
+// they were already in, since this list is only what moves out into the room document).
+export const ROOM_TYPES = [['chat', 'array'], ['agentFeed', 'array'], ['activity', 'array'], ['commitRequests', 'map'], ['tasks', 'map'], ['taskComments', 'map'], ['published', 'map']]
+
+// eslint-disable-next-line no-control-regex
+const NOT_IN_REFS = /[\u0000- \u007f~^:?*[\\]/
+
+/**
+ * Whether `key` may name a branch document: a git branch name (the rules of
+ * `git check-ref-format --branch`, checked here since the relay has no git),
+ * a detached commit (@ and 12 hex digits), or ∅.
+ */
+export function validBranchKey (key) {
+  if (typeof key !== 'string' || !key || key.length > MAX_BRANCH_KEY) return false
+  if (key === DEFAULT_KEY || /^@[0-9a-f]{12}$/.test(key)) return true
+  if (key === 'HEAD' || key === '@' || key.startsWith('-') || NOT_IN_REFS.test(key)) return false
+  if (key.includes('..') || key.includes('@{') || key.includes('//')) return false
+  if (key.startsWith('/') || key.endsWith('/') || key.endsWith('.')) return false
+  return key.split('/').every((part) => part && !part.startsWith('.') && !part.endsWith('.lock'))
+}
+
+/** A branch document's file name: the key in base64url (branch names have slashes, and ∅). */
+export const branchFileName = (key) => `${Buffer.from(key, 'utf8').toString('base64url')}.ydoc`
+
+/** Whether a document whose state vector is `have` holds everything one at `want` holds. */
+export function covers (have, want) {
+  const h = Y.decodeStateVector(have)
+  for (const [client, clock] of Y.decodeStateVector(want)) if ((h.get(client) || 0) < clock) return false
+  return true
+}
+
+/**
+ * A room saved before branch documents kept everything in one document. Its
+ * room-wide parts are copied into a new room document (returned) and emptied
+ * in the old one, which stays as it is otherwise: it becomes the default
+ * branch's document, so every app's saved copy of it still matches.
+ */
+export function splitLegacyDoc (legacy) {
+  const room = new Y.Doc()
+  room.transact(() => {
+    for (const [name, kind] of ROOM_TYPES) {
+      if (kind === 'array') room.getArray(name).push(legacy.getArray(name).toJSON())
+      else for (const [k, v] of Object.entries(legacy.getMap(name).toJSON())) room.getMap(name).set(k, v)
+    }
+  })
+  legacy.transact(() => {
+    for (const [name, kind] of ROOM_TYPES) {
+      if (kind === 'array') { const a = legacy.getArray(name); if (a.length) a.delete(0, a.length) } else {
+        const m = legacy.getMap(name)
+        for (const k of [...m.keys()]) m.delete(k)
+      }
+    }
+  })
+  return room
+}
+
+export class BranchStore {
+  /**
+   * @param {object} o
+   * @param {string|null} o.dir  where this room's branch documents are saved (null: memory only)
+   * @param {number} [o.idleMs]  a document nobody is on is unloaded this long after its last use
+   * @param {(entry: object) => void} o.onLoad  wires a document just loaded (listeners, the guard)
+   * @param {(entry: object) => void} [o.onSave]  after each save
+   * @param {(err: Error) => void} [o.onDiskError]  a save failed
+   */
+  constructor ({ dir, idleMs = BRANCH_IDLE_MS, onLoad, onSave = () => {}, onDiskError = () => {} }) {
+    this.dir = dir || null
+    this.idleMs = idleMs
+    this.onLoad = onLoad
+    this.onSave = onSave
+    this.onDiskError = onDiskError
+    this.loaded = new Map() // key -> { key, doc, files, blobs, fileKeys, conns, bytes, saveTimer, unloadTimer }
+    this.sizes = new Map() // key -> bytes on disk, for the room's size limit
+  }
+
+  file (key) { return this.dir ? path.join(this.dir, branchFileName(key)) : null }
+
+  /** Whether branch `key` has a saved document. */
+  stored (key) { return !!this.dir && fs.existsSync(this.file(key)) }
+
+  /** The loaded entry for `key`, or null (never loads). */
+  get (key) { return this.loaded.get(key) || null }
+
+  /** Bytes branch `key` takes: its loaded size, or its file's. */
+  size (key) {
+    const e = this.loaded.get(key)
+    if (e) return e.bytes
+    if (!this.sizes.has(key)) {
+      let n = 0
+      try { n = fs.statSync(this.file(key)).size } catch {}
+      this.sizes.set(key, n)
+    }
+    return this.sizes.get(key)
+  }
+
+  /** Branch `key`'s entry, its document loaded from disk (or new and empty). Throws { unreadable } when its file can't be read. */
+  load (key) {
+    let e = this.loaded.get(key)
+    if (e) { this.touch(e); return e }
+    const doc = new Y.Doc()
+    let bytes = 0
+    if (this.stored(key)) {
+      try {
+        const buf = fs.readFileSync(this.file(key))
+        Y.applyUpdate(doc, buf)
+        bytes = buf.length
+      } catch (err) {
+        doc.destroy()
+        throw Object.assign(new Error(`could not read branch ${key}: ${err.message}`), { unreadable: true })
+      }
+    }
+    e = { key, doc, files: doc.getMap('files'), blobs: doc.getMap('blobs'), fileKeys: doc.getMap('fileKeys'), relayKeys: doc.getMap('relayKeys'), modes: doc.getMap('modes'), conns: new Set(), bytes, saveTimer: null, unloadTimer: null }
+    this.loaded.set(key, e)
+    this.onLoad(e)
+    this.touch(e)
+    return e
+  }
+
+  subscribe (ws, key) {
+    const e = this.load(key)
+    e.conns.add(ws)
+    this.touch(e)
+    return e
+  }
+
+  unsubscribe (ws, key) {
+    const e = this.loaded.get(key)
+    if (!e) return
+    e.conns.delete(ws)
+    this.touch(e)
+  }
+
+  /** Used just now: a document nobody is on is unloaded idleMs from now (only one that can be saved). */
+  touch (e) {
+    clearTimeout(e.unloadTimer)
+    e.unloadTimer = null
+    if (e.conns.size || !this.dir) return
+    e.unloadTimer = setTimeout(() => this.unload(e.key), this.idleMs)
+    e.unloadTimer.unref?.()
+  }
+
+  unload (key) {
+    const e = this.loaded.get(key)
+    if (!e || e.conns.size) return
+    if (this.save(e)) this.drop(e)
+  }
+
+  drop (e) {
+    clearTimeout(e.saveTimer)
+    clearTimeout(e.unloadTimer)
+    if (e.guard) e.guard.destroy()
+    e.doc.destroy()
+    this.loaded.delete(e.key)
+  }
+
+  scheduleSave (e) {
+    if (!this.dir || e.saveTimer) return
+    e.saveTimer = setTimeout(() => this.save(e), 1000)
+  }
+
+  /** Saves a loaded document now; false when the disk refused (it then stays loaded). */
+  save (e) {
+    clearTimeout(e.saveTimer)
+    e.saveTimer = null
+    if (!this.dir || this.frozen) return true // frozen: a crash injected in a test (relay-sync.js crashPoint)
+    const state = Y.encodeStateAsUpdate(e.doc)
+    if (!this.write(e.key, state)) return false
+    e.bytes = state.length
+    this.onSave(e)
+    return true
+  }
+
+  /** Writes a branch document's state whole, then renames it: a crash leaves the old file, never a cut-off one. */
+  write (key, state) {
+    try {
+      fs.mkdirSync(this.dir, { recursive: true })
+      const f = this.file(key)
+      fs.writeFileSync(f + '.tmp', state)
+      fs.renameSync(f + '.tmp', f)
+      this.sizes.set(key, state.length)
+      return true
+    } catch (err) {
+      this.onDiskError(err)
+      return false
+    }
+  }
+
+  /** Branch `from` is called `to` from now on (∅ taken by the session's first real branch). */
+  rename (from, to) {
+    const e = this.loaded.get(from)
+    if (e) { this.loaded.delete(from); e.key = to; this.loaded.set(to, e) }
+    if (this.stored(from)) {
+      try { fs.renameSync(this.file(from), this.file(to)) } catch (err) { this.onDiskError(err) }
+    }
+    if (this.sizes.has(from)) { this.sizes.set(to, this.sizes.get(from)); this.sizes.delete(from) }
+  }
+
+  /** Deletes branch `key`'s document, loaded or not. */
+  remove (key) {
+    const e = this.loaded.get(key)
+    if (e) this.drop(e)
+    if (this.dir) fs.rmSync(this.file(key), { force: true })
+    this.sizes.delete(key)
+  }
+
+  /** Saves and drops every loaded document (the room is leaving memory). */
+  destroy () { for (const e of [...this.loaded.values()]) { this.save(e); this.drop(e) } }
+
+  /** Drops every loaded document without saving (the room was ended and its data deleted). */
+  discard () { for (const e of [...this.loaded.values()]) this.drop(e) }
+}

package/src/branches.js

@@ -0,0 +1,194 @@
+// The session's branches: which branch each member's folder is on, how it
+// stands against its upstream, and every branch and worktree of the
+// repository with who last worked on it. Each folder tells the room about its
+// own git (Session.gitSummary, in presence); this folds those into one list.
+// Pure: Session.status() and the hosted relay both call it.
+
+import { RELAY_NAME, isRelay } from './ui/chat.js'
+
+// Who the relay is in chat, the activity log, the chronology and the branch list: what it posts
+// itself, the commits it brings in for a branch no folder is online on (relay-upstream.js), and
+// the questions it answers (relay-ask.js).
+export const RELAY_BY = RELAY_NAME
+
+export { isRelay }
+
+const str = (v, n) => typeof v === 'string' ? v.slice(0, n) : null
+const num = (v) => Number.isFinite(v) && v >= 0 ? Math.floor(v) : 0
+
+/** A member's git summary as it came over presence (anyone's to write), trimmed to its shape. */
+export function cleanGit (g) {
+  if (!g || typeof g !== 'object') return null
+  const u = g.upstream && typeof g.upstream === 'object' ? g.upstream : null
+  const r = g.repo && typeof g.repo === 'object' ? g.repo : null
+  return {
+    branch: str(g.branch, 200),
+    key: str(g.key, 200),
+    on: str(g.on, 200),
+    held: str(g.held, 20),
+    upstream: u ? { name: str(u.name, 200), url: str(u.url, 500), behind: num(u.behind), ahead: num(u.ahead), diverged: !!u.diverged, conflicts: num(u.conflicts), waiting: str(u.waiting, 300), mergedBy: str(u.mergedBy, 120), clashTask: typeof u.clashTask === 'string' && /^[0-9a-f]{16}$/.test(u.clashTask) ? u.clashTask : null, ...(u.fetchOk === false ? { fetchOk: false, fetchError: str(u.fetchError, 200) || 'git fetch failed' } : {}) } : null,
+    repo: r ? {
+      worktrees: (Array.isArray(r.worktrees) ? r.worktrees : []).slice(0, 50).map((w) => ({ name: str(w && w.name, 200), branch: str(w && w.branch, 200) })),
+      branches: (Array.isArray(r.branches) ? r.branches : []).slice(0, 30).map((b) => ({
+        name: str(b && b.name, 200), upstream: str(b && b.upstream, 200), ahead: num(b && b.ahead), behind: num(b && b.behind),
+        author: str(b && b.author, 100), ts: num(b && b.ts), subject: str(b && b.subject, 200)
+      })).filter((b) => b.name)
+    } : null
+  }
+}
+
+/**
+ * One entry per branch: { name, folders: [{ name, held }] (members whose folder is on it),
+ * ais: [names] (AI sessions named after it), worktrees: [names], hosted: [names] (hosted agents
+ * working on it, from the room's branch list), upstream: { name, url,
+ * behind, ahead, diverged, conflicts, waiting } | null, last: { author, ts, subject } | null,
+ * session: true when the branch has a live document in this session (a copy, whether or not
+ * anyone is on it right now), default: true for the room's default branch, full: true when its
+ * document is over the session's size limit (it takes no new changes), relay: what the relay
+ * brought in itself while no folder was on it, and when it last looked (relayLine) | null }.
+ * Branches someone is on come first, then the rest by last commit. `members`: [{ name, git, persona? }].
+ * `sessionBranches`: the room's own branch list (Session.branchList / the relay's), [{ key, default, full }].
+ */
+export function branchBoard (members, sessionBranches = []) {
+  const byName = new Map()
+  const entry = (name) => {
+    if (!byName.has(name)) byName.set(name, { name, folders: [], ais: [], worktrees: [], hosted: [], upstream: null, last: null, session: false, default: false, full: false, relay: null, onGitHub: false, merged: null })
+    return byName.get(name)
+  }
+  for (const m of members) {
+    const g = m.git
+    if (!g) continue
+    if (g.branch || g.key) {
+      const e = entry(g.on || g.key || g.branch)
+      e.folders.push({ name: m.name, held: g.held === 'switching' ? null : g.held, upstream: g.upstream })
+      // The folder that sees the most: one whose fetch works over one whose doesn't, then the least behind.
+      const better = (a, b) => !b || ((a.fetchOk === false) !== (b.fetchOk === false) ? b.fetchOk === false : a.behind < b.behind)
+      if (g.upstream && better(g.upstream, e.upstream)) e.upstream = g.upstream
+    }
+    if (!g.repo) continue
+    for (const b of g.repo.branches) {
+      const e = entry(b.name)
+      if (!e.last || b.ts > e.last.ts) e.last = { author: b.author, ts: b.ts, subject: b.subject }
+      if (!e.upstream && b.upstream) e.upstream = { name: b.upstream, url: null, behind: b.behind, ahead: b.ahead, diverged: b.ahead > 0 && b.behind > 0, conflicts: 0, waiting: null }
+    }
+    for (const w of g.repo.worktrees) if (w.branch && w.name !== '.' && !entry(w.branch).worktrees.includes(w.name)) entry(w.branch).worktrees.push(w.name)
+  }
+  // An AI session is named after its work, its git branch when it has one (persona.js).
+  for (const m of members) {
+    if (!m.persona) continue
+    const label = m.name.includes(' · ') ? m.name.slice(m.name.indexOf(' · ') + 3) : null
+    if (label && byName.has(label)) byName.get(label).ais.push(m.name)
+  }
+  // Every branch with a live copy in the session, whether or not anyone is on it right now
+  // (it still appears here), and which one is the room's default.
+  for (const b of (Array.isArray(sessionBranches) ? sessionBranches : [])) {
+    if (!b || typeof b.key !== 'string') continue
+    const e = entry(b.key)
+    if (b.onGitHub) { e.onGitHub = true; continue }
+    e.session = true
+    if (b.merged) e.merged = b.merged
+    if (b.default) e.default = true
+    if (b.full) e.full = true
+    if (b.relay && typeof b.relay === 'object') e.relay = b.relay
+    for (const n of (Array.isArray(b.hosted) ? b.hosted : [])) if (!e.hosted.includes(n)) e.hosted.push(n)
+  }
+  const active = (e) => e.folders.length + e.ais.length + e.worktrees.length + e.hosted.length
+  return [...byName.values()].sort((a, b) => (active(b) > 0) - (active(a) > 0) || (b.last?.ts || 0) - (a.last?.ts || 0) || (a.name < b.name ? -1 : 1))
+}
+
+const ago = (ts, now) => {
+  const s = Math.max(0, Math.round((now - ts) / 1000))
+  if (s < 90) return 'just now'
+  if (s < 5400) return `${Math.round(s / 60)}m ago`
+  if (s < 129600) return `${Math.round(s / 3600)}h ago`
+  return `${Math.round(s / 86400)}d ago`
+}
+
+/** One line on how a branch stands against its upstream, or ''. */
+export function upstreamLine (u) {
+  if (!u || !u.name) return ''
+  // A fetch that failed: what git last knew is stale, so never "up to date".
+  if (u.fetchOk === false) return `can't fetch ${u.name}: ${u.fetchError || 'git fetch failed'}${u.behind ? ` (${u.behind} behind at the last fetch that worked)` : ''}`
+  // A clash is handed to one AI as a task (clash.js): who, when it is.
+  const by = u.mergedBy ? `; being merged by ${u.mergedBy}${u.clashTask ? ` (task ${u.clashTask})` : ''}` : ''
+  if (u.diverged) return `diverged from ${u.name} (${u.ahead} ahead, ${u.behind} behind)${by}`
+  const n = Array.isArray(u.conflicts) ? u.conflicts.length : u.conflicts
+  if (n) return `${u.behind} behind ${u.name}; ${n} file${n === 1 ? '' : 's'} clash with the session's work${by}`
+  if (u.waiting) return `${u.behind} behind ${u.name}; waiting: ${u.waiting}`
+  if (u.behind) return `${u.behind} behind ${u.name}`
+  if (u.ahead) return `${u.ahead} ahead of ${u.name}`
+  return `up to date with ${u.name}`
+}
+
+/**
+ * One line on what the relay does for a branch no folder is online on: brought in by the relay
+ * (when, how many commits), a clash it handed out, why it can't, and when it last looked; or ''.
+ */
+export function relayLine (r, now = Date.now()) {
+  if (!r || !(r.checkedAt || (r.brought && r.brought.at))) return ''
+  const up = r.upstream || 'its upstream'
+  const bits = []
+  if (r.brought && r.brought.at) bits.push(`brought in by the relay ${ago(r.brought.at, now)} (${r.brought.count} commit${r.brought.count === 1 ? '' : 's'} from ${up}, ${r.brought.files} file${r.brought.files === 1 ? '' : 's'})`)
+  if (r.clashTask) bits.push(`the relay handed a clash with ${up} to task ${r.clashTask}`)
+  if (r.problem) bits.push(r.problem)
+  if (r.checkedAt) bits.push(`the relay last checked ${up} ${ago(r.checkedAt, now)}`)
+  return bits.join('; ')
+}
+
+/** The board as markdown for an AI (quilt_status, quilt_branches). `mine`: the caller's own branch, marked "(yours)". */
+export function branchesMarkdown (board, { now = Date.now(), limit = 12, mine = null } = {}) {
+  if (!board.length) return '_No git branches: the folders in this session are not git repositories._'
+  const out = []
+  for (const b of board.slice(0, limit)) {
+    const who = [
+      ...b.folders.map((f) => `${f.name}'s folder${f.held ? ` (${f.held})` : ''}${f.upstream && (f.upstream.conflicts || f.upstream.diverged || f.upstream.fetchOk === false) ? ` (${upstreamLine(f.upstream)})` : ''}`),
+      ...b.ais.map((n) => `AI session ${n}`),
+      ...b.hosted.map((n) => `hosted agent ${n}`),
+      ...b.worktrees.map((w) => `worktree \`${w}\``)
+    ]
+    const line = upstreamLine(b.upstream)
+    const bits = [
+      b.default ? 'default' : '',
+      b.session ? 'in the session' : b.onGitHub ? 'on GitHub, not in the session yet (quilt_git_branch with create: true opens it)' : '',
+      b.merged ? `merged into ${b.merged.into}${b.merged.number ? ` (pull request #${b.merged.number})` : ''}` : '',
+      who.length ? `on it: ${who.join(', ')}` : '',
+      who.some((w) => w.includes(`(${line})`)) ? '' : line,
+      relayLine(b.relay, now),
+      b.last ? `last commit ${ago(b.last.ts, now)} by ${b.last.author}: ${b.last.subject}` : ''
+    ].filter(Boolean)
+    out.push(`- \`${b.name}\`${b.name === mine ? ' (yours)' : ''}${bits.length ? ` · ${bits.join(' · ')}` : ''}`)
+  }
+  if (board.length > limit) out.push(`- …and ${board.length - limit} more`)
+  return out.join('\n')
+}
+
+/** What the relay said when asked to look at GitHub now (Room.syncUpstreamNow), for an AI; '' when it wasn't asked. */
+export function describeRelaySync (r, branch = '') {
+  if (!r) return ''
+  if (r.error) return `The relay couldn't be asked to look at GitHub for \`${branch}\` (${r.error}).`
+  return r.said || ''
+}
+
+/** What quilt_sync_branch did, for the AI that asked. */
+export function describeBranchSync (r) {
+  if (!r || !r.git) {
+    const relay = r && r.relay && !r.relay.error && r.relay.state !== 'unknown-repo' ? describeRelaySync(r.relay) : ''
+    return `This folder is not a git repository, so it can't bring commits in itself: clone the repository into this folder (\`git clone <url> .\`, with credentials that work without a prompt) and join again from there.${relay ? `\n\nMeanwhile the relay brings commits in for this branch from GitHub: ${relay}` : ' Until then, the relay brings commits in for this branch from GitHub once a member\'s folder on it has told it which repository the branch follows.'}`
+  }
+  if (!r.branch) return 'This folder is not on a branch (detached HEAD): check out a branch first.'
+  if (r.busy) return `Not now: ${r.busy === 'switching' ? 'this folder is moving to the branch you checked out' : r.busy === 'busy' || r.busy === 'settling' ? 'git is at work in this folder' : r.busy}. Quilt looks again by itself in a minute.`
+  const u = r.upstream
+  if (!u || !u.name) return `\`${r.branch}\` has no upstream (git branch --set-upstream-to sets one), so there is nothing to bring in.`
+  if (u.fetchOk === false) {
+    const relay = describeRelaySync(r.relay, r.branch)
+    return `Couldn't fetch ${u.name}: ${u.fetchError || 'git fetch failed'}. Nothing new could be looked for through this folder, so \`${r.branch}\` may be behind ${u.name}. Give git in this folder credentials that work without a prompt (a credential helper, an SSH key, or a token in the remote's URL) and call quilt_sync_branch again.${relay ? `\n\nThe relay brings commits in for \`${r.branch}\` from GitHub while no folder on it can: ${relay}` : ''}`
+  }
+  if (r.moved) {
+    const b = u.brought
+    return `Brought ${b && b.count ? `${b.count} commit${b.count === 1 ? '' : 's'}` : 'the new commits'} from ${u.name} into the session (${b ? b.files : 0} file${b && b.files === 1 ? '' : 's'}), merged with its uncommitted work. \`${r.branch}\` is up to date.`
+  }
+  if (u.conflicts && u.conflicts.length) {
+    return `Nothing brought in: ${u.behind} commit${u.behind === 1 ? '' : 's'} on ${u.name} clash with the session's uncommitted work in:\n${u.conflicts.map((c) => `- ${c.path}: ${c.why}`).join('\n')}\n${u.mergedBy && !u.clashMine ? `${u.mergedBy} is merging them (task ${u.clashTask}): leave those files to them.` : `Run git pull in this folder and resolve those; the session takes in the result.${u.clashTask ? ` This merge is yours: task ${u.clashTask} on the board.` : ''}`}`
+  }
+  return `\`${r.branch}\`: ${upstreamLine(u)}.${u.diverged ? ' Quilt never merges git history: pull or rebase it yourself, and the session takes in whatever that changes.' : ''}`
+}

package/src/catchup.js

@@ -0,0 +1,111 @@
+// "While you were away": what the session did between this folder's last stop
+// and its rejoin. Built from the shared history (history.js) by comparing the
+// entries the saved doc already had with the ones the relay brought, so it
+// needs no clocks to agree and nothing new on the relay. Shown in the app and
+// in every tool's quilt_status until the person dismisses it.
+
+/** id -> ts of every history entry the doc has now (a folded entry keeps its id but moves its ts). */
+export function historyMarks (entries) {
+  const marks = new Map()
+  for (const e of entries || []) if (e && e.id) marks.set(e.id, e.ts)
+  return marks
+}
+
+/**
+ * The changes others made that `marks` (taken before syncing) hadn't seen,
+ * grouped by person, newest first. `partial`: the history was trimmed past
+ * where we left off, so older changes may be missing from the list.
+ */
+export function awayChanges (entries, marks, me) {
+  const list = (entries || []).filter((e) => e && e.id && e.path && (!marks.has(e.id) || marks.get(e.id) !== e.ts))
+  const people = new Map()
+  for (const e of list) {
+    if (e.by === me) continue
+    const p = people.get(e.by) || { name: e.by, added: 0, removed: 0, ts: 0, files: new Map() }
+    // A folded entry we had seen as "created" was already there for us: it's an edit now.
+    const kind = e.kind === 'created' && marks.has(e.id) ? 'edited' : e.kind
+    const f = p.files.get(e.path) || { path: e.path, kind, added: 0, removed: 0, ts: 0 }
+    // Created then edited is still new; deleted last is gone.
+    if (kind === 'deleted') f.kind = 'deleted'
+    else if (f.kind === 'deleted' || (f.kind !== 'created' && kind === 'created')) f.kind = kind
+    f.added += e.added || 0; f.removed += e.removed || 0; f.ts = Math.max(f.ts, e.ts || 0)
+    if (e.pulled) f.pulled = true
+    p.added += e.added || 0; p.removed += e.removed || 0; p.ts = Math.max(p.ts, e.ts || 0)
+    p.files.set(e.path, f)
+    people.set(e.by, p)
+  }
+  const newest = (a, b) => b.ts - a.ts
+  const out = [...people.values()].map((p) => ({ ...p, files: [...p.files.values()].sort(newest) })).sort(newest)
+  const partial = marks.size > 0 && entries.length > 0 && !entries.some((e) => e && marks.has(e.id))
+  return { people: out, partial }
+}
+
+/**
+ * Folds a new catch-up into one not yet dismissed (the person left and came
+ * back again before reading it): changes add up, notes are kept once.
+ */
+export function mergeCatchUp (prev, next) {
+  if (!prev) return next
+  const people = new Map(prev.people.map((p) => [p.name, { ...p, files: new Map(p.files.map((f) => [f.path, { ...f }])) }]))
+  for (const p of next.people) {
+    const q = people.get(p.name) || { name: p.name, added: 0, removed: 0, ts: 0, files: new Map() }
+    q.fileCount = Math.max(q.fileCount || 0, p.fileCount || 0)
+    q.added += p.added; q.removed += p.removed; q.ts = Math.max(q.ts, p.ts)
+    for (const f of p.files) {
+      const g = q.files.get(f.path)
+      if (!g) { q.files.set(f.path, { ...f }); continue }
+      g.added += f.added; g.removed += f.removed; g.ts = Math.max(g.ts, f.ts)
+      g.kind = f.kind === 'deleted' ? 'deleted' : g.kind === 'created' && f.kind !== 'deleted' ? 'created' : f.kind
+      if (f.pulled) g.pulled = true
+    }
+    people.set(p.name, q)
+  }
+  const newest = (a, b) => b.ts - a.ts
+  const uniq = (xs, key) => [...new Map(xs.map((x) => [key(x), x])).values()]
+  return {
+    ...next,
+    since: prev.since ?? next.since,
+    first: prev.first || next.first,
+    pulled: (prev.pulled || 0) + (next.pulled || 0),
+    partial: prev.partial || next.partial,
+    people: [...people.values()].map((p) => ({ ...p, fileCount: Math.max(p.fileCount || 0, p.files.size), files: [...p.files.values()].sort(newest) })).sort(newest),
+    backups: uniq([...(prev.backups || []), ...(next.backups || [])], (b) => b.copy),
+    mine: {
+      shared: (prev.mine?.shared || 0) + (next.mine?.shared || 0),
+      merged: uniq([...(prev.mine?.merged || []), ...(next.mine?.merged || [])], (p) => p),
+      conflicts: uniq([...(prev.mine?.conflicts || []), ...(next.mine?.conflicts || [])], (p) => p)
+    }
+  }
+}
+
+/** True when there's nothing worth showing. */
+export function emptyCatchUp (c) {
+  return !c || (!c.people.length && !c.pulled && !(c.backups || []).length && !c.mine?.shared && !(c.mine?.merged || []).length && !(c.mine?.conflicts || []).length)
+}
+
+const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`
+const kindWord = (k) => k === 'created' ? 'new' : k === 'deleted' ? 'deleted' : null
+
+/** The catch-up as Markdown lines, for quilt_status / STATUS.md / `quilt status`. */
+export function catchUpMarkdown (c, { ago = () => '' } = {}) {
+  if (emptyCatchUp(c)) return []
+  const out = [`## While you were away${c.since ? ` (you left ${ago(c.since)})` : ''}`]
+  if (c.first && c.pulled) out.push(`- The session put ${plural(c.pulled, 'file')} in this folder when you joined.`)
+  for (const p of c.people) {
+    const files = p.files.slice(0, 12).map((f) => {
+      const k = kindWord(f.kind)
+      return `\`${f.path}\` (${k || `+${f.added} -${f.removed}`}${f.pulled ? ', pulled from git' : ''})`
+    })
+    const n = Math.max(p.fileCount || 0, p.files.length)
+    if (n > files.length) files.push(`and ${n - files.length} more`)
+    out.push(`- **${p.name}** changed ${plural(n, 'file')}, +${p.added} -${p.removed}: ${files.join(', ')}`)
+  }
+  if (c.partial) out.push('- Older changes from while you were away are no longer in the history.')
+  const m = c.mine || {}
+  if (m.shared) out.push(`- Your ${plural(m.shared, 'change')} from while you were away went into the session.`)
+  if (m.merged?.length) out.push(`- Combined with the session's changes: ${m.merged.map((p) => `\`${p}\``).join(', ')}.`)
+  if (m.conflicts?.length) out.push(`- Clashed with the session's changes (the session's version is in the file, yours is in the merge; see quilt_merges): ${m.conflicts.map((p) => `\`${p}\``).join(', ')}.`)
+  if (c.backups?.length) out.push(`- Your copies of ${plural(c.backups.length, 'file')} differed from the session's and were replaced; they are kept: ${c.backups.map((b) => `\`${b.path}\` → \`${b.copy}\``).join(', ')}.`)
+  out.push('Read quilt_history for the diffs before you change these files.')
+  return out
+}

package/src/chat-archive.js

@@ -0,0 +1,85 @@
+// The session's chat, kept longer than the room keeps it. The room's chat holds the newest 500
+// messages (every writer trims it, so the shared document stays small); a busy session with
+// several agents passes that in days, and a person's conversation with one agent is gone with
+// it. Each place that reads conversations for agents (a folder's daemon, the relay for hosted
+// agents) keeps every message it sees in a file beside its copy of the room, and reads the two
+// together (conversation.js). Who may read what is decided when it is read, as for the room's chat.
+import fs from 'node:fs'
+import path from 'node:path'
+
+export const ARCHIVE_CAP = 5000 // messages kept; the file is rewritten without the oldest past this
+const SLACK = 1000
+
+const valid = (m) => m && typeof m === 'object' && typeof m.id === 'string' && m.id && typeof m.by === 'string' && typeof m.text === 'string'
+
+export class ChatArchive {
+  /** `file`: where it is kept (null keeps it in memory only, for tests and rooms without a disk). */
+  constructor (file, { cap = ARCHIVE_CAP, log = () => {} } = {}) {
+    this.file = file
+    this.cap = cap
+    this.log = log
+    this.list = []
+    this.ids = new Set()
+    this.lines = 0
+    if (file) {
+      try {
+        for (const line of fs.readFileSync(file, 'utf8').split('\n')) {
+          if (!line) continue
+          let m
+          try { m = JSON.parse(line) } catch { continue } // a line cut off by a crash
+          this.lines++
+          if (valid(m) && !this.ids.has(m.id)) { this.ids.add(m.id); this.list.push(m) }
+        }
+      } catch {}
+      this.list.sort((a, b) => (a.ts || 0) - (b.ts || 0))
+      // The file keeps up to SLACK more than the cap between rewrites.
+      for (const m of this.list.splice(0, Math.max(0, this.list.length - this.cap))) this.ids.delete(m.id)
+    }
+  }
+
+  /** Keeps messages not kept yet (from the room's chat, oldest first). */
+  add (messages) {
+    const fresh = []
+    for (const m of messages || []) {
+      if (!valid(m) || this.ids.has(m.id)) continue
+      const keep = { id: m.id, by: m.by, ...(m.to ? { to: m.to } : {}), ...(m.of ? { of: m.of } : {}), ...(m.kind ? { kind: m.kind } : {}), text: m.text, ts: Number(m.ts) || 0 }
+      this.ids.add(m.id)
+      this.list.push(keep)
+      fresh.push(keep)
+    }
+    if (!fresh.length) return 0
+    for (let i = Math.max(1, this.list.length - fresh.length); i < this.list.length; i++) {
+      if (this.list[i].ts < this.list[i - 1].ts) { this.list.sort((a, b) => (a.ts || 0) - (b.ts || 0)); break }
+    }
+    if (this.list.length > this.cap) {
+      for (const m of this.list.splice(0, this.list.length - this.cap)) this.ids.delete(m.id)
+    }
+    if (!this.file) return fresh.length
+    try {
+      if (this.lines + fresh.length > this.cap + SLACK) {
+        fs.mkdirSync(path.dirname(this.file), { recursive: true })
+        const tmp = this.file + '.tmp'
+        fs.writeFileSync(tmp, this.list.map((m) => JSON.stringify(m)).join('\n') + '\n', { mode: 0o600 })
+        fs.renameSync(tmp, this.file)
+        this.lines = this.list.length
+      } else {
+        fs.mkdirSync(path.dirname(this.file), { recursive: true })
+        fs.appendFileSync(this.file, fresh.map((m) => JSON.stringify(m)).join('\n') + '\n', { mode: 0o600 })
+        this.lines += fresh.length
+      }
+    } catch (err) { this.log(`could not keep chat history: ${err.message}`) }
+    return fresh.length
+  }
+
+  /**
+   * Everything kept, with the room's current chat (`live`, which wins for a message in both),
+   * oldest first.
+   */
+  with (live = []) {
+    const liveIds = new Set()
+    for (const m of live) if (valid(m)) liveIds.add(m.id)
+    const older = this.list.filter((m) => !liveIds.has(m.id))
+    const out = older.concat(live.filter(valid))
+    return older.length && live.length && older[older.length - 1].ts > (live[0].ts || 0) ? out.sort((a, b) => (a.ts || 0) - (b.ts || 0)) : out
+  }
+}