heyquilt 0.0.1 → 0.3.90

package/src/settings.js

@@ -0,0 +1,46 @@
+// Per-user settings in ~/.quilt/settings.json: your colour, AI tool and session
+// defaults. And the one relay Quilt uses.
+import fs from 'node:fs'
+import path from 'node:path'
+import { quiltHome } from './legacy.js'
+
+/** The relay every session uses. QUILT_SERVER overrides it, for development and tests only. */
+export const HOSTED_RELAY = 'wss://relay.heyquilt.com'
+// The hosted relay's older address points at the same relay, so its sessions reopen as they are.
+const HOSTED_ALIASES = [HOSTED_RELAY, 'wss://cowove-relay.fly.dev']
+// Settings from when you could pick a relay. Ignored, and dropped the next time settings are saved.
+const RETIRED = ['relay', 'relayKey', 'relayMode', 'publicUrl']
+
+const file = () => path.join(quiltHome(), 'settings.json')
+
+export function getSettings () {
+  let s = {}
+  try { s = JSON.parse(fs.readFileSync(file(), 'utf8')) || {} } catch {}
+  for (const k of RETIRED) delete s[k]
+  return s
+}
+
+export function saveSettings (patch) {
+  const next = { ...getSettings(), ...patch }
+  for (const k of Object.keys(next)) if (next[k] === undefined || next[k] === null || next[k] === '') delete next[k]
+  fs.mkdirSync(path.dirname(file()), { recursive: true })
+  fs.writeFileSync(file(), JSON.stringify(next, null, 2), { mode: 0o600 })
+  return next
+}
+
+export function relayUrl () {
+  return process.env.QUILT_SERVER || HOSTED_RELAY
+}
+
+export function isHostedRelay (server) {
+  return HOSTED_ALIASES.includes(String(server || '').replace(/\/+$/, ''))
+}
+
+/**
+ * A saved session on any relay other than Quilt's own (or the QUILT_SERVER relay in use): one that
+ * ran on someone's own computer, or through a tunnel to it. Quilt no longer runs those, and must
+ * never send this computer's pass to them.
+ */
+export function unsupportedRelay (server) {
+  return !!server && !isHostedRelay(server) && server !== relayUrl()
+}

package/src/setup.js

@@ -0,0 +1,184 @@
+// Wires quilt into AI coding tools in the current project: registers the MCP
+// server for Claude Code / Cursor and adds pairing guidance to the agent
+// instruction files. These files live in the project, so they sync to
+// everyone in the session.
+import fs from 'node:fs'
+import path from 'node:path'
+import { hookSettings, isQuiltHook } from './hooks.js'
+import { registerEverywhere } from './integrations.js'
+import { TASK_WORKFLOW_MD, CHECKLIST_SCAFFOLD, extractChecklist } from './agent-task-workflow.js'
+
+const START = '<!-- quilt:start -->'
+const END = '<!-- quilt:end -->'
+
+export const AGENT_GUIDE = `${START}
+## Live pair session (quilt)
+
+This project is being edited **live by more than one person at once**, each
+with their own AI coding tool. Files can change underneath you at any time.
+
+- Before starting a task, check what your collaborators are doing: call the
+  \`quilt_status\` MCP tool, or run \`quilt status\` in a shell, or read
+  \`.quilt/STATUS.md\`.
+- The session has a shared task board (To do, In progress, QA, Done). Read it with
+  \`quilt_tasks\`. Add work with \`quilt_add_task\`. Move a task to In progress
+  when you start it and to QA with \`qaNotes\` when you finish (\`quilt_move_task\`).
+${TASK_WORKFLOW_MD}
+- Read the project's rules and design system with \`quilt_project_rules\` before your
+  first change: the same rules whatever tool each person uses.
+- See what a partner's AI is doing with \`quilt_partner_feed\`, and where people
+  are working with \`quilt_list_files\` (recent edits and claims).
+- Announce what you're working on (\`quilt_set_focus\` / \`quilt focus "..."\`).
+- Share your work with \`quilt_share\`: when you start a request (what was asked,
+  your plan) and when you finish (what you did, the files you changed). Partners
+  see it in their feed, it goes on the task board, and the host won't commit under you.
+- Before you change files, call \`quilt_before_edit\` with their paths. It tells you
+  whether each one is yours to edit (claiming free ones for you) and shows what
+  people said about those files in chat. Don't edit a file it refuses.
+- You're a member of your own in the session, apart from your person and their other
+  AI sessions, named after your work: "<their first name> · <label>", from your git
+  branch or the first thing you say you're doing. Rename yourself with
+  \`quilt_name_session\`. Your messages, inbox, claims and duties are your own. People
+  see all of a person's AI sessions as one, "<person>'s AI": write to another person's AI
+  by that name ("@Daniel's AI"), and what is written to your person's AI reaches whichever
+  of their sessions was active last (with none of them live, their cloud AI, if they
+  connected one: their own AI tool on their own cloud VM).
+- Claims follow edits, whatever tool you are: the moment you change a file nobody
+  holds, Quilt claims it for you, and lets go when you finish (your AI goes idle, or
+  the file has been quiet for a few minutes). Claim ahead only for a larger change
+  across several files (\`quilt_claim\` / \`quilt claim <path>\`) and release it when
+  done (\`quilt_release\` / \`quilt release <path>\`).
+- Your unfinished work is boxed: in a folder that is a git repository, a file you
+  change stays in a box until you commit it. Everyone sees the change, but it is only
+  in your folder, so nobody else's git can commit it. Committing it (or putting it
+  back) opens the box by itself; finishing or releasing does not. \`quilt_unpack\`
+  shares a box early when someone needs it: decide yourself, and ask your person first
+  for a large, risky or critical change or when the project's rules say so. A file
+  boxed by someone else isn't in your folder yet: don't build on it; ask for it with
+  \`quilt_request_file\`.
+- If a file is claimed by someone else, your edit is refused or undone, and the next
+  quilt tool you call tells you so. Don't retry or work around it: ask for it in its
+  file queue (\`quilt_request_file\`: a title like "Working on X for task Y" and up to
+  300 characters on your plan), then carry on with other work. You're woken when it's
+  handed to you, with the holder's context.
+- When someone waits in the queue for a file you hold, every quilt answer says so.
+  Finish your change, then hand it off with \`quilt_handoff\` and your context (what
+  you changed, what's left, gotchas). You can't finish or release it before. A claim
+  whose holder does nothing for 20 minutes goes to the next one waiting.
+- Answer collaborators' messages (\`quilt_read_messages\`): help with their change,
+  or say when you'll be done. New ones are shown at the top of
+  every quilt answer. When you finish, call \`quilt_set_work\` with "done": it is
+  refused until everyone who wrote to you has an answer.
+- \`quilt_inbox\` lists what is waiting for you: mentions of you (@yourname), direct
+  messages and tasks handed to you. Read it when you start and act on each one.
+- Before moving a ticket to QA, run the checks under "Verifying a change" (in
+  AGENTS.md; add them there if the section is missing) and pass a change description
+  plus self-validation as \`qaNotes\` to \`quilt_move_task\`. QA without notes is refused.
+  Moving to Done still needs \`verified\`.
+- Always re-read a file right before editing it; never rely on an old copy.
+- Prefer small, focused edits over rewriting whole files.
+- Git works as usual here: pull and push yourself, and commit only the files you
+  changed (never \`git add -A\` or \`git commit -a\`: the folder holds other people's
+  unfinished work). An agent's folder is a checkout Quilt made, and its git signs in
+  to GitHub through Quilt within the session owner's policy. Taking a task puts your
+  folder on a branch of your own for it (quilt/<you>/<task>); push it and Quilt opens
+  the pull request; Done merges it once checks pass (a person moves it to Done unless
+  the owner lets agents push anywhere). Pushes and merges on GitHub reach the session
+  within seconds, so never pull by hand. Quilt recognises git
+  commands, so a stash or reset on this computer never erases the session's
+  work (it comes back a moment later), a git conflict pauses this folder until
+  you resolve it and \`git add\` it, and checking out another branch moves this
+  folder to that branch's work in the session (the old branch keeps its own).
+  Deleting a file deletes it for everyone.
+- If git refuses to pull because untracked files would be overwritten, those
+  files came from the session: \`quilt_status\` lists them under "Pulling" and
+  says whether they match the commits. Make way and pull with
+  \`rm <files> && git pull --autostash\`: Quilt keeps them for everyone and the
+  pull lands them (where they differ, Quilt merges the two afterwards).
+${END}`
+
+function upsertBlock (file, block) {
+  let text = ''
+  try { text = fs.readFileSync(file, 'utf8') } catch {}
+  const re = new RegExp(`${START}[\\s\\S]*?${END}`)
+  const next = re.test(text) ? text.replace(re, block) : (text ? text.replace(/\s*$/, '\n\n') : '') + block + '\n'
+  if (next !== text) fs.writeFileSync(file, next)
+  return next !== text
+}
+
+/**
+ * Points a tool's own rules file (CLAUDE.md, GEMINI.md) at AGENTS.md, the one set of rules for
+ * every tool (project-rules.js): an "@AGENTS.md" line on top, which Claude Code and Gemini CLI
+ * read in. Quilt's guide block comes in with AGENTS.md, so it leaves this file; the rest of the
+ * file is the owner's and stays. `create`: write the file when it isn't there. True when written.
+ */
+export function pointAtAgents (file, { create = false } = {}) {
+  let text = null
+  try { text = fs.readFileSync(file, 'utf8') } catch {}
+  if (text === null && !create) return false
+  const own = (text || '').replace(new RegExp(`\\n*${START}[\\s\\S]*?${END}\\n*`), '\n').replace(/^\s+/, '')
+  const next = /^\s*@AGENTS\.md\s*$/m.test(own) ? own.replace(/\s*$/, '\n') : `@AGENTS.md\n${own.trim() ? `\n${own.replace(/\s*$/, '\n')}` : ''}`
+  if (next === text) return false
+  fs.writeFileSync(file, next)
+  return true
+}
+
+/** Where Quilt's Claude Code hooks live: this person's own settings, which never sync or get committed. */
+export const HOOKS_FILE = '.claude/settings.local.json'
+
+/**
+ * Puts Quilt's hooks into the project's .claude/settings.local.json, replacing earlier
+ * Quilt entries and leaving other hooks and settings alone. Returns true when the file changed.
+ */
+export function installHooks (root) {
+  const file = path.join(root, HOOKS_FILE)
+  let prev = ''
+  try { prev = fs.readFileSync(file, 'utf8') } catch {}
+  let json = {}
+  try { json = JSON.parse(prev) || {} } catch {}
+  if (typeof json !== 'object' || Array.isArray(json)) json = {}
+  const hooks = (json.hooks && typeof json.hooks === 'object' && !Array.isArray(json.hooks)) ? json.hooks : {}
+  const ours = isQuiltHook
+  for (const [event, entries] of Object.entries(hookSettings())) {
+    const kept = (Array.isArray(hooks[event]) ? hooks[event] : [])
+      .map((e) => (e && Array.isArray(e.hooks) ? { ...e, hooks: e.hooks.filter((h) => !ours(h)) } : e))
+      .filter((e) => e && (!Array.isArray(e.hooks) || e.hooks.length))
+    hooks[event] = [...kept, ...entries]
+  }
+  json.hooks = hooks
+  const text = JSON.stringify(json, null, 2) + '\n'
+  if (prev === text) return false
+  fs.mkdirSync(path.dirname(file), { recursive: true })
+  fs.writeFileSync(file, text)
+  return true
+}
+
+/**
+ * Adds the "Verifying a change" template to AGENTS.md when neither guide has that
+ * section yet, outside Quilt's block so owners can edit it. Returns true when written.
+ */
+export function scaffoldChecklist (root) {
+  const read = (f) => { try { return fs.readFileSync(path.join(root, f), 'utf8') } catch { return '' } }
+  if (extractChecklist(read('AGENTS.md')) || extractChecklist(read('CLAUDE.md'))) return false
+  const file = path.join(root, 'AGENTS.md')
+  const text = read('AGENTS.md')
+  fs.writeFileSync(file, (text ? text.replace(/\s*$/, '\n\n') : '') + CHECKLIST_SCAFFOLD)
+  return true
+}
+
+export function setup (root, { home } = {}) {
+  const changed = []
+  // MCP servers go in each AI tool's own settings on this computer (with this install's path),
+  // not in the project, whose files sync to everyone. See integrations.js.
+  for (const r of registerEverywhere(home ? { home } : {})) {
+    if (r.result === 'added' || r.result === 'updated') changed.push(`${r.file} (${r.name} MCP server)`)
+    else if (r.result === 'skipped' || r.result === 'failed') changed.push(`${r.file}: left alone, not plain JSON (${r.name})`)
+  }
+  if (installHooks(root)) changed.push(`${HOOKS_FILE} (Claude Code hooks: files are claimed as you edit them)`)
+  if (upsertBlock(path.join(root, 'AGENTS.md'), AGENT_GUIDE)) changed.push('AGENTS.md (Cursor, Codex, and other agents)')
+  // Claude Code and Gemini CLI read AGENTS.md through a pointer, so every tool has the same rules.
+  if (pointAtAgents(path.join(root, 'CLAUDE.md'), { create: true })) changed.push('CLAUDE.md (Claude Code: reads AGENTS.md)')
+  if (pointAtAgents(path.join(root, 'GEMINI.md'))) changed.push('GEMINI.md (Gemini CLI: reads AGENTS.md)')
+  if (scaffoldChecklist(root)) changed.push('AGENTS.md ("Verifying a change": fill in what proves a change works here)')
+  return changed
+}

package/src/shell-path.js

@@ -0,0 +1,46 @@
+// An app opened from Finder or the Dock gets a minimal PATH (/usr/bin:/bin:/usr/sbin:/sbin),
+// so git from Homebrew or Xcode's tools isn't found. The PATH your login shell sets up is
+// read once at startup and put in front of it.
+import { execFile } from 'node:child_process'
+import path from 'node:path'
+
+const MARK = '__QUILT_PATH__'
+
+/**
+ * The shell's PATH entries first, then the current ones, each once, in order;
+ * on macOS and Linux (`sep` ":"), /usr/bin is always there (the system git lives in it).
+ */
+export function mergePath (shellPath, currentPath, sep = path.delimiter) {
+  const seen = new Set()
+  const out = []
+  for (const dir of [...String(shellPath || '').split(sep), ...String(currentPath || '').split(sep), ...(sep === ':' ? ['/usr/bin'] : [])]) {
+    if (!dir || seen.has(dir)) continue
+    seen.add(dir)
+    out.push(dir)
+  }
+  return out.join(sep)
+}
+
+/** The PATH printed between two markers (a shell's startup files may print their own lines), or null. */
+export function pathFromOutput (out) {
+  const m = new RegExp(`${MARK}(.*?)${MARK}`, 's').exec(String(out || ''))
+  return m && m[1].trim() ? m[1].trim() : null
+}
+
+/** Your login shell's PATH, or null when it can't be read within `timeoutMs`. Never rejects. */
+export function loginShellPath ({ shell = process.env.SHELL || '/bin/zsh', timeoutMs = 3000 } = {}) {
+  if (process.platform === 'win32') return Promise.resolve(null)
+  return new Promise((resolve) => {
+    execFile(shell, ['-ilc', `echo "${MARK}\${PATH}${MARK}"`], { timeout: timeoutMs, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }, (err, stdout) => {
+      resolve(err ? null : pathFromOutput(stdout))
+    })
+  })
+}
+
+/** Sets process.env.PATH to your login shell's PATH merged with the current one. Not on Windows: its PATH is left as it is. */
+export async function adoptLoginShellPath (opts) {
+  if (process.platform === 'win32') return process.env.PATH
+  const shellPath = await loginShellPath(opts)
+  process.env.PATH = mergePath(shellPath, process.env.PATH)
+  return process.env.PATH
+}

package/src/status.js

@@ -0,0 +1,199 @@
+// Renders a session status snapshot as Markdown. Used for .quilt/STATUS.md,
+// `quilt status`, and the MCP `quilt_status` tool, so every tool sees the same view.
+
+import { branchesMarkdown } from './branches.js'
+import { taskMarkdown } from './tasks.js'
+import { mergeAction } from './merges.js'
+import { catchUpMarkdown } from './catchup.js'
+import { DEFAULT_KEY } from './branchdocs.js'
+
+/** A shell word for a path (quoted only when it needs to be). */
+const shellWord = (p) => /^[\w./@+-]+$/.test(p) ? p : `'${p.replace(/'/g, "'\\''")}'`
+
+/** The one line that makes way for a pull over files the session put here, and pulls. */
+export function makeWayCommand (paths) {
+  return `rm ${paths.map(shellWord).join(' ')} && git pull --autostash`
+}
+
+/**
+ * What to tell a person's AI when the upstream adds files the session already
+ * put in this folder (git refuses to pull over untracked files). `adds`: [{ path, same, waiting }].
+ */
+export function pullAdvice ({ upstream, behind, adds }) {
+  const inWay = adds.filter((a) => !a.waiting)
+  const differ = adds.filter((a) => !a.same)
+  const list = (xs) => xs.map((a) => a.path).join(', ')
+  const lines = [`${upstream} has ${behind} commit${behind === 1 ? '' : 's'} adding ${list(adds)}, which the session already put in this folder${differ.length ? '' : ' with the same content'}.`]
+  if (inWay.length) lines.push(`git won't pull over untracked files: make way and pull with \`${makeWayCommand(inWay.map((a) => a.path))}\`. Quilt keeps them for everyone and doesn't share the removal (a plain delete at any other time deletes for everyone).`)
+  else lines.push('They are out of the way: pull now (`git pull --autostash`). Quilt keeps them for everyone meanwhile.')
+  for (const a of differ) lines.push(`${a.path} differs from the session's: after the pull Quilt merges the two (a merge record if they clash).`)
+  return lines.join(' ')
+}
+
+const ago = (ts) => {
+  const s = Math.max(0, Math.round((Date.now() - ts) / 1000))
+  if (s < 60) return `${s}s ago`
+  if (s < 3600) return `${Math.round(s / 60)}m ago`
+  return `${Math.round(s / 3600)}h ago`
+}
+
+export function renderStatus (st, { asAi = false, mentionYours = false } = {}) {
+  const out = []
+  out.push(`# Quilt pair session: room \`${st.room}\``)
+  out.push('')
+  out.push(`Relay: ${st.connected ? 'connected' : '**disconnected** (edits are kept and will sync on reconnect)'} · ${st.fileCount} shared files`)
+  if (!st.connected && st.problem) out.push(`⚠️ ${st.problem}`)
+  out.push(`You: **${st.me.name}** (${st.me.tool})${st.me.persona ? `, one of ${st.me.of}'s AI sessions` : ''}${st.me.focus ? ` · focus: ${st.me.focus}` : ''}`)
+  if (st.workspaceName || st.workspace) out.push(`Workspace: ${st.workspaceName || st.workspace}`)
+  out.push('')
+
+  const away = catchUpMarkdown(st.catchUp, { ago })
+  if (away.length) out.push(...away, '')
+
+  out.push('## Partners online')
+  if (!st.peers.length) out.push('_Nobody else is connected right now._')
+  for (const p of st.peers.filter((x) => x.name !== st.me.name)) {
+    const tools = [p.tool, ...(p.agents || [])].filter((t) => t && t !== 'unknown')
+    const kind = p.persona ? ` [AI session of ${p.mine && st.me.persona ? 'your person' : p.of}]` : p.kind === 'agent' ? ' [AI agent]' : ''
+    out.push(`- **${p.name}**${kind}${tools.length ? ` (${[...new Set(tools)].join(', ')})` : ''}${p.focus ? `: working on: ${p.focus}` : ''}`)
+    const ai = aiLine(p.agent)
+    if (ai) out.push(`  - AI: ${ai}`)
+    const editing = p.editing.slice(0, 8)
+    if (editing.length) out.push(`  - recently edited: ${editing.map((e) => `\`${e.path}\` (${e.secondsAgo}s ago)`).join(', ')}`)
+  }
+  out.push('')
+  if (st.away && st.away.length) {
+    out.push('## Away')
+    out.push('_Agents that work in turns, between turns: write to them as usual, they read it at the start of their next turn._')
+    for (const a of st.away) out.push(`- **${a.name}** [AI agent]: last here ${ago(a.lastSeen)}`)
+    out.push('')
+  }
+
+  out.push('## Tasks')
+  out.push(taskMarkdown(st.tasks, st.me.name, { tool: st.me.tool, asAi, mentionYours }))
+  out.push('')
+
+  if (st.branches && st.branches.length) {
+    out.push('## Branches')
+    out.push(branchesMarkdown(st.branches, { limit: 6 }))
+    out.push('')
+  }
+
+  const openCommits = (st.commits || []).filter((r) => r.state === 'open')
+  if (openCommits.length) {
+    out.push('## Commit requests')
+    for (const r of openCommits) {
+      const who = r.by === st.me.name ? 'you' : r.by
+      const branch = r.branch && r.branch !== DEFAULT_KEY ? ` on \`${r.branch}\`` : ''
+      out.push(`- [${r.id}] ${ago(r.ts)}: ${who} asked for a commit${branch}: ${r.message}${r.error ? `. Last try: ${r.error}` : ''}`)
+      if (Array.isArray(r.files) && r.files.length) out.push(`  Files: ${r.files.slice(0, 20).join(', ')}${r.files.length > 20 ? `, and ${r.files.length - 20} more` : ''}`)
+      if (r.description) out.push(`  ${String(r.description).replace(/\s+/g, ' ')}`)
+    }
+    if (st.canCommit) out.push('This folder has git: commit one in the app (Commit and push), or by hand and close it with quilt_commit_request_done.')
+    out.push('')
+  }
+
+  const pull = st.git && st.git.pull
+  if (pull && pull.adds && pull.adds.length) {
+    out.push('## Pulling')
+    out.push(pullAdvice(pull))
+    for (const a of pull.adds) out.push(`- \`${a.path}\`: ${a.waiting ? 'out of the way, waiting for your pull' : a.same ? 'same content as the session\'s' : 'differs from the session\'s'}`)
+    out.push('')
+  }
+
+  // Boxes (docs/superpowers/specs/2026-10-16-git-boxes-design.md): unfinished work only in its owner's folder.
+  const boxed = st.claims.filter((c) => c.box)
+  if (boxed.length) {
+    out.push('## Boxed work')
+    for (const c of boxed) out.push(c.by === st.me.name ? `- \`${c.pattern}\`: your unfinished work: in your folder only, until you commit it (or quilt_unpack)` : `- \`${c.pattern}\`: ${c.by}'s unfinished work: not in your folder until they commit or unpack it`)
+    out.push('')
+  }
+  const plain = st.claims.filter((c) => !c.box)
+  out.push('## Claimed files')
+  if (!plain.length) out.push('_No claims._')
+  for (const c of plain) {
+    const who = c.by === st.me.name ? 'you' : c.by
+    out.push(`- \`${c.pattern}\`: ${who}${c.note ? `: ${c.note}` : ''} (${ago(c.ts)})`)
+  }
+  out.push('')
+
+  const merges = (st.merges || []).filter((m) => m.state !== 'done')
+  if (merges.length) {
+    out.push('## Merges to settle')
+    for (const m of merges) {
+      const who = m.by === st.me.name ? 'you' : m.by
+      const otherName = m.others[0] ? (m.others[0] === st.me.name ? 'you' : m.others[0]) : null
+      const action = mergeAction(m)
+      const theirsPart = m.theirsHash === null ? ', it was deleted in the session' : otherName ? `, ${otherName} changed it in the session` : ''
+      out.push(`- \`${m.path}\` (id ${m.id}): ${who} ${action}${theirsPart}${m.kind === 'ai' ? '; merged by AI, needs a look' : ''}. See quilt_merges.`)
+    }
+    out.push('')
+  }
+
+  out.push('## Recent activity')
+  const act = st.activity.slice(-15).reverse()
+  if (!act.length) out.push('_Nothing yet._')
+  for (const a of act) {
+    const who = a.by === st.me.name ? 'you' : a.by
+    if (a.kind === 'pulled') out.push(`- ${ago(a.ts)}: ${who} pulled ${a.detail || 'commits'}`)
+    else if (a.kind === 'brought') out.push(`- ${ago(a.ts)}: ${who} brought in ${a.detail || 'commits'}${a.branch ? ` on \`${a.branch}\`` : ''}`)
+    else if (a.kind === 'switched') out.push(`- ${ago(a.ts)}: ${who} switched to \`${a.branch}\``)
+    else out.push(`- ${ago(a.ts)}: ${who} ${a.kind} \`${a.path}\`${a.detail ? ` (${a.detail})` : ''}`)
+  }
+  out.push('')
+
+  out.push('## Changes')
+  const changes = st.changes || []
+  if (!changes.length) out.push('_No changes yet._')
+  for (const p of changes) {
+    const who = p.name === st.me.name ? 'you' : `**${p.name}**`
+    const line = (g, label) => {
+      const n = g.fileCount ?? g.files.length
+      const files = g.files.map((f) => `\`${f.path}\` (${fileChange(f)})`)
+      if (n > g.files.length) files.push(`and ${n - g.files.length} more`)
+      out.push(`- ${who}${label}: ${n} file${n === 1 ? '' : 's'}, +${g.added} -${g.removed} (${ago(g.ts)}): ${files.join(', ')}`)
+    }
+    // Their own edits, then what their git pulls brought (other people's commits), never mixed.
+    if ((p.fileCount ?? p.files.length) || !p.pulled) line(p, '')
+    if (p.pulled) line(p.pulled, ' pulled from git')
+  }
+  out.push('')
+
+  out.push(`## Messages${st.unread ? ` (${st.unread} unread)` : ''}`)
+  if (!st.chat.length) out.push('_No messages._')
+  for (const m of st.chat.slice(-10)) out.push(`- ${renderMessage(m, st.me.name)}`)
+  out.push('')
+  return out.join('\n')
+}
+
+function aiLine (a) {
+  if (!a) return ''
+  if (a.sharing === false) return 'sharing paused'
+  if (a.status === 'unavailable') return `${a.tool || 'feed'} unavailable`
+  if (!a.tool) return ''
+  return `${a.tool} ${a.status === 'working' ? 'is working' : 'idle'} (see quilt_partner_feed)`
+}
+
+export function renderMessage (m, me) {
+  const from = m.by === me ? 'you' : m.by
+  const to = m.to ? ` → ${m.to === me ? 'you' : m.to} (direct, id ${m.id}${m.re ? `, answers ${m.re}` : ''})` : ''
+  let line = `${ago(m.ts)} ${m.unread ? '🆕 ' : ''}**${from}${to}:** ${m.text}`
+  if (m.file) {
+    line += ` 📎 \`${m.file.name}\` (${formatBytes(m.file.size)})`
+    line += m.file.localPath ? `, saved at \`${m.file.localPath}\`` : `, id \`${m.id}\``
+  }
+  return line
+}
+
+export function formatBytes (n) {
+  if (n < 1024) return `${n} B`
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`
+  return `${(n / 1024 / 1024).toFixed(1)} MB`
+}
+
+/** One file's change in a few words: "deleted", "new, +5" or "+12 -1". */
+function fileChange (f) {
+  if (f.kind === 'deleted') return 'deleted'
+  if (f.kind === 'created') return `new, +${f.added}${f.removed ? ` -${f.removed}` : ''}`
+  return `+${f.added} -${f.removed}`
+}

package/src/summarize.js

@@ -0,0 +1,109 @@
+// Summaries of your AI chat, made on your computer before anything is
+// shared: your prompts and your AI's replies become a sentence or two. Uses
+// the Claude Code CLI (`claude -p`) when it's installed and signed in, and
+// falls back to shortening the text when it isn't.
+import { spawn } from 'node:child_process'
+import os from 'node:os'
+
+const INSTRUCTIONS = {
+  prompt: 'Summarize this request a developer gave their AI coding assistant in one plain sentence of at most 20 words. Output only the sentence.',
+  reply: 'Summarize this reply from an AI coding assistant in one or two plain sentences, at most 35 words in total. Mention files or decisions if there are any. Output only the summary.',
+  task: 'Name the coding task in this request as a short to-do title: 2 to 6 words, starting with a verb, like "Add dark mode" or "Fix login redirect". Output only the title.'
+}
+const MAX_TASK_TITLE = 80
+const SHORT_ENOUGH = 140 // characters: already short, share as is
+const TIMEOUT_MS = 45000
+const RETRY_AFTER_MS = 10 * 60 * 1000 // after the CLI fails, shorten instead for a while
+
+/** The first sentence (or first `max` characters) of text. */
+export function shorten (text, max = 160) {
+  const flat = String(text || '').replace(/```[\s\S]*?```/g, ' [code] ').replace(/\s+/g, ' ').trim()
+  const sentence = flat.match(/^.*?[.!?](\s|$)/)
+  const first = sentence && sentence[0].length >= 20 ? sentence[0].trim() : flat
+  if (first.length <= max) return first
+  const cut = first.slice(0, max - 1)
+  return `${cut.slice(0, cut.lastIndexOf(' ') > max / 2 ? cut.lastIndexOf(' ') : cut.length).replace(/[\s,;:]+$/, '')}…`
+}
+
+/** Runs a command with text on stdin (in a temp folder, so it never shows up as a chat in the project). */
+function runCli (cmd, args, input) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(cmd, args, { cwd: os.tmpdir(), env: process.env, stdio: ['pipe', 'pipe', 'pipe'] })
+    let out = ''
+    let err = ''
+    const timer = setTimeout(() => { child.kill('SIGKILL'); reject(new Error('timed out')) }, TIMEOUT_MS)
+    child.stdout.on('data', (d) => { out += d })
+    child.stderr.on('data', (d) => { err += d })
+    child.on('error', (e) => { clearTimeout(timer); reject(e.code === 'ENOENT' ? new Error(`${cmd} is not installed`) : e) })
+    child.on('close', (code) => {
+      clearTimeout(timer)
+      if (code === 0 && out.trim()) resolve(out.trim())
+      else reject(new Error((err || out).trim().split('\n').pop() || `${cmd} exited with ${code}`))
+    })
+    child.stdin.end(input)
+  })
+}
+
+/** The summarizing command: QUILT_SUMMARY_CMD (for tests or other tools) or Claude Code's CLI. */
+function command (kind) {
+  const custom = process.env.QUILT_SUMMARY_CMD
+  if (custom) {
+    const [cmd, ...args] = custom.split(' ').filter(Boolean)
+    return [cmd, [...args, INSTRUCTIONS[kind]]]
+  }
+  return ['claude', ['-p', '--model', 'haiku', '--no-session-persistence', INSTRUCTIONS[kind]]]
+}
+
+/**
+ * Returns summarize(kind, text) -> Promise<{ text, how: 'ai'|'shortened'|'as-is' }>.
+ * `onWarn` hears (once per failure spell) why summaries fell back to shortening.
+ */
+export function createSummarizer ({ onWarn = () => {}, run = runCli } = {}) {
+  let brokenUntil = 0
+  return async function summarize (kind, text) {
+    text = String(text || '')
+    if (!INSTRUCTIONS[kind]) return { text, how: 'as-is' }
+    if (text.length <= SHORT_ENOUGH) return { text, how: 'as-is' }
+    if (Date.now() >= brokenUntil) {
+      try {
+        const [cmd, args] = command(kind)
+        const out = await run(cmd, args, text.slice(0, 20000))
+        return { text: out.replace(/\s+/g, ' ').trim().slice(0, 400), how: 'ai' }
+      } catch (err) {
+        brokenUntil = Date.now() + RETRY_AFTER_MS
+        onWarn(/auth|log ?in|sign ?in|OAuth/i.test(err.message)
+          ? 'Summaries are shortened for now: your claude CLI isn\'t signed in (run `claude` once in a terminal to sign in).'
+          : `Summaries are shortened for now: ${err.message}`)
+      }
+    }
+    return { text: shorten(text), how: 'shortened' }
+  }
+}
+
+/** One clean line from the model: no quotes, "Title:" label or trailing period. Empty when nothing is left. */
+export function cleanTaskTitle (out) {
+  const line = String(out || '').split(/\r?\n/).map((s) => s.trim()).find(Boolean) || ''
+  return line.replace(/^(task|title)\s*:\s*/i, '').replace(/^["'`*]+|["'`*]+$/g, '').replace(/[.!]+$/, '').trim().slice(0, MAX_TASK_TITLE)
+}
+
+/**
+ * Returns taskTitle(request, files) -> Promise<string|null>: a short title for an
+ * auto-created task ("Add dark mode"), or null when the CLI isn't available.
+ * Unlike summaries, short requests are titled too: "okay, go ahead" is short but no title.
+ */
+export function createTaskTitler ({ onWarn = () => {}, run = runCli } = {}) {
+  let brokenUntil = 0
+  return async function taskTitle (request, files = []) {
+    const text = String(request || '').trim()
+    if (!text || Date.now() < brokenUntil) return null
+    const input = files.length ? `${text.slice(0, 4000)}\n\nFiles it changed: ${files.slice(0, 10).join(', ')}` : text.slice(0, 4000)
+    try {
+      const [cmd, args] = command('task')
+      return cleanTaskTitle(await run(cmd, args, input)) || null
+    } catch (err) {
+      brokenUntil = Date.now() + RETRY_AFTER_MS
+      onWarn(`Task titles use the start of your prompt for now: ${err.message}`)
+      return null
+    }
+  }
+}

package/src/sync-words.js

@@ -0,0 +1,42 @@
+// Where each branch stands with GitHub (relay-sync.js syncStatus), in words for agents: the
+// quilt_sync_status tool, hosted (relay-mcp.js) and in a folder (mcp.js), from the branch list.
+
+const short = (sha) => (typeof sha === 'string' && sha ? sha.slice(0, 7) : '')
+const plural = (n, w) => `${n} ${w}${n === 1 ? '' : 's'}`
+
+/** One line for branch entry `b` ({ key, relay: { repo, sync, ... } }), or null when it doesn't follow GitHub. */
+export function syncLine (b) {
+  const r = b && b.relay
+  const s = r && r.sync
+  if (!s) return null
+  const repo = String(r.repo || '').replace(/^github\.com\//, '')
+  const at = s.revision ? ` at ${short(s.revision)}` : ''
+  const head = `${b.key}${repo ? ` (${repo})` : ''}`
+  switch (s.state) {
+    case 'synced': return `${head}: in step with GitHub${at}; nothing uncommitted.`
+    case 'github-pending': return `${head}: has GitHub's latest${at}; ${plural(s.pending || 0, 'file')} changed in the session and not committed (quilt_git_commit commits yours).`
+    case 'conflict-held': return `${head}: ${s.why || `${plural(s.held || 0, 'file')} held for a merge`}${at}; the merger proposes with quilt_clash (quilt_clash status lists them).`
+    case 'pr-pending': return `${head}: ${r.leased ? 'another session holds this branch' : 'protected on GitHub'}, so commits go through ${s.pr && s.pr.number ? `pull request #${s.pr.number}${s.pr.url ? ` (${s.pr.url})` : ''}` : 'a pull request (opened with the next commit)'}${at}.`
+    case 'offline': return `${head}: GitHub unreachable${s.since ? ` since ${new Date(s.since).toISOString().slice(11, 16)} UTC` : ''}; the session keeps working, and commits asked for go when it answers.`
+    case 'permission-held': return `${head}: ${s.why || 'GitHub refused the relay'}.`
+    default: return `${head}: not syncing with GitHub (${s.why || 'paused'}).`
+  }
+}
+
+/** The files of a branch that are GitHub's version, not edited in the session since: one line, or ''. */
+export function fromGithubLine (s) {
+  const files = s && Array.isArray(s.fromGithubFiles) ? s.fromGithubFiles : []
+  if (!files.length) return ''
+  const more = (s.fromGithub || files.length) - files.length
+  return `  From GitHub, not edited here since: ${files.map((f) => `${f.path} (${short(f.sha)}${f.by ? ` by ${f.by}` : ''})`).join(', ')}${more > 0 ? `, and ${more} more` : ''}.`
+}
+
+/** Every branch that follows GitHub, the caller's first: one line each. */
+export function syncStatusText (list, { mine = '' } = {}) {
+  const rows = (Array.isArray(list) ? list : []).filter((b) => b && b.relay && b.relay.sync)
+  if (!rows.length) return 'No branch of this session syncs with GitHub (none follows a GitHub repository, or the relay has no git sync).'
+  rows.sort((a, b) => (a.key === mine ? -1 : b.key === mine ? 1 : 0))
+  return rows.map((b) => [syncLine(b), fromGithubLine(b.relay.sync)].filter(Boolean).join('\n')).filter(Boolean).join('\n')
+}
+
+export const SYNC_STATUS_DESCRIPTION = 'Where each branch of the session stands with GitHub: in step (with the commit it is at), files changed and not committed, files held for a merge, commits going through a pull request (a protected branch, or another session holds it), GitHub unreachable, or sync paused and why. Pushes and merges on GitHub come in by themselves, and the files that are GitHub\'s version, not edited here since, are listed with the commit that brought them; nothing goes to GitHub until someone commits.'