heyquilt 0.0.1 → 0.3.90

package/src/git-hook.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+// The hooks of the relay's git views (relay-githttp.js): git runs this for a push into a session's
+// view, with the ref updates on stdin. The relay decides (QUILT_HOOK_URL, a secret only this relay
+// process knows): before the refs move ("pre-receive") it checks the push and puts it on GitHub;
+// after ("post-receive") it sets the view's branches back to what GitHub has. What the relay says is
+// printed for the person or agent pushing ("remote: …").
+import http from 'node:http'
+import path from 'node:path'
+
+// git gives hooks some paths relative to the repository (GIT_DIR=.): the relay needs them whole.
+const whole = (p) => (p ? path.resolve(process.cwd(), p) : '')
+const wholeList = (l) => String(l || '').split(path.delimiter).filter(Boolean).map(whole).join(path.delimiter)
+
+const phase = process.argv[2] === 'post-receive' ? 'post' : 'pre'
+let input = ''
+process.stdin.setEncoding('utf8')
+process.stdin.on('data', (d) => { input += d })
+process.stdin.on('end', () => {
+  const url = process.env.QUILT_HOOK_URL
+  if (!url) { process.stderr.write('Quilt: this push did not come through the relay.\n'); process.exit(phase === 'pre' ? 1 : 0) }
+  const body = JSON.stringify({
+    phase,
+    room: process.env.QUILT_ROOM || '',
+    who: process.env.QUILT_WHO || '',
+    name: process.env.QUILT_WHO_NAME || '',
+    updates: input,
+    env: {
+      GIT_DIR: whole(process.env.GIT_DIR || '.'),
+      GIT_OBJECT_DIRECTORY: whole(process.env.GIT_OBJECT_DIRECTORY),
+      GIT_ALTERNATE_OBJECT_DIRECTORIES: wholeList(process.env.GIT_ALTERNATE_OBJECT_DIRECTORIES),
+      GIT_QUARANTINE_PATH: whole(process.env.GIT_QUARANTINE_PATH)
+    }
+  })
+  const req = http.request(url, { method: 'POST', headers: { 'content-type': 'application/json', 'content-length': Buffer.byteLength(body), authorization: `Bearer ${process.env.QUILT_HOOK_TOKEN || ''}` }, timeout: 10 * 60 * 1000 }, (res) => {
+    let out = ''
+    res.setEncoding('utf8')
+    res.on('data', (d) => { out += d })
+    res.on('end', () => {
+      let r = null
+      try { r = JSON.parse(out) } catch {}
+      if (r && r.message) process.stderr.write(`${r.message}\n`)
+      process.exit(r && r.ok ? 0 : (phase === 'pre' ? 1 : 0))
+    })
+  })
+  req.on('error', (err) => { process.stderr.write(`Quilt: the relay did not answer (${err.message}).\n`); process.exit(phase === 'pre' ? 1 : 0) })
+  req.on('timeout', () => req.destroy(new Error('it took too long')))
+  req.end(body)
+})

package/src/git.js

@@ -0,0 +1,147 @@
+// Git for starting a session from GitHub: checking names, listing repos and
+// branches, cloning. Quilt never commits, pulls or pushes. Wraps the `git`
+// and `gh` CLIs; arguments are always passed as a list, never through a shell.
+import fs from 'node:fs'
+import path from 'node:path'
+import { execFile } from 'node:child_process'
+
+// QUILT_GH lets tests stand in a fake `gh`.
+const GH = () => process.env.QUILT_GH || 'gh'
+const REPO_RE = /^[\w.-]+\/[\w.-]+$/
+// Never stop to ask for a password or open an editor.
+const ENV = { GIT_TERMINAL_PROMPT: '0', GH_PROMPT_DISABLED: '1', GIT_EDITOR: 'true', GH_NO_UPDATE_NOTIFIER: '1' }
+
+/** Runs a command; resolves to stdout, or rejects with a short message from stderr. */
+function run (cmd, args, { cwd, allowFail = false } = {}) {
+  return new Promise((resolve, reject) => {
+    execFile(cmd, args, { cwd, env: { ...process.env, ...ENV }, maxBuffer: 32 * 1024 * 1024, timeout: 5 * 60 * 1000 }, (err, stdout, stderr) => {
+      if (!err) return resolve(stdout)
+      if (allowFail) return resolve(null)
+      if (err.code === 'ENOENT') return reject(new Error(cmd === GH() ? 'The GitHub CLI (gh) is not installed.' : 'git is not installed.'))
+      const e = new Error(shortError(stderr || stdout || err.message))
+      e.stderr = String(stderr || '')
+      e.exitCode = err.code
+      reject(e)
+    })
+  })
+}
+const git = (dir, args, opts) => run('git', args, { cwd: dir, ...opts })
+const gh = (args, opts) => run(GH(), args, opts)
+
+/** The first useful line of a CLI error, without "fatal:"/"error:" noise. */
+function shortError (text) {
+  const lines = String(text).split('\n').map((l) => l.trim()).filter(Boolean)
+  const line = lines.find((l) => /^(fatal|error|remote|GraphQL|HTTP)/i.test(l)) || lines[0] || 'Something went wrong.'
+  return line.replace(/^(fatal|error):\s*/i, '').replace(/^remote:\s*/i, '').slice(0, 300)
+}
+
+/** Throws unless `name` is a valid branch name. */
+export async function checkBranchName (name) {
+  name = String(name || '').trim()
+  if (!name) throw new Error('Enter a branch name.')
+  // Not `--branch`: it expands @{-N} using the current folder's repo, so the
+  // answer would depend on where quilt happens to run.
+  if (name.startsWith('-') || name === 'HEAD' || (await run('git', ['check-ref-format', `refs/heads/${name}`], { allowFail: true })) === null) {
+    throw new Error(`"${name}" isn't a valid branch name.`)
+  }
+  return name
+}
+
+function checkRepo (repo) {
+  repo = String(repo || '').trim()
+  if (!REPO_RE.test(repo) || repo.split('/').some((p) => /^\.+$/.test(p))) throw new Error('Pick a repository (owner/name).')
+  return repo
+}
+
+// --------------------------------------------------------------- GitHub --
+
+/** Is gh installed and signed in? { installed, authenticated, user, message } */
+export async function ghStatus () {
+  const probe = (args) => new Promise((resolve) => {
+    execFile(GH(), args, { env: { ...process.env, ...ENV }, timeout: 20000 }, (err, stdout, stderr) => resolve({ err, text: `${stdout}\n${stderr}` }))
+  })
+  const version = await probe(['--version'])
+  if (version.err && version.err.code === 'ENOENT') return { installed: false, authenticated: false, user: null, message: 'Quilt can\'t list your GitHub repositories on this computer: start from a folder (a clone) instead.' }
+  const out = await probe(['auth', 'status', '--hostname', 'github.com'])
+  if (out.err) return { installed: true, authenticated: false, user: null, message: 'Quilt can\'t list your GitHub repositories on this computer: start from a folder (a clone) instead.' }
+  const user = (out.text.match(/account (\S+)/) || out.text.match(/as (\S+)/) || [])[1] || null
+  return { installed: true, authenticated: true, user, message: null }
+}
+
+/** Your repos, plus your organizations' repos, most recently updated first. */
+export async function listRepos ({ limit = 100 } = {}) {
+  limit = Math.max(1, Math.min(1000, Number(limit) || 100))
+  const fields = ['--json', 'nameWithOwner,description,updatedAt,defaultBranchRef']
+  const parse = (out) => { try { return JSON.parse(out || '[]') } catch { return [] } }
+  const mine = parse(await gh(['repo', 'list', ...fields, '--limit', String(limit)]))
+  const orgs = String(await gh(['api', 'user/orgs', '--jq', '.[].login'], { allowFail: true }) || '').split('\n').filter(Boolean).slice(0, 10)
+  const theirs = await Promise.all(orgs.map((o) => gh(['repo', 'list', o, ...fields, '--limit', String(Math.min(limit, 100))], { allowFail: true }).then(parse)))
+  const seen = new Set()
+  return [...mine, ...theirs.flat()]
+    .filter((r) => r && r.nameWithOwner && !seen.has(r.nameWithOwner) && seen.add(r.nameWithOwner))
+    .sort((a, b) => String(b.updatedAt || '').localeCompare(String(a.updatedAt || '')))
+    .map((r) => ({ name: r.nameWithOwner, description: r.description || '', updatedAt: r.updatedAt || null, defaultBranch: r.defaultBranchRef?.name || null }))
+}
+
+/** Branch names of a GitHub repo, and which one is the default. */
+export async function listBranches (repo) {
+  repo = checkRepo(repo)
+  const [names, def] = await Promise.all([
+    gh(['api', `repos/${repo}/branches`, '--paginate', '--jq', '.[].name']),
+    gh(['api', `repos/${repo}`, '--jq', '.default_branch'])
+  ])
+  const defaultBranch = def.trim() || null
+  const branches = names.split('\n').map((s) => s.trim()).filter(Boolean)
+  // Default branch first, then alphabetical.
+  branches.sort((a, b) => (a === defaultBranch ? -1 : b === defaultBranch ? 1 : a.localeCompare(b)))
+  return { branches, defaultBranch }
+}
+
+async function defaultBranchOf (dir) {
+  const head = await git(dir, ['symbolic-ref', '--quiet', '--short', 'refs/remotes/origin/HEAD'], { allowFail: true })
+  if (head && head.trim()) return head.trim().replace(/^origin\//, '')
+  for (const b of ['main', 'master']) {
+    if ((await git(dir, ['rev-parse', '--verify', '--quiet', `refs/remotes/origin/${b}`], { allowFail: true })) !== null) return b
+  }
+  return null
+}
+
+/**
+ * Clones `repo` into `dir` (which must be new or empty), then checks out
+ * `branch`, or creates `newBranch` from origin/`base` (default: the default branch).
+ */
+export async function cloneRepo ({ repo, dir, branch, newBranch, base }) {
+  repo = checkRepo(repo)
+  if (!dir) throw new Error('Choose a folder to clone into.')
+  dir = path.resolve(dir)
+  if (branch) branch = await checkBranchName(branch)
+  if (newBranch) newBranch = await checkBranchName(newBranch)
+  if (base) base = await checkBranchName(base)
+  const existed = fs.existsSync(dir)
+  if (existed && fs.readdirSync(dir).some((f) => f !== '.DS_Store')) {
+    throw new Error(`${path.basename(dir)} already has files in it. Pick an empty or new folder.`)
+  }
+  fs.mkdirSync(path.dirname(dir), { recursive: true })
+  try {
+    await gh(['repo', 'clone', repo, dir])
+    const has = async (b) => (await git(dir, ['rev-parse', '--verify', '--quiet', `refs/remotes/origin/${b}`], { allowFail: true })) !== null
+    if (newBranch) {
+      base = base || await defaultBranchOf(dir)
+      if (!base || !(await has(base))) throw new Error(`There's no branch named ${base} on GitHub to start from.`)
+      if (await has(newBranch)) throw new Error(`A branch named ${newBranch} already exists. Use it instead, or pick another name.`)
+      await git(dir, ['checkout', '-q', '--no-track', '-b', newBranch, `origin/${base}`])
+    } else if (branch) {
+      const current = (await git(dir, ['branch', '--show-current'])).trim()
+      if (branch !== current) {
+        if (!(await has(branch))) throw new Error(`There's no branch named ${branch} on GitHub.`)
+        await git(dir, ['checkout', '-q', '-b', branch, '--track', `origin/${branch}`])
+      }
+    }
+    return { dir, branch: (await git(dir, ['branch', '--show-current'])).trim() }
+  } catch (err) {
+    // Only clean up what we made.
+    if (!existed) fs.rmSync(dir, { recursive: true, force: true })
+    else for (const f of fs.readdirSync(dir)) if (f !== '.DS_Store') fs.rmSync(path.join(dir, f), { recursive: true, force: true })
+    throw err
+  }
+}

package/src/github-commit.js

@@ -0,0 +1,320 @@
+// Commits made by the relay, through GitHub's API, for any member of a session: an agent on any
+// tool (Codex, Cursor, Claude Code, a hosted agent over HTTP), with no git and no credentials on
+// its machine, and with nobody else online. The session's copy of the files is the content; the
+// branch's commit on GitHub is the parent; only the files named change. No folder, index or
+// working tree is involved, so nobody's uncommitted work is swept in.
+//
+// It never rewrites history: a ref is only moved forward (GitHub refuses anything else without
+// force, which is never sent), and a file that changed on GitHub since the session's copy was
+// taken is refused rather than overwritten. Public and private repositories work alike: writing
+// needs the session's GitHub token with write access to the repository's contents (and to pull
+// requests, to open one).
+//
+// Git for this session (AGENT_COMMITS; docs/superpowers/specs/2026-10-17-git-for-everyone.md): off for
+// everyone, or on with what agents may push: their own branches only (quilt/<agent>/…, the default),
+// or any branch, the session's own included. People may push any branch while it is on.
+import crypto from 'node:crypto'
+import { blameChange } from './history.js'
+
+const API = 'https://api.github.com'
+export const AGENT_COMMITS = ['off', 'branches', 'any']
+export const DEFAULT_AGENT_COMMITS = 'branches'
+export const MAX_COMMIT_FILES = 300
+export const MAX_COMMIT_BYTES = 20 * 1024 * 1024
+const BRANCH = /^(?!\/)(?!.*\/\/)(?!.*\.\.)(?!.*\.lock(\/|$))(?!.*[\s~^:?*[\\\x00-\x1f\x7f])(?!.*@\{)[^]+(?<![/.])$/
+
+export class CommitRefused extends Error {}
+
+/** Who set the rule over a session, in words: "the workspace Platform", "the team Night shift", "the org Acme". */
+export const ruleSetter = (set) => `the ${set.by === 'org' ? 'org' : set.by === 'team' ? 'team' : 'workspace'}${set.name ? ` ${set.name}` : ''}`
+
+/**
+ * Git for everyone, in one line, for whoever is in the session: `policy` ('off', 'branches', 'any'),
+ * `by` (the rule over the session, { by, name }, when one set it) and `login` (the GitHub account
+ * whose connection covers the repository, when one does).
+ */
+export function gitForEveryoneWords ({ policy = DEFAULT_AGENT_COMMITS, by = null, login = '' } = {}) {
+  if (policy === 'off') return `Git is off for everyone in this session: ${by ? ruleSetter(by) : 'the session owner'} turned it off.`
+  const agents = policy === 'any' ? 'people and agents push to any branch' : 'people push to any branch, agents to branches of their own'
+  if (login) return `Git is on for everyone here, through @${login}'s connection: ${agents}, with nothing to set up.`
+  return `Git is on for everyone here once someone connects GitHub (one click in the commit panel, by anyone whose GitHub account can write to the repository): ${agents}.`
+}
+
+/** git's id for a file's bytes (what GitHub's trees list), so content is compared without fetching it. */
+export function gitBlobSha (buf) {
+  return crypto.createHash('sha1').update(`blob ${buf.length}\0`).update(buf).digest('hex')
+}
+
+/** "duncan", "daniel-carmichael": a name as a branch path segment. */
+export function slug (s, max = 40) {
+  return String(s || '').toLowerCase().normalize('NFKD').replace(/[^\w\s-]/g, '').trim().replace(/[\s_]+/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '').slice(0, max).replace(/-$/, '') || 'work'
+}
+
+/** The branches an agent owns: quilt/<its name>/… */
+export const agentPrefix = (name) => `quilt/${slug(name, 30)}/`
+
+/** Whether `name` is a branch name git and GitHub accept. */
+export const validBranchName = (name) => typeof name === 'string' && name.length > 0 && name.length <= 200 && BRANCH.test(name)
+
+/**
+ * Where a member's commit goes, or why it may not: { branch, own } or throws CommitRefused.
+ * `sessionBranch`: the GitHub branch the session's branch follows (main). `target`: what they
+ * asked for ('' = the default). `kind`: 'agent' for agents, anything else for people.
+ */
+export function commitTarget ({ policy = DEFAULT_AGENT_COMMITS, kind = 'human', name, sessionBranch, target = '', message = '' }) {
+  const agent = kind === 'agent'
+  const mode = AGENT_COMMITS.includes(policy) ? policy : DEFAULT_AGENT_COMMITS
+  if (agent && mode === 'off') throw new CommitRefused('Git is off for everyone in this session. Ask a person for the commit with quilt_request_commit (your files and a message).')
+  const prefix = agentPrefix(name)
+  let branch = String(target || '').trim().replace(/^refs\/heads\//, '')
+  if (!branch) branch = agent && mode === 'branches' ? `${prefix}${slug(message, 40)}` : sessionBranch
+  if (!validBranchName(branch)) throw new CommitRefused(`"${branch}" is not a branch name git accepts.`)
+  if (agent && mode === 'branches' && !branch.startsWith(prefix)) {
+    throw new CommitRefused(`The session owner lets agents commit only to branches of their own: ${prefix}<topic>${branch === sessionBranch ? ` (not ${sessionBranch} itself)` : ''}. Leave branch out to get one, and open a pull request with pull_request: true.`)
+  }
+  return { branch, own: branch !== sessionBranch }
+}
+
+/**
+ * What a commit of `files` would change: { changes: [{ path, sha?, deleted, bytes }], same: [paths], moved: [paths] }.
+ * `files`: Map path -> Buffer (the session's content) or null (deleted in the session).
+ * `parent`: Map path -> blob sha at the commit the new one goes on; `base`: at the commit the
+ * session's copy is measured from. A file whose blob differs between the two changed on GitHub
+ * since the session took its copy: it is `moved`, and committing the session's copy would undo
+ * that change. Without `base` (a branch only its agent writes to) nothing counts as moved.
+ */
+export function planCommit (files, { parent, base = null }) {
+  const changes = []
+  const same = []
+  const moved = []
+  for (const [rel, buf] of files) {
+    const now = buf ? gitBlobSha(buf) : null
+    const at = parent.get(rel) || null
+    if (now === at) { same.push(rel); continue }
+    if (base && (base.get(rel) || null) !== at) { moved.push(rel); continue }
+    changes.push({ path: rel, sha: now, deleted: !buf, bytes: buf || null })
+  }
+  return { changes, same, moved }
+}
+
+/**
+ * Who changed each file in the session since `since` (ms) besides `me`, from the branch's
+ * history (entries oldest first): Map path -> [names]. Pulls from git are nobody's.
+ */
+export function othersEditing (paths, history, { me, since = 0 } = {}) {
+  const want = new Set(paths)
+  const out = new Map()
+  for (const e of history || []) {
+    if (!e || !want.has(e.path) || e.pulled || e.seed || !e.by || e.by === me || (e.ts || 0) <= since) continue
+    const list = out.get(e.path) || []
+    if (!list.includes(e.by)) list.push(e.by)
+    out.set(e.path, list)
+  }
+  return out
+}
+
+/** Who besides `me` made the changes a commit of one text file would carry (history.js blameChange). */
+export function othersInChange ({ before = '', after = '', entries = [], me }) {
+  return blameChange({ before, after, entries }).filter((n) => n !== me)
+}
+
+/** The commit message, and who made it: an agent is named as the author, the token's account commits it. */
+export function messageFor ({ message, by, task = null, coAuthors = [] }) {
+  const lines = [String(message || '').trim() || 'Changes from the Quilt session']
+  const trailer = [`Made in Quilt by ${by}${task ? ` for task ${task.id}: ${task.title}` : ''}.`]
+  for (const n of coAuthors) trailer.push(`Co-authored-by: ${n} <${noreply(n)}>`)
+  return `${lines.join('\n')}\n\n${trailer.join('\n')}`
+}
+
+export const noreply = (name) => `${slug(name, 40)}@agents.noreply.heyquilt.com`
+
+class GitHubWriteError extends Error {
+  constructor (status, what, body) {
+    super(`GitHub answered ${status} to ${what}${body && body.message ? `: ${body.message}` : ''}`)
+    this.status = status
+    this.body = body
+  }
+}
+
+/** The GitHub calls a commit needs. The token goes in a header, never a URL. */
+export function githubWriter ({ fetch = globalThis.fetch, token, owner, name }) {
+  const headers = { 'user-agent': 'quilt-relay', 'x-github-api-version': '2022-11-28', accept: 'application/vnd.github+json', authorization: `Bearer ${token}` }
+  const repo = `${API}/repos/${owner}/${name}`
+  const req = async (method, path, body, what) => {
+    const res = await fetch(`${repo}${path}`, { method, headers: { ...headers, ...(body ? { 'content-type': 'application/json' } : {}) }, ...(body ? { body: JSON.stringify(body) } : {}), redirect: 'follow' })
+    let json = null
+    try { json = await res.json() } catch {}
+    if (!res.ok) throw new GitHubWriteError(res.status, what, json)
+    return json
+  }
+  const enc = (ref) => ref.split('/').map(encodeURIComponent).join('/')
+  return {
+    /** The branch's head commit, or null when there is no such branch. */
+    async ref (branch) {
+      try { return (await req('GET', `/git/ref/heads/${enc(branch)}`, null, `branch ${branch}`)).object.sha } catch (err) { if (err.status === 404) return null; throw err }
+    },
+    /** A commit's tree sha and date. */
+    async commit (sha) {
+      const c = await req('GET', `/git/commits/${sha}`, null, `commit ${sha.slice(0, 7)}`)
+      return { tree: c.tree.sha, ts: Date.parse(c.committer && c.committer.date) || 0 }
+    },
+    /** Every file's blob sha in a tree: Map path -> sha (null when GitHub cut the listing short). */
+    async blobs (treeSha) {
+      const t = await req('GET', `/git/trees/${treeSha}?recursive=1`, null, 'the file list')
+      if (t.truncated) return null
+      return new Map((t.tree || []).filter((x) => x.type === 'blob').map((x) => [x.path, x.sha]))
+    },
+    async modes (treeSha) {
+      const t = await req('GET', `/git/trees/${treeSha}?recursive=1`, null, 'the file list')
+      return new Map((t.tree || []).filter((x) => x.type === 'blob').map((x) => [x.path, x.mode]))
+    },
+    /** A file's bytes at a commit, or null when it isn't there. */
+    async content (sha, rel) {
+      const res = await fetch(`${repo}/contents/${enc(rel)}?ref=${sha}`, { headers: { ...headers, accept: 'application/vnd.github.raw' }, redirect: 'follow' })
+      if (res.status === 404) return null
+      if (!res.ok) throw new GitHubWriteError(res.status, rel, null)
+      return Buffer.from(await res.arrayBuffer())
+    },
+    async blob (buf) { return (await req('POST', '/git/blobs', { content: buf.toString('base64'), encoding: 'base64' }, 'a file')).sha },
+    async tree (baseTree, entries) { return (await req('POST', '/git/trees', { base_tree: baseTree, tree: entries }, 'the new file list')).sha },
+    async newCommit ({ message, tree, parent, author }) {
+      return (await req('POST', '/git/commits', { message, tree, parents: [parent], ...(author ? { author } : {}) }, 'the commit')).sha
+    },
+    /** Moves the branch forward to `sha` (never forced: GitHub refuses a move that would lose commits). */
+    async move (branch, sha) { await req('PATCH', `/git/refs/heads/${enc(branch)}`, { sha, force: false }, `branch ${branch}`) },
+    async create (branch, sha) { await req('POST', '/git/refs', { ref: `refs/heads/${branch}`, sha }, `new branch ${branch}`) },
+    async pull ({ title, head, base, body }) {
+      try {
+        const p = await req('POST', '/pulls', { title, head, base, body }, 'the pull request')
+        return { number: p.number, url: p.html_url }
+      } catch (err) {
+        // One is already open for this branch: say which.
+        if (err.status === 422) {
+          const open = await req('GET', `/pulls?head=${encodeURIComponent(`${owner}:${head}`)}&state=open`, null, 'pull requests')
+          if (Array.isArray(open) && open[0]) return { number: open[0].number, url: open[0].html_url, existed: true }
+        }
+        throw err
+      }
+    },
+    /** The branch's newest commits: [{ sha, message, author, date, url }]. */
+    async log (branch, n = 10) {
+      const list = await req('GET', `/commits?sha=${encodeURIComponent(branch)}&per_page=${Math.max(1, Math.min(50, n | 0))}`, null, `commits on ${branch}`)
+      return (Array.isArray(list) ? list : []).map((c) => ({ sha: c.sha, message: (c.commit && c.commit.message) || '', author: (c.commit && c.commit.author && c.commit.author.name) || (c.author && c.author.login) || '', date: (c.commit && c.commit.author && c.commit.author.date) || '', url: c.html_url }))
+    },
+    /** Open pull requests, newest first: [{ number, title, head, base, url, draft, by, sha }]. */
+    async pulls () {
+      const list = await req('GET', '/pulls?state=open&per_page=50&sort=updated&direction=desc', null, 'pull requests')
+      return (Array.isArray(list) ? list : []).map((p) => ({ number: p.number, title: p.title, head: p.head && p.head.ref, base: p.base && p.base.ref, url: p.html_url, draft: !!p.draft, by: p.user && p.user.login, sha: p.head && p.head.sha }))
+    },
+    /** One pull request: { number, title, head, base, url, sha, state, merged, mergeable, mergeableState }. */
+    async pullRequest (number) {
+      const p = await req('GET', `/pulls/${Number(number)}`, null, `pull request #${number}`)
+      return { number: p.number, title: p.title, head: p.head && p.head.ref, base: p.base && p.base.ref, url: p.html_url, sha: p.head && p.head.sha, state: p.state, merged: !!p.merged, mergeable: p.mergeable, mergeableState: p.mergeable_state || '' }
+    },
+    /** How `head` stands to `base`: 'identical', 'ahead' (base is in head), 'behind' or 'diverged' (it isn't). */
+    async compare (base, head) {
+      const c = await req('GET', `/compare/${encodeURIComponent(base)}...${encodeURIComponent(head)}`, null, 'a comparison')
+      return (c && c.status) || 'diverged'
+    },
+    /** How a commit's checks stand: 'passing', 'failing', 'pending' or 'none', with the failing ones named. */
+    async checks (sha) {
+      const runs = await req('GET', `/commits/${sha}/check-runs?per_page=100`, null, 'checks')
+      const st = await req('GET', `/commits/${sha}/status`, null, 'statuses')
+      const items = (runs && Array.isArray(runs.check_runs) ? runs.check_runs : []).map((c) => ({ name: c.name, done: c.status === 'completed', ok: ['success', 'neutral', 'skipped'].includes(c.conclusion) }))
+      for (const s of (st && Array.isArray(st.statuses) ? st.statuses : [])) items.push({ name: s.context, done: s.state !== 'pending', ok: s.state === 'success' })
+      if (!items.length) return { state: 'none', failing: [] }
+      const failing = items.filter((c) => c.done && !c.ok).map((c) => c.name)
+      if (failing.length) return { state: 'failing', failing }
+      return { state: items.every((c) => c.done) ? 'passing' : 'pending', failing: [] }
+    },
+    /** Merges a pull request: { sha }. GitHub refuses when it can't be merged as it is (conflicts, rules). */
+    async merge (number, { method = 'squash', title = '' } = {}) {
+      const r = await req('PUT', `/pulls/${Number(number)}/merge`, { merge_method: method, ...(title ? { commit_title: title } : {}) }, `merging #${number}`)
+      return { sha: r.sha, merged: !!r.merged }
+    },
+    async deleteBranch (branch) {
+      try { await req('DELETE', `/git/refs/heads/${enc(branch)}`, null, `deleting ${branch}`) } catch (err) { if (err.status !== 404 && err.status !== 422) throw err }
+    }
+  }
+}
+
+/** Why GitHub refused, in words for whoever asked (never the token). */
+export function writeProblem (err, repo) {
+  const s = err && err.status
+  if (s === 401) return `the session's GitHub token was refused by GitHub (expired or revoked): ask the session owner for a new one (quilt_github_token)`
+  if (s === 403 || s === 404) return `the session's GitHub token can't write to ${repo}: the owner needs a token with "Contents: Read and write" on it (and "Pull requests: Read and write" to open pull requests), set with quilt_github_token`
+  if (s === 409) return `${repo} is empty or being changed: try again`
+  if (s === 422) return `GitHub refused: ${err.body && err.body.message ? err.body.message : 'the branch moved meanwhile'}`
+  return err && err.message ? err.message : String(err)
+}
+
+/**
+ * Makes the commit on GitHub: `files` (Map path -> Buffer|null) onto `branch`, which starts at
+ * `from` when it doesn't exist yet (the session's commit), checked against `base` (the commit
+ * the session's copy is measured from; null for a branch of the asker's own, which only they write to). Resolves { sha, branch, created, changed, same } or
+ * throws CommitRefused (nothing to commit, files changed on GitHub) or a GitHub error.
+ */
+export async function commitOnGitHub (gh, { files, branch, from, base, message, author, tries = 2 }) {
+  for (let attempt = 1; ; attempt++) {
+    const head = await gh.ref(branch)
+    const parent = head || from
+    const pc = await gh.commit(parent)
+    const parentBlobs = await gh.blobs(pc.tree)
+    if (!parentBlobs) throw new CommitRefused('The repository is too large for GitHub to list in one go; commit from a folder with git.')
+    const baseBlobs = !base ? null : base === parent ? parentBlobs : await gh.blobs((await gh.commit(base)).tree)
+    if (base && !baseBlobs) throw new CommitRefused('The repository is too large for GitHub to list in one go; commit from a folder with git.')
+    const plan = planCommit(files, { parent: parentBlobs, base: baseBlobs })
+    if (plan.moved.length) {
+      throw new CommitRefused(`${plan.moved.join(', ')} changed on ${head ? branch : 'GitHub'} since the session's copy was taken, so committing the session's copy would undo that. ` +
+        'Bring those commits into the session first (quilt_sync_branch; the session then has both), then commit again.')
+    }
+    if (!plan.changes.length) return { sha: parent, branch, created: false, changed: [], same: plan.same, nothing: true, exists: !!head }
+    const modes = await gh.modes(pc.tree)
+    const entries = []
+    for (const c of plan.changes) {
+      if (c.deleted) entries.push({ path: c.path, mode: modes.get(c.path) || '100644', type: 'blob', sha: null })
+      else entries.push({ path: c.path, mode: modes.get(c.path) || '100644', type: 'blob', sha: await gh.blob(c.bytes) })
+    }
+    const tree = await gh.tree(pc.tree, entries)
+    const sha = await gh.newCommit({ message, tree, parent, author })
+    try {
+      if (head) await gh.move(branch, sha)
+      else await gh.create(branch, sha)
+      return { sha, parent, branch, created: !head, changed: plan.changes.map((c) => c.path), same: plan.same }
+    } catch (err) {
+      // Someone pushed to the branch meanwhile: start again from its new head.
+      if ((err.status === 422 || err.status === 409) && attempt < tries) continue
+      throw err
+    }
+  }
+}
+
+/** quilt_commit, the same for every agent (local MCP, hosted MCP, CLI). */
+export const GIT_COMMIT_DESCRIPTION = 'Commit your work to the branch you are on, on GitHub: the session\'s copy of exactly these files (by default every change of yours on record on this branch), with your message. ' +
+  'On a branch of your own (quilt/<you>/…, where taking a task puts you) the pull request to the session\'s branch opens by itself and is tied to your task. ' +
+  'The session\'s branch itself is open to agents only when the owner lets agents push to any branch; otherwise take a task or quilt_git_branch create first. ' +
+  'Refused for a file that changed on GitHub since the session\'s copy (quilt_sync_branch first) and for one holding others\' uncommitted changes (unless with_others). ' +
+  'Commit as soon as work is finished and tested: work that is only in the session has not shipped. When the owner keeps agents from committing, ask a person with quilt_request_commit.'
+export const gitCommitSchema = (z) => ({
+  message: z.string().min(1).max(2000).describe('What the change does (the first line is the subject)'),
+  files: z.array(z.string().min(1).max(500)).max(200).optional().describe('The files to commit, deleted ones too; default: every change of yours on record on this branch'),
+  task: z.string().max(40).optional().describe('The task this is for: its title names the pull request, and the task follows it'),
+  with_others: z.boolean().optional().describe('Also commit files that hold other people\'s uncommitted changes (they are named as co-authors)')
+})
+
+export const COMMIT_DESCRIPTION = 'For agents with no folder (hosted, over HTTP): commit your finished work to the repository on GitHub through the relay, since you have no git of your own; nobody else needs to be online. Agents with a folder push with git instead. ' +
+  'Quilt commits the session\'s copy of exactly these files (by default every change of yours on record on this branch) with your message, and everyone sees it in chat. ' +
+  'Where it goes is the session owner\'s call: by default a branch of your own (quilt/<you>/<topic>; pull_request: true opens a pull request to the session\'s branch); ' +
+  'when the owner lets agents commit to any branch, leaving branch out commits to the session\'s branch itself. ' +
+  'Refused for a file that changed on GitHub since the session\'s copy (bring it in with quilt_sync_branch first) and for one holding others\' uncommitted changes (unless with_others). ' +
+  'Commit as soon as work is finished and tested: work that is only in the session has not shipped. When the owner keeps agents from committing, ask a person with quilt_request_commit.'
+
+/** quilt_commit's arguments, the same for the local and the hosted tool (`z`: zod). */
+export const commitSchema = (z) => ({
+  message: z.string().max(2000).optional().describe('The commit message: what the change does (a task\'s title by default)'),
+  files: z.array(z.string().max(1024)).max(300).optional().describe('The files to commit, relative to the project\'s top folder (deleted ones too); default: every change of yours on record on this branch'),
+  branch: z.string().max(200).optional().describe('The GitHub branch to commit to; default: a branch of your own (quilt/<you>/<topic>), or the session\'s branch when the owner lets agents commit there'),
+  pull_request: z.boolean().optional().describe('Open a pull request from your branch to the session\'s branch'),
+  with_others: z.boolean().optional().describe('Also commit files that hold others\' uncommitted changes (they are named as co-authors)'),
+  task: z.string().max(40).optional().describe('The task this work was for: its title is the message and its changes the files, unless you give them')
+})

package/src/gitignore.js

@@ -0,0 +1,49 @@
+// Quilt keeps a session's local state in .quilt/. In a git folder that is an
+// untracked folder, so `git stash -u` or `git clean -fd` would take it away. The
+// project's own .gitignore is where git is told to leave it alone: a line is
+// added there (and shared, like any edit of .gitignore). Nothing under .git is
+// ever touched.
+import fs from 'node:fs'
+import path from 'node:path'
+import { gitDir } from './gitstate.js'
+
+const IGNORES_QUILT = new Set(['.quilt', '.quilt/', '/.quilt', '/.quilt/'])
+export const QUILT_IGNORE_COMMENT = "# Quilt keeps this session's local state here"
+
+/**
+ * Whether .gitignore's text already has a line ignoring .quilt. Trailing
+ * spaces don't count (git drops them); leading ones are part of the pattern.
+ */
+export function ignoresQuilt (text) {
+  return String(text).split(/\r?\n/).some((line) => IGNORES_QUILT.has(line.replace(/\s+$/, '')))
+}
+
+/**
+ * In a git folder, makes sure .gitignore ignores .quilt/: appends a comment
+ * and `.quilt/` when no line does (creating the file if need be, in its own
+ * line endings). Returns { added: true }, { added: false } (nothing to do:
+ * not a git folder, or already ignored), or { added: false, error } when
+ * .gitignore couldn't be read or written.
+ */
+export function ensureQuiltIgnored (root) {
+  if (!gitDir(root)) return { added: false }
+  const file = path.join(root, '.gitignore')
+  let text = ''
+  try {
+    const st = fs.lstatSync(file)
+    if (!st.isFile()) return { added: false, error: new Error('.gitignore is not a plain file') }
+    text = fs.readFileSync(file, 'utf8')
+  } catch (err) {
+    if (err.code !== 'ENOENT') return { added: false, error: err }
+  }
+  if (ignoresQuilt(text)) return { added: false }
+  const eol = text.includes('\r\n') ? '\r\n' : '\n'
+  const lead = text && !text.endsWith('\n') ? eol : ''
+  try {
+    // Appended, so the file's own bytes stay as they are; O_NOFOLLOW: never through a link put there meanwhile.
+    fs.writeFileSync(file, `${lead}${QUILT_IGNORE_COMMENT}${eol}.quilt/${eol}`, { flag: fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_APPEND | (fs.constants.O_NOFOLLOW || 0) })
+  } catch (err) {
+    return { added: false, error: err }
+  }
+  return { added: true }
+}