heyquilt 0.3.121 → 0.3.138

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
+// (Seam's 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,284 @@
+// Quilt's side of Seam for agents (Seam's 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 session's own MCP server (`quilt mcp` in a folder, the relay's for hosted agents)
+// serves Seam's everyday tools itself, acting on the session's quilt and the folder's square with
+// the member's own Quilt sign-in (seam-access.js), so nothing is set up by hand. There, everything
+// an AI is told names only Seam (Daniel, 2026-10-31): the git-era tools are hidden (GIT_TOOLS) or
+// refuse with the Seam tool to use, the guidance leaves git out (seamOnly), a push that still
+// reaches the hook is refused, and the relay gives no GitHub token to an agent's git there.
+//
+// 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, and offers no Seam tools.
+import { z } from 'zod'
+// Seam's tools, their descriptions and answers come from Seam's client package (@heyquilt/seam).
+import { registerSeamTools, SEAM_INPUTS, SEAM_DESCRIPTIONS } from '@heyquilt/seam/lib/quilts/tools.js'
+import { describeWrite } from '@heyquilt/seam/lib/quilts/describe.js'
+import { squareShort } from '@heyquilt/seam/lib/quilts/errors.js'
+
+/** 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
+}
+
+/**
+ * Seam's tools a session that is a quilt serves, the same for a folder's AI sessions and hosted
+ * agents: the everyday ones (Seam's 'core' profile) an agent in a session needs. A folder's
+ * square is the session's, so cloning, pulling, listing quilts and abandoning are left out.
+ */
+export const SEAM_SESSION_TOOLS = ['seam_square_status', 'seam_commit', 'seam_merge', 'seam_rebase', 'seam_resolve', 'seam_diff', 'seam_log', 'seam_show', 'seam_cat', 'seam_ls', 'seam_grep', 'seam_blame', 'seam_checks', 'seam_events', 'seam_reviews', 'seam_review', 'seam_interdiff', 'seam_squares', 'seam_open_square']
+
+// 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_cat (the line\'s copy of a file, to write back)',
+  quilt_git_pull_requests: 'seam_squares (the squares on a line) and seam_checks',
+  quilt_git_merge: 'seam_merge (merges your square onto main once its checks pass)',
+  quilt_git_branch: 'seam_square_status (your folder\'s square)',
+  quilt_sync_branch: 'seam_square_status (a square follows its line: seam_rebase moves it onto the tip)',
+  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, then seam_merge once its checks pass (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'
+}
+
+/** How work lands in a session that is a quilt, for an AI with a folder (its files are its square's live work). */
+export const SEAM_GUIDE = 'Edit files in your folder as always: they are your square\'s live work, shared at once with everyone on it. ' +
+  'Commit the square with seam_commit (it commits everything the square holds now, every writer\'s, so say why in the message), and merge it onto main with seam_merge once its checks pass (seam_checks; seam_events with wait: 30 waits for a verdict). ' +
+  'A conflict comes back as terms in your square: read them with seam_square_status and settle each with seam_resolve (or edit the file and commit), then merge again. ' +
+  'seam_diff, seam_log, seam_show and seam_blame read the history. Work lands only through these tools.'
+
+/** The same for a hosted agent, which has no folder. */
+export const SEAM_GUIDE_HOSTED = 'You have no folder: open a square of your own with seam_open_square, read files with seam_cat and seam_ls (rev: main or your square), and commit their new contents with seam_commit (files, square: your square). ' +
+  'Merge it onto main with seam_merge once its checks pass (seam_checks; seam_events with wait: 30 waits for a verdict). ' +
+  'A conflict comes back as terms in your square: read them with seam_square_status and settle each with seam_resolve (or commit the file without markers), then merge again. ' +
+  'Work lands only through these tools.'
+
+const guideFor = ({ hosted = false } = {}) => hosted ? SEAM_GUIDE_HOSTED : SEAM_GUIDE
+
+// How an agent hears of Seam: only as where the session's code is committed and merged. Chat, tasks and
+// the session itself stay in Quilt; nobody reaches a session through Seam.
+const codeIn = (quiltId) => `This session's code is committed and merged in Seam (the quilt ${quiltId})`
+
+/**
+ * Why a git-era tool is refused in a quilt session: just the Seam tool to use (or, for one with no
+ * counterpart, how work lands there); null when it isn't. An AI whose tool list is from before the
+ * move may still call one that is hidden now.
+ */
+export function seamRefusal (tool, quiltId, { hosted = false } = {}) {
+  if (!quiltId) return null
+  if (Object.hasOwn(SEAM_FOR, tool)) return `${codeIn(quiltId)}: ${SEAM_FOR[tool] ? `use ${SEAM_FOR[tool]} instead.` : 'Seam\'s tools need nothing set up.'}`
+  return GIT_TOOLS.has(tool) ? `${codeIn(quiltId)}, where ${tool} is not used. ${guideFor({ hosted })}` : null
+}
+
+/**
+ * The git-era tools a session that is a quilt does not offer (each of SEAM_FOR, and those about
+ * branches, boxes and merges with git): hidden from the tool list while it is one, so nothing an
+ * AI reads there names git or GitHub.
+ */
+export const GIT_TOOLS = new Set([...Object.keys(SEAM_FOR), 'quilt_git_status', 'quilt_git_log', 'quilt_git_diff', 'quilt_git_revert', 'quilt_git_pull_requests', 'quilt_git_merge', 'quilt_unpack', 'quilt_merges', 'quilt_resolve_merge', 'quilt_adopt_work', 'quilt_branches', 'quilt_clash', 'quilt_migrate_session'])
+
+// A sentence of guidance about git: branches, boxes, pushes, pull requests or GitHub.
+const GITTY = /\bgit\b|GitHub|pull request|\bpush(es|ed|ing)?\b|\bbox(es|ed)?\b|quilt_git_|quilt_unpack|quilt_branches|quilt_sync_|quilt_github|quilt_request_commit|quilt_commit_|quilt_agent_commits|quilt_merges|quilt_resolve_merge|quilt_adopt_work|quilt_clash|\bbranch(es)?\b/i
+
+/** Guidance with every sentence about git left out, for a session that is a quilt. */
+export function seamOnly (text) {
+  return String(text || '').split(/(?<=[.!?])\s+(?=[A-Z@"'(*0-9])/).filter((x) => !GITTY.test(x)).join(' ')
+}
+
+// Status sections that are git's alone (status.js), and the lines elsewhere that speak of git.
+const GIT_SECTION = /^## (Branches|Commit requests|Pulling|Boxed work|Waiting to go in)\b/
+const GIT_LINE = /\bgit\b|GitHub|pull request/i
+
+/**
+ * A session's status (status.js markdown) for a session that is a quilt: git's sections left out,
+ * and lines about git elsewhere too; what people wrote (the messages and chat sections) stays as it is.
+ */
+export function seamStatus (md) {
+  const out = []
+  let skip = false
+  let said = false
+  for (const line of String(md || '').split('\n')) {
+    if (line.startsWith('## ')) { skip = GIT_SECTION.test(line); said = /messages|chat/i.test(line) }
+    if (skip) continue
+    if (!said && GIT_LINE.test(line)) continue
+    out.push(line)
+  }
+  return out.join('\n')
+}
+
+/** Seam's own description of a tool, without its comparisons to git commands. */
+const seamWords = (d) => String(d || '').replace(/\s*\(git [^)]*\)/g, '').replace(/,? as git [^.,;]* does/g, '').replace(/, git:<sha>/g, '')
+
+/** The task workflow (agent-task-workflow.js) for a session that is a quilt: its git steps left out, the Seam one in. */
+export function seamWorkflow (workflow, { hosted = false } = {}) {
+  return `${seamOnly(workflow)} Before QA, commit the task's work with seam_commit${hosted ? ' in your square' : ''}, saying what the task is; it reaches main with seam_merge once its checks pass.`
+}
+
+/** A hosted agent's file tool at layout 3, where the session's files are in squares, not branches. */
+export function seamFileRefusal (quiltId) {
+  return quiltId ? `${codeIn(quiltId)}: its files are in squares, which Seam's tools read and write. ${SEAM_GUIDE_HOSTED}` : null
+}
+
+/** What a push that still reaches the folder's hook hears in a session that is a quilt: the Seam way, nothing else. */
+export function pushRefusal (quiltId) {
+  return quiltId ? `${codeIn(quiltId)}, so nothing is sent from here. ${SEAM_GUIDE}` : null
+}
+
+/** The line a session's status answers with, in a quilt session; '' otherwise. */
+export function seamNote (quiltId, { hosted = false } = {}) {
+  return quiltId ? `${codeIn(quiltId)}; chat, tasks and the session stay in Quilt. ${guideFor({ hosted })}` : ''
+}
+
+/** 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's code is committed and merged in Seam (the quilt ${quiltId}): agents use seam_commit and seam_merge`
+}
+
+/**
+ * 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, GIT_TOOLS.has(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)
+}
+
+// What the session adds to Seam's own description of a tool.
+const IN_SESSION = {
+  seam_commit: 'In this Quilt session, with no files: commits your folder\'s square (everything its live work holds now). ',
+  seam_merge: 'In this Quilt session: merges your folder\'s square onto main (committing its live work first); the folder carries on in a new square. ',
+  seam_square_status: 'In this Quilt session: your folder\'s square, with its live work not committed yet. ',
+  seam_open_square: 'In this Quilt session your folder works in a square of its own already (seam_square_status names it): edit there and seam_commit. '
+}
+const IN_SESSION_HOSTED = { seam_commit: 'You have no folder: give the files\' new contents (files) and your square. ' }
+
+/** An MCP tool spec for one of SEAM_SESSION_TOOLS: Seam's description and input, quilt and square optional (the session's). */
+export function seamToolSpec (name, { hosted = false } = {}) {
+  const lead = (hosted ? IN_SESSION_HOSTED[name] : IN_SESSION[name]) || ''
+  const shape = Object.fromEntries(Object.entries(SEAM_INPUTS[name]).map(([k, v]) => [k, v && v.description && seamWords(v.description) !== v.description ? v.describe(seamWords(v.description)) : v]))
+  return { description: lead + seamWords(SEAM_DESCRIPTIONS[name]), inputSchema: z.looseObject(shape) }
+}
+
+const SQUARE_INPUT = SEAM_INPUTS.seam_square_status.square
+// The tools whose answer can move the folder's square on Seam (its live document follows).
+const MOVES_HEAD = new Set(['seam_rebase', 'seam_resolve', 'seam_merge', 'seam_commit'])
+
+/** Seam's own handler for one tool (registerSeamTools on a stand-in server), with `client` for this call. */
+function seamHandler (name, client, hosted) {
+  let handler = null
+  registerSeamTools({ registerTool: (n, spec, fn) => { handler = fn } }, { client: () => client, tools: [name], hosted })
+  return handler
+}
+
+const textOf = (r) => ((r && r.content) || []).map((c) => c.text || '').join('\n')
+const answer = (text, extra = {}) => ({ content: [{ type: 'text', text }], ...extra })
+
+/**
+ * Runs one of SEAM_SESSION_TOOLS for a member of a session that is a quilt: Seam's own handler,
+ * with the session's quilt (and the folder's square) filled in where the call names none.
+ * `live` is the folder's live block on that square (source-live/live-block.js), or null: with it,
+ * seam_commit commits the live work the relay holds, seam_merge commits it first, the status says
+ * what is uncommitted, and a square whose head Seam moved has its live document follow.
+ * `next()` is asked after the folder's square merged, to move the branch to its next square.
+ * Returns an MCP tool result.
+ */
+export async function runSessionSeamTool (name, args = {}, { client, quilt, square = null, live = null, hosted = false, next = null, branch = '' }) {
+  if (!SEAM_SESSION_TOOLS.includes(name)) return answer(`${name} is not one of this session's Seam tools (${SEAM_SESSION_TOOLS.join(', ')}).`, { isError: true })
+  const shape = SEAM_INPUTS[name]
+  const a = { ...(args || {}) }
+  if (Object.hasOwn(shape, 'quilt') && !a.quilt) a.quilt = quilt
+  // A call that names a square other than the folder's acts on that one, on Seam alone.
+  const ref = String(a.square || '').replace(/^sq:/, '')
+  const mine = !ref || !!(square && ref.length >= 4 && String(square).startsWith(ref))
+  if (square && shape.square === SQUARE_INPUT && !a.square) a.square = square
+  if (square && name === 'seam_log' && !a.rev) a.rev = `sq:${square}`
+  if (square && name === 'seam_diff' && !a.from && !a.to) { a.from = 'main'; a.to = `sq:${square}` }
+  const onFolder = !!(live && square && mine && a.quilt === quilt)
+  const run = (x) => seamHandler(name, client, hosted)(x)
+  // A square opened beside the folder's is in no folder: its work could only go in as file contents
+  // (Seam's agent trial 2026-10-31, finding 10). The folder's square is where work goes.
+  if (live && square && name === 'seam_open_square') return answer(`This folder is on square ${squareShort(square)} already, and work goes there: edit the files in your folder and commit them with seam_commit, then seam_merge merges the square onto main (and the folder carries on in a new one).`, { isError: true })
+  try {
+    if (onFolder && name === 'seam_commit' && !a.files && !a.delete && !a.amend) {
+      if (!a.message) return answer('Say why: message.')
+      const r = await live.commit({ message: a.message })
+      return r && r.nothing ? answer('Nothing to commit: the square holds no live work since its last commit.') : answer(describeWrite(r, 'Committed'), { structuredContent: r })
+    }
+    if (onFolder && name === 'seam_merge' && !a.from && !a.dry_run) {
+      // The relay holds the square's live work: it is committed first, so the merge has all of it.
+      const c = await live.commit({ message: a.message || 'Work in progress' })
+      if (!a.message) { const t = await patchTitle(client, a.quilt, a.square, branch).catch(() => null); if (t) a.message = t }
+      const r = await run({ ...a, commit_live: false })
+      const rec = r.structuredContent || {}
+      const sealed = c && !c.nothing ? `Committed the square's live work first: ${describeWrite(c, 'committed')}\n` : ''
+      if (rec.ok && rec.merged && next) {
+        let moved = ''
+        try { const n = await next(); if (n && n.moved) moved = `\nThe folder carries on in a new square, ${squareShort(n.square)}, on main's new tip: keep editing as before.` } catch (err) { moved = `\nThe folder's branch did not move to a new square yet (${err.message}): ask again with seam_square_status.` }
+        return { ...r, content: [{ type: 'text', text: sealed + textOf(r) + moved }] }
+      }
+      if (rec.ok === false) await followHead(live, rec)
+      return { ...r, content: [{ type: 'text', text: sealed + textOf(r) + inChat(r) }] }
+    }
+    if (name === 'seam_merge' && !a.message && !a.from && !a.dry_run && mine) { const t = await patchTitle(client, a.quilt, a.square, branch).catch(() => null); if (t) a.message = t }
+    const r = await run(a)
+    if (name === 'seam_merge') return { ...r, content: [{ type: 'text', text: textOf(r) + inChat(r) }] }
+    if (onFolder && name === 'seam_square_status') {
+      const work = live.status ? live.status() : []
+      const lines = work.length ? `Live work not committed yet (seam_commit commits it):\n${work.map((w) => `  ${w.status} ${w.path}`).join('\n')}` : 'No live work since the last commit.'
+      return { ...r, content: [{ type: 'text', text: `${textOf(r)}\n${lines}` }] }
+    }
+    if (onFolder && MOVES_HEAD.has(name) && !r.isError) await followHead(live, r.structuredContent || {})
+    return r
+  } catch (err) {
+    return answer(err.message, { isError: true })
+  }
+}
+
+// Seam tells an agent whose merge waits for an approval to ask for a review (Seam's agent trial
+// 2026-10-31, finding 5), which reaches people only in Seam: in a Quilt session they hear it in chat.
+const ASKS_REVIEW = /waits for someone else[\s\S]*seam_review with kind request/
+const inChat = (r) => ASKS_REVIEW.test(textOf(r)) ? '\nIn this Quilt session, also ask them in chat (quilt_message, naming the square): Seam\'s review request is not shown in Quilt, and they approve with seam_review (kind approve) from their own AI session. Then wait for their answer and merge again.' : ''
+
+/**
+ * The title a merge gives its patch when the call names none: Seam takes the square's title, and a square
+ * the move into Seam opened for a branch is titled with the branch's name, so every patch from main was
+ * called "main". Then the square's own commits name it: its one message, or "N commits: first; second; …".
+ * Null (Seam's title stands) for a square named otherwise, or with no message of its own.
+ */
+export async function patchTitle (client, quilt, square, branch) {
+  if (!branch || !square || !client || !client.square || !client.log) return null
+  const s = await client.square(quilt, square)
+  if (!s || String(s.title || '').trim() !== String(branch).trim()) return null
+  const log = await client.log(quilt, { rev: `sq:${s.id || square}`, limit: 50 })
+  const own = ((log && log.commits) || []).filter((c) => c && c.square_id === (s.id || square) && c.message)
+    .map((c) => String(c.message).split('\n')[0].trim()).filter((m) => m && m !== 'Work in progress').reverse()
+  if (!own.length) return null
+  if (own.length === 1) return own[0].slice(0, 200)
+  const all = `${own.length} commits: ${own.join('; ')}`
+  return all.length > 200 ? `${all.slice(0, 199)}…` : all
+}
+
+/** The square's head after a Seam answer that moved it, and the live document following it. */
+async function followHead (live, rec) {
+  const own = (rec.square && rec.square.head) || rec.head || null
+  // A square with no commit of its own (a rebase moved its base only): its live work is relative to its base.
+  const base = !own && rec.square && rec.square.base ? rec.square.base : null
+  if ((own || base) && live.moveTo) await live.moveTo(own || base, { base: !!base }).catch(() => {})
+}