heyquilt 0.3.121 → 0.3.138

package/src/relay-mcp.js

@@ -36,8 +36,10 @@ import { clashAction, CLASH_DESCRIPTION, clashSchema } from './relay-clash.js'
 import { agentCommitsOf, repoRecordFor, POLICY_WORDS, pullRequestsFor, mergeForMember, describePulls, describeMerge, PULLS_DESCRIPTION, MERGE_DESCRIPTION, mergeSchema, agentsCanCommit, unpublishedFor, unpublishedRefusal, finishTaskFor, gitCommitFor, describeGitCommit, gitStatusFor, describeGitStatus, gitLogFor, describeGitLog, gitDiffFor, describeGitDiff, GIT_STATUS_DESCRIPTION, GIT_LOG_DESCRIPTION, GIT_DIFF_DESCRIPTION, GIT_REVERT_DESCRIPTION } from './relay-commit.js'
 import { UpdateCheck } from './update-check.js'
 import { TASK_WORKFLOW, pickupBrief, doneRefusal, verifiedEnough, verifiedLine, qaRefusal, qaNotesEnough, qaNotesLine, pickChecklist, MAX_VERIFIED } from './agent-task-workflow.js'
-import { HistoryLog, queryHistory, parseSince, formatHistory, currentTask, lineDiff } from './history.js'
+import { HistoryLog, queryHistory, parseSince, formatHistory, currentTask, lineDiff, legacyTail } from './history.js'
+import { linkedHistory } from './quilt-history.js'
 import { changeRefusal, TALK_REFUSED } from './session-access.js'
+import { MIGRATE_SESSION_DESCRIPTION, describeQuiltPlan } from './session-quilt.js'
 import { chatAbout, renderChatAbout, waitingOn, needsNoReply, renderUnanswered, heldRefusal, queuedFor, renderQueueNotice, renderQueued, answered, unaddressed, CHAT_RULES, RE_HELP, replyFor, renderReplied, PERSON_CHAT, PERSON_INBOX } from './duties.js'
 import { describeSubscription, describeWebhookTest, COALESCE_HELP, WEBHOOK_EVENTS } from './webhooks.js'
 import { registerWorkspaceTools, bytesFetcher, WORKSPACE_GUIDE_HOSTED } from './workspace-tools.js'
@@ -47,6 +49,11 @@ import { isDiff, hasEntry, listPaths, readPath, readPaths, textOf, notePresent,
 import { hostedRooms, hostedIn, newHosted } from './hosted-agents.js'
 import { turnSyncStep, ROOM_KEY } from './relay-turn-sync.js'
 import { describeSecretNames, SECRET_NAMES_DESCRIPTION } from './secret-names.js'
+import { quiltOf, seamRefusal, seamNote, seamStatus, seamFileRefusal, seamToolSpec, runSessionSeamTool, seamOnly, seamWorkflow, SEAM_SESSION_TOOLS, SEAM_GUIDE_HOSTED, GIT_TOOLS } from './session-seam.js'
+import { seamAccess } from './seam-access.js'
+import { releaseInSeam } from './seam-claims.js'
+import { releaseWords } from './release-words.js'
+import { LAYOUT_QUILT } from './session-layout3.js'
 import { TRANSCRIPT_DESCRIPTION, renderLines, readLines, inVoice, transcribeSetting, voiceStatusLines } from './voice.js'
 
 const FEED_CAP = 300
@@ -152,6 +159,18 @@ function takeStock (doc, me) {
 const linkInboxes = new WeakMap()
 const text = (t) => ({ content: [{ type: 'text', text: t }] })
 const fail = (t) => ({ content: [{ type: 'text', text: t }], isError: true })
+// A session that is a quilt, by its quilt's name (its slug; its id before the relay knows one), or null.
+const quiltName = (room) => { const q = quiltOf(room.meta); return q ? ((room.meta.quilt && room.meta.quilt.slug) || q) : null }
+// quilt_status in a session that is a quilt starts with how work goes there (session-seam.js).
+// Any other answer, the first in a session that is a quilt for this agent: its instructions may be from before the move.
+const withSeamLead = (r, quilt) => {
+  if (r && typeof r.then === 'function') return r.then((x) => withSeamLead(x, quilt))
+  return r && Array.isArray(r.content) ? { ...r, content: [{ type: 'text', text: `🧵 ${seamNote(quilt, { hosted: true })} This is how work lands here, whatever your instructions said before.` }, ...r.content] } : r
+}
+const withSeamNote = (r, quilt) => {
+  if (r && typeof r.then === 'function') return r.then((x) => withSeamNote(x, quilt))
+  return r && Array.isArray(r.content) ? { ...r, content: [{ type: 'text', text: seamNote(quilt, { hosted: true }) }, ...r.content.map((c) => c && c.type === 'text' ? { ...c, text: seamStatus(c.text) } : c)] } : r
+}
 
 function ago (ts) {
   const s = Math.max(0, Math.round((Date.now() - ts) / 1000))
@@ -208,7 +227,8 @@ function sessionTools (server, ctx) {
   // The branch document the agent works on (its store entry), or null for a room without branch documents.
   // The session's default branch may always start; any other new branch only for someone who may change files.
   const branchEntry = (room) => {
-    if (!room.branchDoc) return null
+    // At layout 3 there are no branch documents to work on: every tool but the file tools works on the room.
+    if (!room.branchDoc || room.meta.layout === LAYOUT_QUILT) return null
     const key = branchOf(room)
     const editor = room.resolveKey(key) === room.defaultKey || ctx.access(room)?.role !== 'viewer'
     return room.branchDoc(key, { by: me, editor })
@@ -217,9 +237,16 @@ function sessionTools (server, ctx) {
     // Hosted agents are in several sessions at once: `session` says which this call is about.
     const { session, ...args } = given || {}
     return stale(await ctx.withSession((room) => {
+    // A session that is a quilt has no GitHub path for agents: each GitHub tool names its Seam tool.
+    // At layout 3 its files are in squares, not branches: the file tools name Seam's (quilt_history reads Seam's log, quilt_project_rules main's rules).
+    const quilt = quiltName(room)
+    // quilt_release lets go of the agent's claims in Seam then (seam-claims.js), when it reaches Seam.
+    const seamRelease = name === 'quilt_release' && !!(ctx.seam && ctx.seam())
+    const refused = seamRefusal(name, quilt, { hosted: true }) || (quilt && room.meta.layout === LAYOUT_QUILT && FILE_TOOLS.has(name) && name !== 'quilt_history' && name !== 'quilt_project_rules' && !seamRelease ? seamFileRefusal(quilt) : null)
+    if (refused) return fail(refused)
     // A hosted agent with no branch of its own is pinned to the active branch by its first call
     // on files, so a read and the write after it never land on two different branches.
-    if (ctx.pin && FILE_TOOLS.has(name)) ctx.pin(room)
+    if (ctx.pin && FILE_TOOLS.has(name) && room.meta.layout !== LAYOUT_QUILT) ctx.pin(room)
     // The audit trail: which tool, on what (a path, a pattern or a task id; never contents).
     const caller = ctx.who(room)
     if (caller && caller.id && room.audit) {
@@ -234,7 +261,12 @@ function sessionTools (server, ctx) {
     // Changes the tool makes to the session (files, chat, the board) go in this agent's audit trail.
     const prev = room.auditAs
     room.auditAs = caller && caller.id
-    try { return queueNote(room, fn(args || {}, parts)) } finally { room.auditAs = prev }
+    try {
+      const r = queueNote(room, fn(args || {}, parts))
+      // The first answer in a session that is a quilt says how work lands there (quilt_status always does).
+      const once = quilt && ctx.seamOnce ? ctx.seamOnce(room) : false
+      return name === 'quilt_status' && quilt ? withSeamNote(r, quilt) : once ? withSeamLead(r, quilt) : r
+    } finally { room.auditAs = prev }
     }, session))
   })
   if (ctx.updates) {
@@ -342,10 +374,18 @@ function sessionTools (server, ctx) {
       with_diff: z.boolean().optional().describe('Include each change\'s diff (capped per change)'),
       limit: z.number().int().min(1).max(200).optional().describe('How many of the newest matching changes (default 30)')
     }
-  }, ({ path: p, by, since, task, with_diff, limit }, { room }) => {
+  }, async ({ path: p, by, since, task, with_diff, limit }, { room }) => {
     const from = parseSince(since)
     if (from === undefined) return fail('since: use a duration like 2h or 3d, "today", "yesterday", or a date.')
-    const list = queryHistory(historyOf(room).entries(), { path: p ? cleanPath(p) : '', by, since: from ?? undefined, task, limit: limit || 30 })
+    const q = process.env.QUILT_SOURCE_URL && room.meta && room.meta.quilt_id ? room.meta.quilt : null
+    const own = legacyTail(historyOf(room).entries(), { at: q && q.at, history: !!(q && q.history) })
+    // Linked to a quilt (16: the session became one, or shadows one in step 1): Seam's log plus this record.
+    const link = room.quiltHistoryLink ? room.quiltHistoryLink() : null
+    if (link) {
+      const r = await linkedHistory({ seam: link.seam, quilt: link.quilt, entries: own, query: { path: p ? cleanPath(p) : '', by, since: from ?? undefined, task, limit: limit || 30, withDiff: !!with_diff } })
+      return text(`${formatHistory(r.list, { withDiff: !!with_diff })}${r.note ? `\n\n${r.note}` : ''}`)
+    }
+    const list = queryHistory(own, { path: p ? cleanPath(p) : '', by, since: from ?? undefined, task, limit: limit || 30 })
     return text(formatHistory(list, { withDiff: !!with_diff }))
   })
 
@@ -413,6 +453,18 @@ function sessionTools (server, ctx) {
     return text(`${branchesMarkdown(br, { limit: 40 })}\n\n${BRING_IN_NOTE}`)
   })
 
+  // Seam (Seam's plans/quilt-source-control/16), behind QUILT_SOURCE_URL: what making this session a
+  // quilt would do. Only the dry run: the move itself is the owner's, from the app.
+  if (process.env.QUILT_SOURCE_URL) {
+    tool('quilt_migrate_session', {
+      description: MIGRATE_SESSION_DESCRIPTION,
+      inputSchema: { dry_run: z.literal(true).optional().describe('Always true: report what would happen, change nothing.') }
+    }, (_, { room }) => {
+      if (!room.quiltPlan) return fail('This session cannot become a quilt here.')
+      try { return text(describeQuiltPlan(room.quiltPlan(ctx.access(room)))) } catch (e) { return fail(e.message) }
+    })
+  }
+
   const taskMap = (doc) => doc.getMap('tasks')
 
   const reader = () => ({ name: me, tool: ctx.tool(), asAi: false, agent: true })
@@ -463,6 +515,8 @@ function sessionTools (server, ctx) {
     : pickChecklist(files.get('AGENTS.md')?.toString(), files.get('CLAUDE.md')?.toString())
   /** The project's rules (project-rules.js) on the agent's branch, a diff branch's from git where the session left them. */
   const rulesFor = async (room, branch, files) => {
+    // In squares (layout 3): main's rules on Seam, read with the room's read token (the branch documents are as they were at the move).
+    if (room.meta.layout === LAYOUT_QUILT && quiltOf(room.meta)) return rulesOnSeam(room)
     if (!branch || !isDiff(branch)) return projectRules({ list: [...files.keys()], read: (p) => files.get(p)?.toString() ?? null })
     const list = [...(await listPaths(room, branch.key, branch)).keys()]
     const got = new Map()
@@ -475,6 +529,20 @@ function sessionTools (server, ctx) {
     }
     return projectRules({ list, read: (p) => got.get(p) ?? null })
   }
+  const rulesOnSeam = async (room) => {
+    const seam = room.quiltReadClient ? room.quiltReadClient() : null
+    if (!seam) throw new Error(`The session has no read token for ${quiltName(room)}, so its rules can't be read here: its owner links it to Seam again. Meanwhile read AGENTS.md with seam_cat.`)
+    const q = room.meta.quilt_id
+    const list = ((await seam.tree(q, 'main')).entries || []).filter((e) => e && e.path && e.mode !== 'dir').map((e) => e.path)
+    const got = new Map()
+    for (let round = 0; round < 4; round++) {
+      const asked = new Set()
+      const r = projectRules({ list, read: (p) => { if (got.has(p)) return got.get(p); asked.add(p); return null } })
+      if (!asked.size) return r
+      for (const p of asked) got.set(p, await seam.cat(q, 'main', p).then((x) => Buffer.from(x.content || '', 'base64').toString('utf8'), () => null))
+    }
+    return projectRules({ list, read: (p) => got.get(p) ?? null })
+  }
   tool('quilt_move_task', {
     description: 'Move a task on the shared board. "doing" when you start it: you get a briefing (its files, recent changes to them, claims, the project\'s checks). ' +
       '"qa" when you finish implementing and testing: requires `qaNotes` (what changed and how you self-validated); without it the move is refused. ' +
@@ -514,6 +582,7 @@ function sessionTools (server, ctx) {
         const all = historyOf(room).entries()
         const history = (tf.length ? all.filter((e) => tf.includes(e.path)) : all).slice(-8)
         const claims = claimsOf(room).filter((c) => !tf.length || tf.some((f) => globMatcher(c.pattern)(f)))
+        if (quiltOf(room.meta)) return text(pickupBrief({ task: { ...task, comments: readComments(doc.getMap('taskComments'), task.id) }, history, claims, checklist: await checklistOf(files, room, null), me, workflow: seamWorkflow(TASK_WORKFLOW, { hosted: true }) }))
         const onto = branchForHostedTask(room, task)
         return text(pickupBrief({ task: { ...task, comments: readComments(doc.getMap('taskComments'), task.id) }, history, claims, checklist: await checklistOf(files, room, branchEntry(room)), me }) + (onto ? `\nYou are on ${onto} now (Quilt made it for this task, a copy of ${room.defaultKey}'s files): write your files here and quilt_git_commit them; the pull request opens by itself. Move the task to QA when it is done and tested.` : ''))
       }
@@ -1139,10 +1208,24 @@ function sessionTools (server, ctx) {
     return text(`Claimed ${pattern.trim()}. Release it with quilt_release when done.`)
   })
 
+  const releaseHostedInSeam = async (room, pattern) => {
+    const quilt = quiltName(room) && room.meta.quilt_id
+    const access = ctx.seam && ctx.seam()
+    if (!quilt || !access) return fail(seamFileRefusal(quiltName(room)))
+    try {
+      const asked = room.claimRequest(who(room), { op: 'quilt-claims' })
+      const { gone, ...r } = await releaseInSeam({ access, api: process.env.QUILT_SOURCE_URL, quilt, asked, pattern: pattern ? pattern.trim() : '*' })
+      if (gone.length) room.claimRequest(who(room), { op: 'quilt-released', ids: gone })
+      return text(releaseWords(r, { cli: 'quilt_release' }))
+    } catch (err) { return fail(err.message) }
+  }
+
   tool('quilt_release', {
     description: 'Release a claim (or all of your claims when no pattern is given).',
     inputSchema: { pattern: z.string().optional() }
   }, ({ pattern }, { room }) => {
+    // At layout 3 the claims are Seam's: the agent lets go of its own there, as itself.
+    if (room.meta.layout === LAYOUT_QUILT) return releaseHostedInSeam(room, pattern)
     // Releasing everything keeps boxes: a box opens when it's committed (quilt_git_commit) or unpacked (quilt_unpack).
     const mine = claimsOf(room).filter((c) => c.by === me && (pattern ? c.pattern === pattern.trim() : !c.box))
     // A file someone waits for is handed off, not released.
@@ -1403,6 +1486,13 @@ export function hostedWorkspaceAccess ({ apiUrl, pass, fetch: fetchImpl = global
   return { call, fetchBytes: bytesFetcher(fetchImpl, { timeoutMs: WORKSPACE_TRANSFER_TIMEOUT_MS }), put, saveDir: null, readLocal: null }
 }
 
+/** A request's JSON body, read here (the transport takes it parsed). */
+async function readJsonBody (req) {
+  const chunks = []
+  for await (const c of req) chunks.push(c)
+  return JSON.parse(Buffer.concat(chunks).toString('utf8'))
+}
+
 async function serve (mcp, req, res, body) {
   const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined, enableJsonResponse: true })
   res.on('close', () => { transport.close().catch(() => {}); mcp.close().catch(() => {}) })
@@ -1419,11 +1509,30 @@ async function serve (mcp, req, res, body) {
  */
 export async function handleHostedMcp ({ req, res, pass, relay, workspaces = null, secrets = null, body = undefined }) {
   const image = String(req.headers['x-quilt-image'] || '').trim()
-  // The library's guide is part of the instructions only when its tools are offered.
-  const mcp = new McpServer({ name: 'quilt', version: '0.2.0' }, { instructions: (workspaces ? `${HOSTED_INSTRUCTIONS}\n\n${WORKSPACE_GUIDE_HOSTED}` : HOSTED_INSTRUCTIONS) })
   const me = pass.name
   const account = `${pass.kind}:${pass.sub}`
   const touched = new Set()
+  // Whether the agent's sessions on this machine are quilts (some, all): an agent whose sessions all
+  // are reads only Seam's way, with no git in its instructions or tool list (session-seam.js).
+  const quilts = (() => {
+    let any = false; let all = true; let seen = 0
+    for (const name of hostedRooms(relay.hosted.get(account))) {
+      if (relay.roomEnded(name)) continue
+      const room = relay.getRoom(name)
+      if (!room || !room.exists) continue
+      touched.add(room)
+      seen++
+      if (quiltOf(room.meta)) any = true; else all = false
+    }
+    return { any, all: any && all && seen > 0 }
+  })()
+  // The library's guide is part of the instructions only when its tools are offered.
+  const base = quilts.all ? `${seamOnly(HOSTED_INSTRUCTIONS)} In a session that is a quilt: ${SEAM_GUIDE_HOSTED}` : HOSTED_INSTRUCTIONS
+  const mcp = new McpServer({ name: 'quilt', version: '0.2.0' }, { instructions: (workspaces ? `${base}\n\n${WORKSPACE_GUIDE_HOSTED}` : base) })
+  // Every tool it registers, so the git-era ones can be left out for an agent whose sessions are all quilts.
+  const registered = new Map()
+  const register = mcp.registerTool.bind(mcp)
+  mcp.registerTool = (name, spec, handler) => { const t = register(name, spec, handler); registered.set(name, t); return t }
   const done = () => { for (const room of touched) if (room && !room.conns.size && room.onEmpty) room.onEmpty() }
   res.on('close', done)
   // Which sessions the agent is in, for the accounts API (x-quilt-rooms), and which one this
@@ -1521,6 +1630,8 @@ export async function handleHostedMcp ({ req, res, pass, relay, workspaces = nul
     multi: true, // every tool takes `session`
     who: () => ({ name: me, id: account }),
     kind: pass.kind === 'agent' ? 'agent' : 'human',
+    // This agent to Seam (its pass, traded for an agent token), for what it does there as itself.
+    seam: () => process.env.QUILT_SOURCE_URL && pass.kind === 'agent' && req.headers['x-quilt-pass'] ? hostedSeam(account, String(req.headers['x-quilt-pass'])) : null,
     access: (room) => room.hostedAccess(pass),
     branch: (room) => room.hostedBranch(account),
     setBranch: (room, key, opts) => room.setHostedBranch(account, key, opts),
@@ -1561,6 +1672,14 @@ export async function handleHostedMcp ({ req, res, pass, relay, workspaces = nul
     } : null,
     updates: relay.updates || null,
     image: () => image,
+    // Whether this agent is yet to be told the Seam way in `room` (once per quilt, kept with its record there).
+    seamOnce: (room) => {
+      const r = hostedIn(relay.hosted.get(account), room.name)
+      if (!r || !room.meta.quilt_id || r.seamTold === room.meta.quilt_id) return false
+      r.seamTold = room.meta.quilt_id
+      relay.saveHosted()
+      return true
+    },
     withSession: (fn, session) => {
       const c = current(session)
       return c.error ? fail(c.error) : fn(c.room)
@@ -1661,6 +1780,7 @@ export async function handleHostedMcp ({ req, res, pass, relay, workspaces = nul
   }, async ({ branch, create, session }) => {
     const c = current(session)
     if (c.error) return fail(c.error)
+    { const no = seamRefusal('quilt_git_branch', quiltName(c.room), { hosted: true }); if (no) return fail(no) }
     const room = c.room
     if (!branch) {
       const members = []
@@ -1708,6 +1828,7 @@ export async function handleHostedMcp ({ req, res, pass, relay, workspaces = nul
   }, async ({ session }) => {
     const c = current(session)
     if (c.error) return fail(c.error)
+    { const no = seamRefusal('quilt_sync_branch', quiltName(c.room), { hosted: true }); if (no) return fail(no) }
     const room = c.room
     if (room.meta.layout !== 2 || !room.syncUpstreamNow) return fail('This session has no branches on the relay.')
     try {
@@ -1723,6 +1844,7 @@ export async function handleHostedMcp ({ req, res, pass, relay, workspaces = nul
   }, ({ token, session }) => {
     const c = current(session)
     if (c.error) return fail(c.error)
+    { const no = seamRefusal('quilt_github_token', quiltName(c.room), { hosted: true }); if (no) return fail(no) }
     if (!c.access || !c.access.owner) return fail('Only the session owner can set the GitHub token: ask them.')
     try {
       const r = c.room.setGithubToken(token)
@@ -1778,11 +1900,53 @@ export async function handleHostedMcp ({ req, res, pass, relay, workspaces = nul
   }
 
   sessionTools(mcp, ctx)
+  // Seam's tools for an agent in a session that is a quilt (session-seam.js), as itself: its
+  // pass, traded once for an agent token of its own (seam-access.js). Only while one of its
+  // sessions here is a quilt, so every other agent's tool list stays as it was.
+  const rawPass = String(req.headers['x-quilt-pass'] || '')
+  // Hidden from the list, but a call still answers with the Seam way: an agent's client keeps the
+  // list it read before its session moved into Seam, and a hidden tool would answer only "disabled".
+  if (quilts.all) {
+    if (body === undefined && req.method === 'POST') {
+      try { body = await readJsonBody(req) } catch { res.writeHead(400, { 'content-type': 'application/json' }); res.end(JSON.stringify({ jsonrpc: '2.0', error: { code: -32700, message: 'Parse error' }, id: null })); return }
+    }
+    const calls = [].concat(body || []).some((m) => m && m.method === 'tools/call')
+    if (!calls) for (const [name, t] of registered) if (GIT_TOOLS.has(name)) t.disable()
+  }
+  if (process.env.QUILT_SOURCE_URL && pass.kind === 'agent' && rawPass && quilts.any) {
+    const seam = hostedSeam(account, rawPass)
+    for (const name of SEAM_SESSION_TOOLS) {
+      const spec = seamToolSpec(name, { hosted: true })
+      mcp.registerTool(name, { ...spec, inputSchema: spec.inputSchema.extend({ session: SESSION_ARG }) }, async ({ session, ...args } = {}) => {
+        const c = current(session)
+        if (c.error) return fail(c.error)
+        const quilt = quiltOf(c.room.meta)
+        if (!quilt) return fail('This session is not a quilt: its source control is git, as quilt_status says.')
+        let client
+        try { client = (await seam.client(quilt)).client } catch (e) { return fail(e.message) }
+        return runSessionSeamTool(name, args, { client, quilt, hosted: true })
+      })
+    }
+  }
   // The library works whether or not the agent is in a session (it never touches relay.hosted).
   if (workspaces) registerWorkspaceTools(mcp, { ...hostedWorkspaceAccess(workspaces), webhook: false })
   await serve(mcp, req, res, body)
 }
 
+// Each hosted agent's way into Seam, kept between its requests (each is a new MCP server): the
+// agent token it traded its pass for lasts hours, while passes last minutes.
+const hostedSeams = new Map() // account -> { access, pass }
+function hostedSeam (account, pass) {
+  let e = hostedSeams.get(account)
+  if (!e) {
+    e = { pass }
+    e.access = seamAccess({ api: () => process.env.QUILT_SOURCE_URL, credential: async () => `QuiltPass ${e.pass}` })
+    hostedSeams.set(account, e)
+  }
+  e.pass = pass
+  return e.access
+}
+
 /**
  * Handles one MCP request (stateless: a fresh server per request) for the older
  * link-based flow: a browser's token tied to a room by /agent/link.

package/src/relay-outbound.js

@@ -50,7 +50,7 @@ const plural = (k, w) => `${k} ${w}${k === 1 ? '' : 's'}`
 
 /** Whether branch `key` of the room syncs live to GitHub: the mirror is on, the owner hasn't switched it off, and the relay can write to the repository. */
 export function liveSyncOn (room, key) {
-  if (!room.cfg || !room.cfg.gitSync || !room.mirrors || room.meta.githubSync === false) return false
+  if (!room.cfg || !room.cfg.gitSync || !room.mirrors || room.meta.githubSync === false || room.meta.syncStopped) return false
   const rec = upstreamsOf(room)[key]
   if (!rec || !rec.repo || !rec.ref) return false
   // Agents' policy "off" (addendum 16.7): an agent's own branch stays in the session; a person adopts its work (adoptBranch).

package/src/relay-prune.js

@@ -55,8 +55,11 @@ export const lastActive = (b) => Math.max(Number(b && (b.used || b.seen)) || 0,
 /** Branches nobody has worked on for INACTIVE_MS: not the default, not main or master, not in use. */
 export function inactiveBranches (room, now = Date.now(), inactiveMs = INACTIVE_MS) {
   const on = inUse(room, now)
+  // A quilt's squares' live documents (layout 3) stay: their squares decide when they go. Agents'
+  // own branches are named quilt/<agent>/… too, so only the keys the room lists are kept.
+  const live = new Set(Object.values(room.meta.quilt?.live || {}))
   return Object.entries(room.meta.branches)
-    .filter(([k, b]) => k !== room.defaultKey && !TRUNKS.has(k) && !on.has(k) && now - lastActive(b) >= inactiveMs)
+    .filter(([k, b]) => k !== room.defaultKey && !TRUNKS.has(k) && !live.has(k) && !on.has(k) && now - lastActive(b) >= inactiveMs)
     .map(([k]) => k)
 }
 

package/src/release-words.js

@@ -4,7 +4,7 @@
 
 const list = (xs) => xs.length === 1 ? xs[0] : `${xs.slice(0, -1).join(', ')} and ${xs[xs.length - 1]}`
 
-/** r: { released, held?, branches?, coveredBy?, holder?, yours? }; `cli`: the command to name (quilt release, or quilt_release). */
+/** r: { released, held?, seam? (claims are Seam's: layout 3), branches?, coveredBy?, holder?, yours? }; `cli`: the command to name (quilt release, or quilt_release). */
 export function releaseWords (r, { cli = 'quilt release' } = {}) {
   const n = (r && r.released) || 0
   let s = `Released ${n} claim(s)${r && r.branches && r.branches.length ? ` (on ${list([...new Set(r.branches)])})` : ''}.`
@@ -13,6 +13,6 @@ export function releaseWords (r, { cli = 'quilt release' } = {}) {
       ? ` That path is not a claim of its own: your claim on ${r.coveredBy} covers it. Let go of that with ${cli} ${r.coveredBy}.`
       : ` That path is not a claim of its own: ${r.holder || 'someone'}'s claim on ${r.coveredBy} covers it; only they (or the session owner) can let go of it.`
   }
-  if (r && r.held && r.held.length) s += ` Kept ${r.held.join(', ')}: someone is waiting for ${r.held.length === 1 ? 'it' : 'them'}; hand off with quilt_handoff.`
+  if (r && r.held && r.held.length) s += ` Kept ${r.held.join(', ')}: someone is waiting for ${r.held.length === 1 ? 'it' : 'them'}; ${r.seam ? `hand it on in Seam with a note (seam claim handoff ${r.held[0]} --note "…")` : 'hand off with quilt_handoff'}.`
   return s
 }

package/src/runner.js

@@ -22,6 +22,8 @@ import { keptInProject } from './agent-join.js'
 
 export { JOIN_HOST }
 
+const STATUS_FILE_MS = 1500 // .quilt/STATUS.md is written at most this often
+
 /**
  * An invite link: https://join.heyquilt.com/<room>#<secret> for sessions on Quilt's relay,
  * or https://<relay>/join/<room>#<secret> for any other relay (development relays).
@@ -101,7 +103,7 @@ export async function describeOtherSync (dir) {
  * optionally overrides the relay address given out in invites (e.g. a public
  * tunnel URL when the relay runs on this machine).
  */
-export async function runSession ({ dir, conn, name, tool, toolGuessed = false, color = null, shareByDefault = true, summarizeByDefault = false, joined = false, prefer = 'remote', inviteServer, onLog, onFatal, onDebug, kind = 'human', agentFeed = true, readerOptions = {}, passes = null, identity = null, startName = '', startAgentCommits = '', workspace = '', apiAuth = null }) {
+export async function runSession ({ dir, conn, name, tool, color = null, shareByDefault = true, summarizeByDefault = false, joined = false, prefer = 'remote', inviteServer, onLog, onFatal, onDebug, kind = 'human', agentFeed = true, readerOptions = {}, passes = null, identity = null, startName = '', startAgentCommits = '', newSession = false, workspace = '', apiAuth = null }) {
   dir = path.resolve(dir)
   if (!/^wss?:\/\//.test(conn.server)) throw new Error('The relay address must start with ws:// or wss://')
   if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true })
@@ -139,7 +141,7 @@ export async function runSession ({ dir, conn, name, tool, toolGuessed = false,
 
   // An agent whose keys are kept in its project (quilt agent join --here) is in a sandbox that is cleaned up after every run: it works in turns.
   const turns = kind === 'agent' && keptInProject(name)
-  const session = new Session({ dir, ...conn, name, tool, toolGuessed, color, prefer, kind, shareAgent, identity, passes, startName, startAgentCommits, workspace: savedWorkspace, turns })
+  const session = new Session({ dir, ...conn, name, tool, color, prefer, kind, shareAgent, identity, passes, startName, startAgentCommits, newSession, workspace: savedWorkspace, turns, apiAuth })
   const summarizer = () => createSummarizer({ onWarn: (msg) => session.log(`✂️  ${msg}`) })
   if (summarize) session.summarizer = summarizer()
   session.taskTitler = createTaskTitler({ onWarn: (msg) => session.log(`📋 ${msg}`) })
@@ -147,12 +149,24 @@ export async function runSession ({ dir, conn, name, tool, toolGuessed = false,
   if (onDebug) session.on('debug', onDebug)
   session.on('fatal', (err) => onFatal && onFatal(err))
   const statusFile = path.join(dir, '.quilt', 'STATUS.md')
+  // Written at most every STATUS_FILE_MS: each write works out the whole status again.
+  let statusWrite = null
   session.on('status-changed', () => {
-    // Read config fresh: the workspace can change after the session started (the app's
-    // "move to workspace", or a later quilt_start_session call writing it here).
-    try { fs.writeFileSync(statusFile, renderStatus({ ...session.status(), workspace: readConfig(dir)?.workspace })) } catch {}
+    if (statusWrite) return
+    statusWrite = setTimeout(() => {
+      statusWrite = null
+      if (session.stopped) return
+      // Read config fresh: the workspace can change after the session started (the app's
+      // "move to workspace", or a later quilt_start_session call writing it here).
+      try { fs.writeFileSync(statusFile, renderStatus({ ...session.status(), workspace: readConfig(dir)?.workspace })) } catch {}
+    }, STATUS_FILE_MS)
+    statusWrite.unref?.()
   })
 
+  // Work for this person's AI can run on its own here, when they turned that on (autowork.js). It
+  // listens before the session starts: what was written to their cloud AI while it was away arrives
+  // as the session syncs, before start() returns, and is its work.
+  autowork().attach(session)
   try {
     await session.start({ waitTimeoutMs: 15000 })
   } catch (err) {
@@ -164,8 +178,6 @@ export async function runSession ({ dir, conn, name, tool, toolGuessed = false,
   session.on('identity', ({ name }) => saveName(name))
   // apiAuth: { api, token } for the accounts API as this session's person or agent (secrets, `quilt run`).
   const control = await startControl(session, { invite, viewInvite, joined, apiAuth })
-  // Work for this person's AI can run on its own here, when they turned that on (autowork.js).
-  autowork().attach(session)
   remember({ dir, room: conn.room, server: conn.server, name: session.name, tool, kind, workspace: savedWorkspace })
 
   // Every AI tool on this computer can reach Quilt (its MCP server, by absolute path), with nothing to set up.
@@ -198,6 +210,7 @@ export async function runSession ({ dir, conn, name, tool, toolGuessed = false,
       if (stopped) return
       stopped = true
       if (readers) readers.stop()
+      clearTimeout(statusWrite)
       await control.close()
       await session.stop()
     }

package/src/seam-access.js

@@ -0,0 +1,97 @@
+// Who each AI in a session that is a quilt is to Seam, with nothing set up by hand (Seam's
+// plans/quilt-source-control/11.5). Seam takes Quilt's sign-ins through Quilt's identity service
+// (GET /v1/seam/me on the accounts API): a person's Quilt sign-in is that person
+// (person:<user id>), and a person's AI sessions on their computer are the person; an agent's
+// Quilt key or pass (a cloud AI, a hosted agent) is that agent (agent:<id>), working for its
+// person. SEAM_TOKEN, when set, is used as it is.
+//
+// An agent's own key only reads on Seam: it writes with an agent token. This trades the key for
+// one per quilt, for the squares it works in (merge when its person holds merge, else write),
+// and keeps it until a quarter of an hour before it ends: never once per call, which would
+// reach Seam's 20 live tokens per agent. A token for other squares is revoked when a new one is made.
+import { quiltClient } from '@heyquilt/seam/lib/quilts/client.js'
+
+export const RENEW_MS = 15 * 60_000
+
+/** Whether a credential is an agent's own (a Quilt agent key or pass, or a Seam agent's key from `seam agent new`), which trades for an agent token. */
+export const isAgentKey = (token) => /^(?:QuiltPass |qa_|sak_)/.test(String(token || ''))
+
+/**
+ * Seam clients for one member, on Seam at `api` (a URL, or a function giving it at call time).
+ * `credential()` resolves to the token they sign in to Seam with
+ * (or null). `client(quilt, squares)` is a client acting as them in `quilt`; for an agent, with
+ * a token that reaches `squares` (ids; none: the squares it holds); one that only reads (`read`)
+ * takes the token it holds there already, whatever its squares. Its `token` is the one it uses.
+ */
+export function seamAccess ({ api, credential, make = quiltClient, now = Date.now, fetch: fetchImpl = globalThis.fetch }) {
+  const minted = new Map() // quilt -> { token, id, expires_at, max_level, squares }
+  const where = () => typeof api === 'function' ? api() : api
+  // A trade refused 404: Seam finds no quilt this agent reaches through the person it works for (an
+  // agent needs no member row of its own: Seam takes the person's). So the person is not in the quilt,
+  // or the quilt is gone: the agent is told who that person is to Seam, to pass on.
+  async function noQuilt (quilt, key) {
+    let person = ''
+    try {
+      const res = await fetchImpl(`${String(where()).replace(/\/+$/, '')}/v1/me`, { headers: { authorization: /^QuiltPass /.test(key) ? key : `Bearer ${key}` }, signal: AbortSignal.timeout(10_000) })
+      const me = res.ok ? await res.json() : null
+      if (me && typeof me.on_behalf_of === 'string') person = me.on_behalf_of
+    } catch {}
+    const who = person || 'the person you work for'
+    return `Seam finds no quilt ${quilt} that the person this agent works for (${who}) is in: they are not a member of it, or it was deleted. Tell them: a quilt admin adds them once (seam quilts add ${person || 'person:<their id>'} --level write --quilt ${quilt}), and this agent then works there for them.`
+  }
+  async function mint (quilt, key, squares) {
+    const own = make({ api: where(), token: key })
+    const was = minted.get(quilt)
+    const body = { squares: squares && squares.length ? squares : 'own' }
+    let t
+    try { t = await own.createAgentToken(quilt, { ...body, max_level: 'merge' }) } catch (err) {
+      if (err.status === 404) throw Object.assign(new Error(await noQuilt(quilt, key)), { status: 404, code: 'no_quilt' })
+      // Its person holds write, not merge: a token that writes, and merges wait for a person.
+      if (err.status !== 403) throw err
+      t = await own.createAgentToken(quilt, { ...body, max_level: 'write' })
+    }
+    const kept = { token: t.token, id: t.id, expires_at: Number(t.expires_at) || now() + 8 * 3600e3, max_level: t.max_level || 'write', squares: body.squares }
+    minted.set(quilt, kept)
+    if (was && was.id && was.id !== kept.id && own.revokeAgentToken) own.revokeAgentToken(quilt, was.id).catch(() => {})
+    return kept
+  }
+  return {
+    async client (quilt, squares = [], { read = false, retry } = {}) {
+      const at = where()
+      if (!at) throw new Error('Seam is not on for this app (QUILT_SOURCE_URL is not set).')
+      const key = await credential()
+      if (!key) throw new Error('This session has no Quilt sign-in to reach Seam with: sign in to Quilt (quilt login) and join again.')
+      // `retry: false`: a read that has somewhere else to go (quilt_history: the relay) is not held up by a Seam that is down.
+      const made = (token) => make({ api: at, token, ...(retry === false ? { retry: false } : {}) })
+      if (!isAgentKey(key) || !quilt) return { client: made(key), token: key, person: !isAgentKey(key) }
+      // An agent's own key does not even read a quilt it is not a member of (it reaches it through
+      // its person only with a token), so reading uses whichever token it holds there now.
+      const want = squares && squares.length ? squares : 'own'
+      let t = minted.get(quilt)
+      const fresh = t && t.expires_at - now() >= RENEW_MS
+      if (!fresh || (!read && JSON.stringify(t.squares) !== JSON.stringify(want))) t = await mint(quilt, key, squares)
+      return { client: made(t.token), token: t.token, level: t.max_level, person: false }
+    },
+    /** Forgets the tokens it made (a refused one is made again on the next call). */
+    forget () { minted.clear() }
+  }
+}
+
+/** The credential a folder's session reaches Seam with: SEAM_TOKEN, else its Quilt sign-in (`apiAuth`: the person's, or its agent's key). */
+export function sessionCredential ({ env = process.env, apiAuth = null, account = () => null } = {}) {
+  return async () => {
+    if (env.SEAM_TOKEN) return env.SEAM_TOKEN
+    if (apiAuth) { try { const a = await apiAuth(); if (a && a.token) return a.token } catch {} }
+    const acc = account()
+    return (acc && acc.token) || null
+  }
+}
+
+/** Who `token` is to Seam at `api` (GET /v1/me): { member_id, kind, on_behalf_of? }, or null when Seam can't say. */
+export async function seamWhoAmI (api, token, { fetch: fetchImpl = globalThis.fetch } = {}) {
+  try {
+    const res = await fetchImpl(`${String(api).replace(/\/+$/, '')}/v1/me`, { headers: { authorization: /^QuiltPass /.test(token) ? token : `Bearer ${token}` }, signal: AbortSignal.timeout(10_000) })
+    const me = res.ok ? await res.json() : null
+    return me && typeof me.member_id === 'string' ? me : null
+  } catch { return null }
+}

package/src/seam-claims.js

@@ -0,0 +1,53 @@
+// Letting go of claims in a session that is a quilt (layout 3): its claims are Seam's, and each
+// member lets go of theirs in Seam as themselves (Session.releaseInSeam). The move into Seam made
+// the session's claims as the member who moved it (Seam makes a claim only as its caller), so the
+// relay keeps whose each was (`moved`, server.js quilt-claims): those are their claimant's to let
+// go of, not the mover's, and the session owner may let go of any one named.
+import { seamWhoAmI } from './seam-access.js'
+
+/**
+ * Which of Seam's `claims` this member lets go of for `pattern` ('*': all of theirs): { release,
+ * notYours: [{ pattern, holder }] }. `me`: the member's Seam id; `moved`: the relay's records of the
+ * move's claims ({ id, by, mine }); `owner`: the session owner, who lets go of any claim it names.
+ */
+export function claimsToRelease ({ claims = [], me = '', moved = [], pattern = '*', owner = false }) {
+  const all = !pattern || pattern === '*'
+  const rec = new Map((moved || []).map((m) => [m.id, m]))
+  const release = []
+  const notYours = []
+  for (const c of claims || []) {
+    if (!c || c.conflict || (!all && c.pattern !== pattern)) continue
+    const m = rec.get(c.id)
+    const theirs = m ? !!m.mine : !!me && c.holder === me
+    if (theirs || (owner && !all)) release.push(c)
+    else if (!all) notYours.push({ pattern: c.pattern, holder: m ? `${m.by || 'someone'} (moved into Seam with the session)` : (c.holder_name || c.holder) })
+  }
+  return { release, notYours }
+}
+
+/**
+ * Lets go of this member's claims for `pattern` in Seam: `access` is the member's seamAccess (a
+ * person's sign-in, or an agent's key traded for a token that reaches the claims' squares); `asked`
+ * the relay's quilt-claims answer ({ moved, owner }). Resolves to { released, seam: true, held?,
+ * gone: [claim ids let go of] }; throws naming the holder when the one named is someone else's.
+ */
+export async function releaseInSeam ({ access, api, quilt, asked = {}, pattern = '*' }) {
+  const { client: reader, token } = await access.client(quilt, [], { read: true })
+  const me = await seamWhoAmI(api, token)
+  const got = await reader.claims(quilt)
+  const claims = Array.isArray(got) ? got : (got && got.claims) || []
+  const pick = claimsToRelease({ claims, me: (me && me.member_id) || '', moved: asked.moved, owner: !!asked.owner, pattern })
+  if (!pick.release.length && pick.notYours.length) throw new Error(`${pattern} is claimed by ${pick.notYours[0].holder}; only they can release it (or the session owner)`)
+  if (!pick.release.length) return { released: 0, seam: true, gone: [] }
+  const { client } = await access.client(quilt, [...new Set(pick.release.map((c) => c.square_id))])
+  const gone = []
+  const held = []
+  for (const c of pick.release) {
+    try { await client.unclaim(quilt, c.square_id, c.id); gone.push(c.id) } catch (err) {
+      if (err.code === 'claim_queued') { held.push(c.pattern); continue }
+      if (err.status === 404) { gone.push(c.id); continue } // let go of already
+      throw err
+    }
+  }
+  return { released: gone.length, seam: true, gone, ...(held.length ? { held } : {}) }
+}

package/src/seam-url.js

@@ -0,0 +1,15 @@
+// Where the app and the CLI find Seam, Quilt's source control (Seam's plans/quilt-source-control/16).
+// On by default: QUILT_SOURCE_URL names another Seam, and `off` (or an empty value) turns it off.
+// Only the app's side reads this. The relay and the API read QUILT_SOURCE_URL themselves and stay
+// off without it. It changes nothing for a session the relay does not say is linked to a quilt.
+
+export const SEAM_URL = 'https://api.seam.heyquilt.com'
+
+/** The app's Seam API, or '' when it is turned off. */
+export function appSeamUrl (env = process.env) {
+  const v = env ? env.QUILT_SOURCE_URL : undefined
+  if (v === undefined || v === null) return SEAM_URL
+  const t = String(v).trim()
+  if (!t || /^(off|0|false|no|none)$/i.test(t)) return ''
+  return t.replace(/\/+$/, '')
+}