heyquilt 0.3.121 → 0.3.122

package/src/session-migrate.js

@@ -0,0 +1,119 @@
+// Quilt's side of Seam: a session with no git remote becomes a quilt
+// (plans/quilt-source-control/16, "How a session becomes a quilt", "Without history").
+// It calls Seam through a client with the quiltClient shape (src/quilts/client.js), acting as
+// the session's owner, who becomes the quilt's admin. Seam (src/quilts/) never imports this.
+//
+//   1. a quilt named after the room (slug from the room, `-2`.. when taken);
+//   2. patch 1 on main: the default branch document's files, sealed in a square of the owner's
+//      and merged, message "Session <room> as of <date>";
+//   3. one square per other branch document, based at patch 1, whose live changes are its
+//      difference from patch 1 (so it shows as uncommitted work).
+//
+//   4. each open merge record (state open or editing) as a conflict term in its square's first
+//      commit (16's merges row): `ours` the opener's text, on the migrated square; `theirs` the
+//      session's text, naming patch 1's square and commit; the record's base as the remove. A
+//      default branch's open merges get a square of their own ('(default)'), as main is patch 1.
+//      Binary records, and records whose text stayed on the opener's disk, have nothing to put
+//      in a term: they are listed in `merges_left`.
+//
+// Files kept in storage (large files) have no text on the relay; they are listed in
+// `left_out` and stay in the session's storage.
+
+export const slugFor = (room) => String(room || '').toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 56) || 'session'
+
+const b64 = (text) => Buffer.from(String(text)).toString('base64')
+const put = (path, text) => ({ path, op: 'put', content: b64(text) })
+
+/** The changes that turn `base` ({ path: text }) into `files`. */
+export function changesFrom (base, files) {
+  const out = []
+  for (const [p, t] of Object.entries(files || {})) if (!base || base[p] !== t) out.push(put(p, t))
+  for (const p of Object.keys(base || {})) if (!(p in (files || {}))) out.push({ path: p, op: 'delete' })
+  return out.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
+}
+
+const taken = (e) => e && (e.status === 409 || e.code === 'conflict' || e.code === 'slug_taken' || /taken|exists|duplicate/i.test(String(e.message)))
+
+/**
+ * Makes the quilt. `defaultFiles`: { path: text } of the default branch document; `branches`:
+ * [{ key, files: { path: text } }] for the others; `leftOut`: paths with no text. Returns
+ * { quilt_id, slug, patch, squares: [{ from, id }], left_out }. A failure after the quilt was
+ * made throws with `quilt_id` on the error, so the caller can name it.
+ */
+export const DEFAULT_MERGES = '(default)'
+const OPEN = new Set(['open', 'editing'])
+
+/** The open merges of one branch → { terms: conflict changes, left: records with no text to carry }. */
+export function termsFor (merges, files, { square, patchSquare, patch }) {
+  const terms = []; const left = []; const seen = new Set()
+  for (const m of merges || []) {
+    if (!m || !OPEN.has(m.state) || seen.has(m.path)) continue
+    if (m.binary || m.local || (m.ours == null && !m.oursDeleted)) { left.push(m); continue }
+    seen.add(m.path)
+    const now = files && Object.prototype.hasOwnProperty.call(files, m.path) ? files[m.path] : null
+    if (now == null && m.oursDeleted) { left.push(m); continue } // both sides gone: nothing conflicts
+    terms.push({
+      path: m.path,
+      op: 'conflict',
+      reason: 'import',
+      base: m.base != null ? { content: b64(m.base) } : null,
+      ours: m.oursDeleted ? null : { content: b64(m.ours), from_square: square, ...(m.by ? { by: String(m.by) } : {}) },
+      theirs: now == null ? null : { content: b64(now), ...(patchSquare ? { from_square: patchSquare } : {}), ...(patch ? { from_commit: patch.commit } : {}) }
+    })
+  }
+  return { terms, left }
+}
+
+export async function makeQuiltWithoutHistory ({ seam, room, defaultFiles = {}, defaultMerges = [], branches = [], leftOut = [], date = new Date() }) {
+  const base = slugFor(room)
+  let q = null
+  for (let n = 1; !q && n <= 20; n++) {
+    const slug = n === 1 ? base : `${base}-${n}`
+    try { q = await seam.createQuilt({ slug, name: room }) } catch (e) { if (!taken(e) || n === 20) throw e }
+  }
+  try {
+    let patch = null
+    let patchSquare = null
+    const first = changesFrom(null, defaultFiles)
+    if (first.length) {
+      const day = new Date(date).toISOString().slice(0, 10)
+      const s = await seam.openSquare(q.id, { title: `Session ${room}` })
+      patchSquare = s.id
+      await seam.commit(q.id, s.id, { expect_head: null, message: `Session ${room} as of ${day}`, changes: first })
+      const m = await seam.merge(q.id, 'main', { square: s.id })
+      if (!m || !m.ok || !m.merged) throw Object.assign(new Error(`Seam did not merge patch 1: ${(m && ((m.refused && m.refused.detail) || m.error || m.code)) || "no answer"}`), { code: m && m.code })
+      patch = { no: m.merged.patch_no, commit: m.merged.commit }
+    }
+    const squares = []
+    const terms = []
+    const mergesLeft = []
+    // Open merges as terms in the square's first commit; the rest of its work stays live.
+    const carry = async (from, sq, merges, files) => {
+      const t = termsFor(merges, files, { square: sq, patchSquare, patch })
+      for (const m of t.left) mergesLeft.push({ from, path: m.path, id: m.id })
+      if (!t.terms.length) return new Set()
+      await seam.commit(q.id, sq, { expect_head: null, message: `Open merges from session ${room}: ${t.terms.map((x) => x.path).join(', ')}`.slice(0, 2000), changes: t.terms })
+      for (const x of t.terms) terms.push({ from, path: x.path, square: sq })
+      return new Set(t.terms.map((x) => x.path))
+    }
+    const defaultLeft = termsFor(defaultMerges, defaultFiles, {})
+    if (!defaultLeft.terms.length) for (const m of defaultLeft.left) mergesLeft.push({ from: DEFAULT_MERGES, path: m.path, id: m.id })
+    else {
+      const s = await seam.openSquare(q.id, { title: `Open merges from session ${room}` })
+      const held = await carry(DEFAULT_MERGES, s.id, defaultMerges, defaultFiles)
+      if (held.size) squares.push({ from: DEFAULT_MERGES, id: s.id })
+    }
+    for (const b of branches) {
+      const s = await seam.openSquare(q.id, { title: String(b.key).slice(0, 200) })
+      const held = await carry(b.key, s.id, b.merges, b.files)
+      const changes = changesFrom(defaultFiles, b.files).filter((c) => !held.has(c.path))
+      if (changes.length) await seam.setLive(q.id, s.id, { changes })
+      squares.push({ from: b.key, id: s.id })
+    }
+    return { quilt_id: q.id, slug: q.slug, patch, squares, terms, merges_left: mergesLeft, left_out: [...leftOut].sort() }
+  } catch (e) {
+    e.quilt_id = q.id
+    e.message = `${e.message} (quilt ${q.slug} was made but the session was not moved into it)`
+    throw e
+  }
+}

package/src/session-quilt.js

@@ -0,0 +1,145 @@
+// Quilt's side of Seam: what making a session a quilt would do, without doing it
+// (plans/quilt-source-control/16, "How a session becomes a quilt", "Dry run and check").
+// Pure: it reads a snapshot of the room (Room.quiltSnapshot in server.js) and returns the
+// report the owner reads before the real migration. Seam (src/quilts/) never imports this.
+//
+// Snapshot:
+//   { room, owner, defaultKey, hasRemote,
+//     branches: [{ key, by, files: { path: { hash, bytes } }, history: [entry], merges: [{ id, state }] }],
+//     claims: [{ pattern, branch, by, byId, queue }], tasks: [{ id, pr }], commitRequests: n }
+// Options:
+//   tip: { path: hash } the imported main's tree, when the room has a remote and its import exists.
+import { createHash } from 'node:crypto'
+
+export const fileHash = (text) => createHash('sha256').update(String(text)).digest('hex')
+
+const sumBytes = (files) => Object.values(files || {}).reduce((n, f) => n + (Number(f && f.bytes) || 0), 0)
+
+/** The paths whose content differs between a branch document's files and a tree, both `{ path: hash }`-like. */
+export function differingPaths (files, tree) {
+  const out = []
+  for (const [p, f] of Object.entries(files || {})) if (tree[p] !== (f && f.hash)) out.push(p)
+  for (const p of Object.keys(tree || {})) if (!(p in (files || {}))) out.push(p)
+  return out.sort()
+}
+
+/**
+ * The dry run's report. `mode` is `with_history` for a room with a git remote (the import and
+ * its follow come first; `needs_import` until a `tip` is given), else `without_history` (the
+ * default branch document is sealed as patch 1).
+ */
+export function planSessionQuilt (snap, { tip = null } = {}) {
+  const withHistory = !!snap.hasRemote
+  const defaultKey = snap.defaultKey
+  const owner = snap.owner || ''
+  const branches = (snap.branches || []).filter((b) => b && typeof b.key === 'string')
+  const def = branches.find((b) => b.key === defaultKey) || null
+  const squares = []
+  const report = {
+    room: snap.room,
+    mode: withHistory ? 'with_history' : 'without_history',
+    needs_import: withHistory && !tip,
+    first_patch: null,
+    squares,
+    claims: { moved: 0, opened_for: [], without_square: [] },
+    tasks: { matched: [], unmatched: [] },
+    terms: 0,
+    history: { kept: 0, dropped: 0 },
+    commit_requests: Number(snap.commitRequests) || 0,
+    bytes: 0
+  }
+  if (def && !withHistory) {
+    report.first_patch = { from: def.key, message: `Session ${snap.room} as of <date>`, files: Object.keys(def.files || {}).length, bytes: sumBytes(def.files) }
+  }
+  if (def && withHistory && tip) {
+    const paths = differingPaths(def.files, tip)
+    if (paths.length) {
+      squares.push({ from: def.key, title: `Uncommitted work from ${snap.room}`, base: 'import:main', holder: owner, adoption: true, files: paths.length, bytes: paths.reduce((n, p) => n + (Number(def.files[p] && def.files[p].bytes) || 0), 0) })
+    }
+  }
+  const squareOf = new Map()
+  for (const b of branches) {
+    if (b.key === defaultKey) continue
+    const at = /^@([0-9a-f]{7,64})$/.exec(b.key)
+    const base = withHistory ? (at ? `commit:${at[1]}` : `import:${b.key}`) : 'patch:1'
+    const sq = { from: b.key, title: b.key, base, holder: b.by || owner, adoption: false, files: Object.keys(b.files || {}).length, bytes: sumBytes(b.files) }
+    squares.push(sq)
+    squareOf.set(b.key, sq)
+  }
+  const adoption = squares.find((s) => s.adoption) || null
+  const opened = new Set()
+  for (const c of snap.claims || []) {
+    const branch = c.branch || defaultKey
+    const holder = c.byId || c.by || ''
+    if (branch === defaultKey) {
+      if (adoption) { report.claims.moved++; continue }
+      if (!def) { report.claims.without_square.push({ pattern: c.pattern, branch, holder }); continue }
+      // No square holds the default branch's work: one is opened for the claim's holder.
+      if (!opened.has(holder)) { opened.add(holder); report.claims.opened_for.push(holder) }
+      report.claims.moved++
+      continue
+    }
+    if (squareOf.has(branch)) report.claims.moved++
+    else report.claims.without_square.push({ pattern: c.pattern, branch, holder })
+  }
+  for (const t of snap.tasks || []) {
+    if (!t || !t.pr) continue
+    const b = t.pr.branch
+    if (b && squareOf.has(b)) report.tasks.matched.push({ id: t.id, square_from: b })
+    else report.tasks.unmatched.push({ id: t.id, pr: t.pr.number || null })
+  }
+  for (const b of branches) {
+    report.terms += (b.merges || []).filter((m) => m && (m.state === 'open' || m.state === 'editing')).length
+    for (const h of b.history || []) {
+      if (withHistory && h && (h.pulled || h.seed)) report.history.dropped++
+      else report.history.kept++
+    }
+  }
+  report.bytes = squares.reduce((n, s) => n + s.bytes, 0) + (report.first_patch ? report.first_patch.bytes : 0)
+  report.problems = [
+    ...report.claims.without_square.map((c) => `claim on ${c.pattern} (${c.branch}) has no square`),
+    ...report.tasks.unmatched.map((t) => `task ${t.id}'s pull request${t.pr ? ` #${t.pr}` : ''} has no square; it becomes a task comment`)
+  ]
+  return report
+}
+
+export const MIGRATE_SESSION_DESCRIPTION =
+  'What making this session a quilt (Quilt\'s own source control, Seam) would do, read only: the first patch or the import, ' +
+  'which branches become squares, how claims and tasks with pull requests move, and anything that would not carry over. ' +
+  'Only the session\'s owner (or, in a session without one, anyone who may change files) can ask. Nothing changes.'
+
+/** Why `a` (the asker's access) may not see the dry run, or null when they may. */
+export function quiltPlanRefusal ({ controlled, access }) {
+  if (controlled ? !(access && access.owner) : !!(access && access.role === 'viewer')) return 'only the session\'s owner can see what making it a quilt would do'
+  return null
+}
+
+const kb = (n) => n >= 1024 * 1024 ? `${(n / 1024 / 1024).toFixed(1)} MB` : `${Math.ceil(n / 1024)} KB`
+
+/** The dry run's report as plain text, for an agent or a person. */
+export function describeQuiltPlan (p) {
+  const out = [`Making session ${p.room} a quilt (dry run, nothing changed):`]
+  if (p.mode === 'with_history') {
+    out.push(p.needs_import
+      ? '- The session has a git remote: its history comes in by an import that follows the remote first (seam import), then the session moves.'
+      : '- History comes from the import of the session\'s git remote.')
+  } else if (p.first_patch) {
+    out.push(`- Patch 1 is the ${p.first_patch.from} branch as it is now: ${p.first_patch.files} file${p.first_patch.files === 1 ? '' : 's'}, ${kb(p.first_patch.bytes)}.`)
+  } else {
+    out.push('- The session has no default branch document: patch 1 starts empty.')
+  }
+  if (p.squares.length) {
+    out.push(`- ${p.squares.length} square${p.squares.length === 1 ? '' : 's'}:`)
+    for (const s of p.squares) out.push(`  - ${s.title} from ${s.from}, on ${s.base}, held by ${s.holder || 'nobody'}: ${s.files} file${s.files === 1 ? '' : 's'}`)
+  } else out.push('- No squares: there is no other branch with work on it.')
+  out.push(`- Claims: ${p.claims.moved} move to their squares${p.claims.opened_for.length ? ` (a square is opened for ${p.claims.opened_for.join(', ')})` : ''}.`)
+  if (p.tasks.matched.length) out.push(`- ${p.tasks.matched.length} task${p.tasks.matched.length === 1 ? '' : 's'} with a pull request link${p.tasks.matched.length === 1 ? 's' : ''} to a square.`)
+  if (p.terms) out.push(`- ${p.terms} open merge${p.terms === 1 ? '' : 's'} become${p.terms === 1 ? 's' : ''} terms on their squares.`)
+  out.push(`- History: ${p.history.kept} entr${p.history.kept === 1 ? 'y' : 'ies'} kept${p.history.dropped ? `, ${p.history.dropped} dropped (they are in the import)` : ''}.`)
+  if (p.commit_requests) out.push(`- ${p.commit_requests} commit request${p.commit_requests === 1 ? '' : 's'} must be done or withdrawn first.`)
+  if (p.problems && p.problems.length) {
+    out.push('Would not carry over:')
+    for (const x of p.problems) out.push(`- ${x}`)
+  }
+  return out.join('\n')
+}

package/src/session-seam.js

@@ -0,0 +1,71 @@
+// Quilt's side of Seam for agents (plans/quilt-source-control/12 and 16): in a session that is a
+// quilt, an agent works through Seam (squares, commits, merges), never GitHub. The same for every
+// AI tool: the shared MCP tools refuse their GitHub path with the Seam tool to use instead, and the
+// relay gives no GitHub token to an agent's git there. Seam (src/quilts/) never imports this.
+//
+// A session is a quilt when the relay is on Seam (QUILT_SOURCE_URL) and its room names its quilt
+// (meta.quilt_id, set by the migration with layout 3 and cleared when a failed check reverts it).
+// Every other session keeps its GitHub path exactly as it is.
+
+/** The quilt a room's session is, or null while it is a GitHub-backed (or plain) session. */
+export function quiltOf (meta, env = process.env) {
+  if (!env || !env.QUILT_SOURCE_URL) return null
+  if (!meta) return null
+  return typeof meta.quilt_id === 'string' && meta.quilt_id ? meta.quilt_id : null
+}
+
+// Each GitHub tool, and the Seam tool an agent uses for it in a session that is a quilt.
+export const SEAM_FOR = {
+  quilt_git_commit: 'seam_commit (commits your square)',
+  quilt_git_status: 'seam_square_status (your square and what changed in it)',
+  quilt_git_log: 'seam_log',
+  quilt_git_diff: 'seam_diff',
+  quilt_git_revert: 'seam_restore (puts a file back as the line has it)',
+  quilt_git_pull_requests: 'seam_squares (the squares on a line, with their checks)',
+  quilt_git_merge: 'seam_merge (merges a square onto its line)',
+  quilt_git_branch: 'seam_open_square (a square of your own on a line)',
+  quilt_sync_branch: 'seam_square_status (a square follows its line by itself)',
+  quilt_sync_status: 'seam_square_status',
+  quilt_github_token: null, // nothing to use instead: the owner's export to GitHub has its own credential
+  quilt_request_commit: 'seam_commit on a square of your own, then seam_merge when you may (or ask a person to)',
+  quilt_agent_commits: 'seam_log',
+  quilt_commit_status: 'seam_square_status',
+  quilt_commit_request_done: 'seam_square_status',
+  quilt_github_sync: 'seam_square_status'
+}
+
+/** Why a GitHub tool is refused in a quilt session, naming the Seam tool to use; null when it isn't. */
+export function seamRefusal (tool, quiltId) {
+  if (!quiltId || !Object.hasOwn(SEAM_FOR, tool)) return null
+  const use = SEAM_FOR[tool] ? `Use ${SEAM_FOR[tool]} instead.` : 'Seam needs no GitHub token: the owner\'s export to GitHub has its own credential.'
+  return `This session is the quilt ${quiltId} on Seam, Quilt's source control: it has no GitHub path for agents. ${use} ${SEAM_GUIDE}`
+}
+
+export const SEAM_GUIDE = 'Its tools come from Seam\'s MCP server (`npx @heyquilt/seam mcp`, the same for every AI tool). Work happens in squares: open one with seam_open_square, commit in it with seam_commit, and seam_merge merges it onto its line. Never use git or GitHub here: a push from your git is refused, and Seam writes GitHub itself when the owner exports there.'
+
+/** The line a session's status answers with, in a quilt session; '' otherwise. */
+export function seamNote (quiltId) {
+  return quiltId ? `This session is the quilt ${quiltId} on Seam. ${SEAM_GUIDE}` : ''
+}
+
+/** Why the relay gives no GitHub token to a member's git here; null when it may. People keep theirs. */
+export function gitTokenRefusal (quiltId, kind) {
+  if (!quiltId || kind !== 'agent') return null
+  return `this session is the quilt ${quiltId} on Seam: agents use Seam (seam_commit, seam_merge), not git or GitHub`
+}
+
+/**
+ * A folder's MCP server (src/mcp.js), in a session that is a quilt: wraps `registerTool` so each
+ * GitHub tool refuses with the Seam tool to use. `quiltNow()` is the session's link as the relay
+ * last said ({ id, slug } or null), asked at call time, so a session that becomes a quilt (or
+ * stops being one) changes the answer without a restart. Every other tool is untouched.
+ */
+export function seamGate (registerTool, quiltNow) {
+  return (name, spec, handler) => registerTool(name, spec, Object.hasOwn(SEAM_FOR, name)
+    ? async (...args) => {
+      const q = await quiltNow()
+      const no = q && seamRefusal(name, q.slug || q.id)
+      return no ? { content: [{ type: 'text', text: no }], isError: true } : handler(...args)
+    }
+    : handler)
+}

package/src/session.js

@@ -2,6 +2,9 @@
 // back. Any tool that edits files on disk (Claude Code, Cursor, Codex, vim...)
 // participates automatically; concurrent edits are merged character by
 // character by the CRDT.
+import { describeQuiltPlan } from './session-quilt.js'
+import { SquareFollower } from './session-follow.js'
+import { quiltClient } from '@heyquilt/seam/lib/quilts/client.js'
 import fs from 'node:fs'
 import path from 'node:path'
 import crypto from 'node:crypto'
@@ -25,7 +28,7 @@ import { migrateDir } from './legacy.js'
 import { withComments, addComment as putComment } from './task-comments.js'
 import { readTasks, addTask as putTask, updateTask as patchTask, deleteTask as dropTask, planAutoTask, nextTask, pickupMode, columnName } from './tasks.js'
 import { getSettings } from './settings.js'
-import { HistoryLog, queryHistory, parseSince, currentTask, blameChange, lineDiff } from './history.js'
+import { HistoryLog, queryHistory, parseSince, currentTask, blameChange, lineDiff, legacyTail } from './history.js'
 import { historyMarks, awayChanges, mergeCatchUp, emptyCatchUp } from './catchup.js'
 import { Inbox, mentionsMe, describeEvent } from './inbox.js'
 import { projectRules, renderRules, gatherPlan, planKey } from './project-rules.js'
@@ -681,6 +684,8 @@ export class Session extends EventEmitter {
     this.conn.on('access', (a) => this.setAccess(a))
     this.conn.on('members', (m) => this.setMembers(m))
     this.conn.on('branches', (list) => this.setBranches(list))
+    // Seam (plans/quilt-source-control/16): the relay says when the session is a quilt, and which.
+    this.conn.on('quilt', (q) => { this.quilt = q; this.emit('quilt', q); if (this.squareFollower) this.squareFollower.onQuilt(q).catch(() => {}) })
     // GitHub moved this folder's branch: fetch and bring it in now, not at the next minute's look.
     this.conn.on('pushed', (p) => {
       if (!this.git || !this.git.branch || p.branch !== this.branchKey() || this.stopped) return
@@ -3686,6 +3691,70 @@ export class Session extends EventEmitter {
    * Asked for by an AI (quilt_sync_branch): fetch and bring commits in now, without waiting for
    * the next look or another member's folder. What happened: { branch, upstream, moved, busy }.
    */
+  /**
+   * What making this session a quilt would do (plans/quilt-source-control/16), read only: the
+   * relay's dry run (behind QUILT_SOURCE_URL there, the owner's), as { plan, text }.
+   */
+  async quiltPlan () {
+    if (!this.conn || !this.conn.connected) throw new Error('not connected to the relay; the dry run needs a connection')
+    const r = await this.conn.branchRequest({ op: 'quilt-plan' })
+    return { plan: r.plan, text: describeQuiltPlan(r.plan) }
+  }
+
+  /**
+   * Makes the session a quilt (plans/quilt-source-control/16, "Without history"): the relay does
+   * it, as the owner, with `token` (their Seam sign-in: SEAM_TOKEN, else their Quilt account's).
+   * What it made: { quilt, text }.
+   */
+  async quiltMigrate (token) {
+    if (!this.conn || !this.conn.connected) throw new Error('not connected to the relay; making the session a quilt needs a connection')
+    if (!token) throw new Error('sign in first (quilt login, or set SEAM_TOKEN): the session becomes a quilt as its owner')
+    const r = await this.conn.branchRequest({ op: 'quilt-migrate', token })
+    const q = r.quilt
+    const lines = [`Session ${this.room || ''} is now the quilt ${q.slug}.`.replace('Session  is', 'This session is')]
+    if (q.patch) lines.push(`Patch ${q.patch.no} holds the main branch as it was.`)
+    for (const s of q.squares) lines.push(`Branch ${s.from} is square sq:${s.id.slice(0, 8)}.`)
+    const moved = Object.keys(q.tasks || {}).length
+    if (moved) lines.push(`${moved} task${moved === 1 ? '' : 's'} with a pull request follow${moved === 1 ? 's' : ''} its square.`)
+    if (q.left_out.length) lines.push(`Large files left in the session's storage, not in the quilt: ${q.left_out.join(', ')}.`)
+    return { quilt: q, text: lines.join('\n') }
+  }
+
+  /**
+   * The session's files into its squares' live documents on the relay (layout 3, 16), as the
+   * owner, once it is a quilt: { layout, live, adoption, text }.
+   */
+  async quiltSwitch (token) {
+    if (!this.conn || !this.conn.connected) throw new Error('not connected to the relay; moving the session needs a connection')
+    if (!token) throw new Error('sign in first (quilt login, or set SEAM_TOKEN): the session moves into its squares as its owner')
+    const r = await this.conn.branchRequest({ op: 'quilt-switch', token })
+    const lines = ['The session\'s files are in its squares now; its branches are kept, read-only.']
+    for (const [b, k] of Object.entries(r.live || {})) lines.push(`${b} is in square sq:${k.replace(/^quilt\//, '').slice(0, 8)}.`)
+    if (r.adoption) lines.push(`Work on the main branch since it became a quilt is in the square "Uncommitted work" (sq:${r.adoption.slice(0, 8)}).`)
+    lines.push('Apps without Seam are asked to update. quilt session migrate --back goes back to the branches.')
+    return { ...r, text: lines.join('\n') }
+  }
+
+  /**
+   * At layout 3 (plans/quilt-source-control/16): `dir` (its own folder) follows this folder's
+   * branch's square, live (session-follow.js), signed in to Seam with `token`. Only with
+   * QUILT_SOURCE_URL set and the relay saying the session is a layout-3 quilt.
+   */
+  async quiltFollow (token, dir) {
+    if (!token) throw new Error('sign in first (quilt login, or set SEAM_TOKEN): the square is read and written as you')
+    if (!this.squareFollower) this.squareFollower = new SquareFollower(this)
+    const client = process.env.QUILT_SOURCE_URL ? quiltClient({ api: process.env.QUILT_SOURCE_URL, token }) : null
+    const r = await this.squareFollower.follow({ dir: dir ? path.resolve(this.root, String(dir)) : '', client })
+    return { ...r, text: `${r.dir} follows the square sq:${r.square.slice(0, 8)}: edits there are live for everyone on it.` }
+  }
+
+  /** Back to the branches (layout 2) from the kept branch documents. */
+  async quiltUnswitch () {
+    if (!this.conn || !this.conn.connected) throw new Error('not connected to the relay')
+    const r = await this.conn.branchRequest({ op: 'quilt-unswitch' })
+    return { ...r, text: 'The session works from its branches again; the squares keep their live documents.' }
+  }
+
   async syncBranchNow () {
     // A folder that can't bring commits in itself (no git here, or its fetch fails) asks the
     // relay to look at GitHub for its branch now (relay-upstream.js), as a hosted agent can.
@@ -5634,7 +5703,9 @@ export class Session extends EventEmitter {
   historyQuery ({ path, by, since, task, limit } = {}) {
     const from = parseSince(since)
     if (from === undefined) throw new Error('since: use a duration like 2h or 3d, "today", "yesterday", or a date')
-    return queryHistory(this.history.entries(), { path, by, since: from ?? undefined, task, limit: Math.min(Number(limit) || 50, 500) })
+    // Once the session is a quilt (the relay says so, src/server.js branchesFields), older changes are its legacy tail.
+    const entries = legacyTail(this.history.entries(), { at: this.quilt && this.quilt.at })
+    return queryHistory(entries, { path, by, since: from ?? undefined, task, limit: Math.min(Number(limit) || 50, 500) })
   }
 
   /** `input` is a title, or { title, assignee, forAi, to_ai, tool, files }. "me" means this person. */
@@ -8077,6 +8148,7 @@ export class Session extends EventEmitter {
     this.rechecks.clear()
     clearInterval(this.reconcileTimer)
     clearInterval(this.upstreamPoll)
+    if (this.squareFollower) await this.squareFollower.stop()
     clearTimeout(this.clashTimer)
     if (this.clashPending) clearTimeout(this.clashPending.timer)
     clearTimeout(this.upstreamTimer)

package/src/source-live/live-block.js

@@ -14,9 +14,10 @@ import path from 'node:path'
 import * as Y from 'yjs'
 import { Connection, REMOTE } from '../connection.js'
 import { applyTextDiff } from '../textdiff.js'
-import { blobId, under } from '../quilts/records.js'
-import { isText } from '../quilts/textdiff.js'
-import { checkout, findBlock, saveBlock, localChanges, BLOCK_DIR } from '../quilts/block.js'
+// Seam's block folders and ids come from Seam's client package (@heyquilt/seam), never Seam's server code.
+import { blobId, under } from '@heyquilt/seam/lib/quilts/records.js'
+import { isText } from '@heyquilt/seam/lib/quilts/textdiff.js'
+import { checkout, findBlock, saveBlock, localChanges, BLOCK_DIR } from '@heyquilt/seam/lib/quilts/block.js'
 import { liveKey, liveMaps, liveHead, entryOf, entryId, overlay } from './live-square.js'
 
 export const MAX_LIVE_TEXT = 2 * 1024 * 1024

package/src/source-live/live-square.js

@@ -17,7 +17,7 @@
 // from the overlay, one transaction moves `head` and drops every entry whose content is the one
 // that was committed. An entry typed into after the commit read it stays, against the new head.
 import * as Y from 'yjs'
-import { blobId } from '../quilts/records.js'
+import { blobId } from '@heyquilt/seam/lib/quilts/records.js'
 
 export const LIVE_PREFIX = 'quilt/'
 export const liveKey = (squareId) => `${LIVE_PREFIX}${squareId}`