heyquilt 0.0.1 → 0.3.90

package/src/agent-join.js

@@ -0,0 +1,370 @@
+// `quilt agent join|whoami`: join Quilt as an agent from a terminal, the way an
+// AI uses an invite link: send a short profile to the link, get keys back, and
+// keep them in ~/.quilt/agents/<name>.json (readable only by you). An agent whose home
+// folder is wiped between turns (a hosted sandbox) keeps them in the project's .quilt/
+// instead (--here), and is found there from anywhere in the project.
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import crypto from 'node:crypto'
+import { quiltHome } from './legacy.js'
+import { generateIdentity, signAgentResume } from './identity.js'
+import { writePrivateJson } from './private-file.js'
+import { encodeAgentEnvKey, decodeAgentEnvKey } from './ui/agent-env-key.js'
+
+export const DEFAULTS = { provider: 'Quilt CLI', type: 'command-line agent' }
+const NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,39}$/
+const NOT_A_LINK = "That doesn't look like an agent invite link. Copy the whole link from Quilt."
+// Refresh a little early so the access key doesn't lapse mid-request.
+const EARLY_MS = 60 * 1000
+// A refresh lock is stale once the process holding it is gone; as a safety net, also once
+// it is this old (a live holder never needs this long: its refresh times out first).
+const LOCK_MAX_AGE_MS = 5 * 60 * 1000
+const LOCK_RETRY_MS = 50
+// A refresh the API has already done can't be undone: cutting it off loses the new keys,
+// and the spent refresh key later revokes the agent. So it gets a long time to answer.
+const REFRESH_TIMEOUT_MS = 120 * 1000
+// How long to wait for another process's refresh before giving up: longer than a refresh can take.
+const LOCK_WAIT_MS = 150 * 1000
+/** For tests: how the refresh and lock timeouts nest. */
+export const REFRESH_TIMING = Object.freeze({ refreshTimeoutMs: REFRESH_TIMEOUT_MS, lockWaitMs: LOCK_WAIT_MS, lockMaxAgeMs: LOCK_MAX_AGE_MS })
+
+export function agentFile (name, dir) {
+  if (!NAME.test(String(name || ''))) throw new Error('--name must be 1 to 40 letters, numbers, dots, dashes or underscores')
+  return path.join(dir || agentsHome(name), 'agents', `${name}.json`)
+}
+
+/** The folders at and above `from`, up to (not including) your home folder. */
+function upFrom (from) {
+  const home = path.resolve(os.homedir())
+  const dirs = []
+  for (let d = path.resolve(from); d !== home; d = path.dirname(d)) {
+    dirs.push(d)
+    if (path.dirname(d) === d) break
+  }
+  return dirs
+}
+
+/** The project's .quilt holding agents saved with --here, at or above `from`; null when there is none. */
+export function projectAgentsHome (from = process.cwd()) {
+  for (const d of upFrom(from)) if (fs.existsSync(path.join(d, '.quilt', 'agents'))) return path.join(d, '.quilt')
+  return null
+}
+
+/** Where an agent's keys are: the project's .quilt when it was saved there, else ~/.quilt. */
+function agentsHome (name) {
+  const here = projectAgentsHome()
+  return here && fs.existsSync(path.join(here, 'agents', `${name}.json`)) ? here : quiltHome()
+}
+
+const LOCAL_HOSTS = new Set(['localhost', '127.0.0.1', '::1', '[::1]'])
+
+/** The API's address and the token in an invite link. Plain http is only
+ * allowed for a local address (testing); anything else must be https. */
+export function parseJoinLink (link) {
+  let u
+  try { u = new URL(String(link)) } catch { throw new Error(NOT_A_LINK) }
+  const m = u.pathname.match(/^\/v1\/join\/(qj_[A-Za-z0-9_-]+)\/?$/)
+  const protoOk = u.protocol === 'https:' || (u.protocol === 'http:' && LOCAL_HOSTS.has(u.hostname))
+  if (!m || !protoOk) throw new Error(NOT_A_LINK)
+  return { api: u.origin, token: m[1] }
+}
+
+async function send (fetchImpl, api, method, route, body, key, extra = {}) {
+  const res = await fetchImpl(String(api).replace(/\/+$/, '') + route, {
+    ...extra,
+    method,
+    headers: { ...(body ? { 'content-type': 'application/json' } : {}), ...(key ? { authorization: `Bearer ${key}` } : {}) },
+    body: body ? JSON.stringify(body) : undefined
+  })
+  return { status: res.status, ok: res.ok, body: await res.json().catch(() => null) }
+}
+
+/** Makes sure the agents directory exists, is not a symlink, and is private. */
+function ensureAgentsDir (dir) {
+  let st
+  try { st = fs.lstatSync(dir) } catch (err) {
+    if (err.code !== 'ENOENT') throw err
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 })
+    return
+  }
+  if (st.isSymbolicLink()) throw new Error(`Refusing to use ${dir}: it's a symlink`)
+  // Tighten up permissions someone (or some older version) left too loose.
+  if ((st.mode & 0o777) !== 0o700) fs.chmodSync(dir, 0o700)
+}
+
+/** Saves the agent's file privately (see private-file.js), in a private agents folder. */
+function save (file, data) {
+  ensureAgentsDir(path.dirname(file))
+  writePrivateJson(file, data)
+}
+
+function load (file, name) {
+  let raw
+  try {
+    raw = fs.readFileSync(file, 'utf8')
+  } catch (err) {
+    if (err.code === 'ENOENT') throw new Error(`No agent called ${name} here. Run: quilt agent join <link> --name ${name}`)
+    throw new Error(`Couldn't read the saved agent file for ${name} (corrupt or unreadable): ${err.message}`)
+  }
+  try {
+    return JSON.parse(raw)
+  } catch (err) {
+    throw new Error(`Couldn't read the saved agent file for ${name} (corrupt or unreadable): ${err.message}`)
+  }
+}
+
+/** The agent saved under this name, or null when there is none (or it can't be read). */
+function savedOrNull (file) {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')) } catch { return null }
+}
+
+/**
+ * Uses an invite link once and saves the agent's keys. An agent that joined before comes
+ * back as itself: with `agentId`, or with the id saved under this name on this computer
+ * (then it keeps its own key too). Without either it joins as a new agent.
+ */
+export async function agentJoin ({ link, name, agentId, provider = DEFAULTS.provider, type = DEFAULTS.type, description = '', dir, here = false, fetch: fetchImpl = globalThis.fetch, log = console.log }) {
+  const file = agentFile(name, dir || (here ? path.resolve('.quilt') : undefined))
+  const { api, token } = parseJoinLink(link)
+  const before = savedOrNull(file)
+  const id = agentId || (before?.api === api ? before.agentId : undefined)
+  // The agent's own Ed25519 key, for joining sessions. A returning agent keeps the one it has.
+  const identity = id && before?.agentId === id && before.identity ? before.identity : generateIdentity()
+  const r = await send(fetchImpl, api, 'POST', `/v1/join/${token}`, { name, provider, type, description, publicKey: identity.publicKey, ...(id ? { agentId: id } : {}) })
+  if (!r.ok) throw new Error(r.body?.error || `Couldn't join Quilt (${r.status}).`)
+  const saved = { name, api, agentId: r.body.agentId, accessKey: r.body.accessKey, accessExpiresAt: r.body.accessExpiresAt, refreshKey: r.body.refreshKey, refreshExpiresAt: r.body.refreshExpiresAt, resumeKey: r.body.resumeKey, identity }
+  save(file, saved)
+  const inProject = !dir && path.dirname(path.dirname(file)) !== quiltHome()
+  // Keys in a project folder: git leaves them out, whatever the project's .gitignore says.
+  if (inProject) fs.writeFileSync(path.join(path.dirname(file), '.gitignore'), '*\n')
+  log(`${r.body.rejoined ? 'Joined Quilt again as' : 'Joined Quilt as'} ${name} (agent id ${saved.agentId}: public, keep it to come back as yourself with a new invite). Keys saved in ${file}${inProject ? ": this project's own .quilt, which Quilt never syncs and git ignores. quilt finds them from anywhere in this folder" : ''}`)
+  return saved
+}
+
+/**
+ * Uses an invite link once and keeps nothing on this computer: for a sandbox, whose agent signs in
+ * with a QUILT_AGENT_KEY made from the keys this returns ({ api, agentId, accessKey, ... }). The
+ * agent joins without a key of its own (it works over HTTPS, like a hosted agent).
+ */
+export async function agentJoinUnsaved ({ link, name, agentId, provider = DEFAULTS.provider, type = DEFAULTS.type, description = '', fetch: fetchImpl = globalThis.fetch }) {
+  agentFile(name, os.tmpdir()) // the same check of the name as a saved agent's
+  const { api, token } = parseJoinLink(link)
+  const r = await send(fetchImpl, api, 'POST', `/v1/join/${token}`, { name, provider, type, description, ...(agentId ? { agentId } : {}) })
+  if (!r.ok) throw new Error(r.body?.error || `Couldn't join Quilt (${r.status}).`)
+  return { ...r.body, api } // the address the link reached (the API names its public one)
+}
+
+/**
+ * A new QUILT_AGENT_KEY for the agent signed in with `accessKey` at `api`, working in `session`
+ * (its invite link): a new app key the agent's person sees and can revoke on heyquilt.com.
+ */
+export async function makeEnvKey ({ api, accessKey, session, keyName, fetch: fetchImpl = globalThis.fetch }) {
+  if (!session) throw new Error('--session <session invite link> is needed: the key says which session the sandbox works in.')
+  const r = await send(fetchImpl, api, 'POST', '/v1/agents/me/keys', { session, ...(keyName ? { name: keyName } : {}) }, accessKey)
+  if (!r.ok) throw Object.assign(new Error(r.body?.error || `Couldn't make the key (${r.status}).`), { status: r.status })
+  // The key names the API's public address; one reached at another address (self-hosted, a test) keeps that one.
+  const k = decodeAgentEnvKey(r.body.envKey)
+  return k.api === String(api).replace(/\/+$/, '') ? r.body.envKey : encodeAgentEnvKey({ ...k, api })
+}
+
+/** makeEnvKey for an agent saved on this computer (quilt agent join), signing it back in when its keys were revoked. */
+export async function savedAgentEnvKey ({ name, session, keyName, fetch: fetchImpl = globalThis.fetch }) {
+  const saved = await agentAccess({ name, fetch: fetchImpl })
+  try {
+    return await makeEnvKey({ api: saved.api, accessKey: saved.accessKey, session, keyName, fetch: fetchImpl })
+  } catch (err) {
+    if (err.status !== 401) throw err
+    const back = await agentResume({ name, accessKey: saved.accessKey, fetch: fetchImpl })
+    if (!back) throw err
+    return makeEnvKey({ api: back.api, accessKey: back.accessKey, session, keyName, fetch: fetchImpl })
+  }
+}
+
+async function refresh (saved, file, fetchImpl) {
+  const r = await send(fetchImpl, saved.api, 'POST', '/v1/agents/token', { refreshKey: saved.refreshKey }, null, { signal: AbortSignal.timeout(REFRESH_TIMEOUT_MS) })
+  if (r.status === 401 && canResume(saved)) return resume(saved, file, fetchImpl, r)
+  if (!r.ok) throw refused(r, `Couldn't refresh the agent's keys (${r.status}).`)
+  return keep(saved, file, r.body)
+}
+
+/**
+ * The refresh key was turned away: most often a refresh the API made whose reply never
+ * arrived (the computer slept or went offline), so the key we kept was already spent and
+ * the API revoked the agent's keys. The agent signs for the key it joined with and gets
+ * new ones. `turnedAway` is the refresh's reply, the error to give if this fails too.
+ */
+async function resume (saved, file, fetchImpl, turnedAway) {
+  // The resume key every agent gets when it joins; agents saved before resume keys sign
+  // with their own key instead (the API's clock, not a test's: it has to be close to it).
+  const at = Date.now()
+  const body = saved.resumeKey ? { resumeKey: saved.resumeKey } : { agentId: saved.agentId, at, signature: signAgentResume(saved.identity, saved.agentId, at) }
+  const r = await send(fetchImpl, saved.api, 'POST', '/v1/agents/resume', body, null, { signal: AbortSignal.timeout(REFRESH_TIMEOUT_MS) })
+  if (r.ok) return keep(saved, file, r.body)
+  // An API without resume, or that doesn't know the agent: the refresh's answer says what happened.
+  if (r.status === 404) throw refused(turnedAway, `Couldn't refresh the agent's keys (${turnedAway.status}).`)
+  // Revoked by a person, a signature that doesn't match, or a clock that's off: signed out.
+  if (r.status === 400 || r.status === 401) throw Object.assign(refused(r, `Couldn't sign the agent back in (${r.status}).`), { status: 401 })
+  throw refused(r, `Couldn't sign the agent back in (${r.status}).`)
+}
+
+const canResume = (saved) => !!(saved.resumeKey || saved.identity)
+
+const refused = (r, fallback) => Object.assign(new Error(r.body?.error || fallback), { status: r.status })
+
+function keep (saved, file, body) {
+  const next = { ...saved, accessKey: body.accessKey, accessExpiresAt: body.accessExpiresAt, refreshKey: body.refreshKey, refreshExpiresAt: body.refreshExpiresAt }
+  // Save straight away: the old refresh key is spent, and using it again would revoke the agent.
+  save(file, next)
+  return next
+}
+
+/** A saved agent's file: { name, api, agentId, accessKey, refreshKey, …, resumeKey, identity }. */
+export function readAgent ({ name, dir }) {
+  return load(agentFile(name, dir), name)
+}
+
+const readLock = (lock) => { try { return fs.readFileSync(lock, 'utf8') } catch { return null } }
+
+/** Whether a lock holding `contents` ("<pid>.<token>") and last changed at `mtimeMs` is stale. */
+function lockIsStale (contents, mtimeMs) {
+  if (Date.now() - mtimeMs > LOCK_MAX_AGE_MS) return true
+  const pid = Number(String(contents).split('.')[0])
+  // No pid yet (its holder has only just made it): only age can make it stale.
+  if (!Number.isInteger(pid) || pid <= 0) return false
+  try {
+    process.kill(pid, 0)
+    return false
+  } catch (err) {
+    return err.code === 'ESRCH' // EPERM: running, as someone else
+  }
+}
+
+/**
+ * Removes the lock when its holder is gone, unless it changed while we looked.
+ * Returns true when the lock is gone (so try to take it again). Two processes
+ * removing one crashed holder's lock at the very same instant can both get in;
+ * that needs a crash and a tie, so it is accepted. (`between` lets tests step in
+ * between the two reads.)
+ */
+export function takeOverStale (lock, between = () => {}) {
+  let seen, st
+  try {
+    seen = fs.readFileSync(lock, 'utf8')
+    st = fs.statSync(lock)
+  } catch {
+    return true // gone already
+  }
+  if (!lockIsStale(seen, st.mtimeMs)) return false
+  between()
+  if (readLock(lock) !== seen) return false
+  fs.rmSync(lock, { force: true })
+  return true
+}
+
+/**
+ * Runs `fn` holding `<file>.lock`, so only one process at a time refreshes an agent's
+ * keys: a refresh key used twice gets the agent revoked for good.
+ */
+export async function withLock (file, fn) {
+  const lock = `${file}.lock`
+  const token = `${process.pid}.${crypto.randomBytes(8).toString('hex')}`
+  const until = Date.now() + LOCK_WAIT_MS
+  for (;;) {
+    let fd = null
+    try {
+      fd = fs.openSync(lock, 'wx', 0o600)
+    } catch (err) {
+      if (err.code !== 'EEXIST') throw err
+    }
+    if (fd !== null) {
+      try { fs.writeSync(fd, token) } finally { fs.closeSync(fd) }
+      try {
+        return await fn()
+      } finally {
+        // Only our own lock, never one another process has since made.
+        if (readLock(lock) === token) fs.rmSync(lock, { force: true })
+      }
+    }
+    if (takeOverStale(lock)) continue
+    if (Date.now() > until) throw new Error(`Another Quilt process is stuck refreshing the agent's keys. Remove ${lock} and try again.`)
+    await new Promise((resolve) => setTimeout(resolve, LOCK_RETRY_MS))
+  }
+}
+
+/** The saved agent with a working access key, refreshed first when it has (nearly) run out. */
+export async function agentAccess ({ name, dir, fetch: fetchImpl = globalThis.fetch, now = Date.now }) {
+  const file = agentFile(name, dir)
+  const fresh = (saved) => saved.accessExpiresAt - EARLY_MS > now()
+  const saved = load(file, name)
+  if (fresh(saved)) return saved
+  return withLock(file, () => {
+    // Another process may have refreshed while we waited: use its keys.
+    const latest = load(file, name)
+    return fresh(latest) ? latest : refresh(latest, file, fetchImpl)
+  })
+}
+
+/**
+ * The API turned `accessKey` away before it ran out (its keys were revoked): signs back in
+ * with the agent's key. Resolves to the saved agent with new keys, the keys another process
+ * already got, or null for an agent saved with neither a resume key nor a key of its own.
+ */
+export async function agentResume ({ name, dir, accessKey, fetch: fetchImpl = globalThis.fetch }) {
+  const file = agentFile(name, dir)
+  return withLock(file, () => {
+    const latest = load(file, name)
+    if (latest.accessKey !== accessKey) return latest
+    if (!canResume(latest)) return null
+    return resume(latest, file, fetchImpl, { status: 401, body: { error: "This agent's keys were revoked. Invite it again." } })
+  })
+}
+
+/** Who the agent is, refreshing its keys first when the access key has (nearly) run out. */
+export async function agentWhoami ({ name, dir, fetch: fetchImpl = globalThis.fetch, now = Date.now }) {
+  const saved = await agentAccess({ name, dir, fetch: fetchImpl, now })
+  let r = await send(fetchImpl, saved.api, 'GET', '/v1/agents/me', null, saved.accessKey)
+  if (r.status === 401) {
+    const back = await agentResume({ name, dir, accessKey: saved.accessKey, fetch: fetchImpl })
+    if (back) r = await send(fetchImpl, back.api, 'GET', '/v1/agents/me', null, back.accessKey)
+  }
+  if (!r.ok) throw new Error(r.body?.error || `Couldn't reach Quilt (${r.status}).`)
+  return r.body
+}
+
+/** Whether this agent's keys are in the project (saved with --here), not in ~/.quilt. */
+export function keptInProject (name) {
+  try { return path.dirname(path.dirname(agentFile(name))) !== quiltHome() } catch { return false }
+}
+
+/** The names of the agents saved in `dir`, or on this computer and in this project. */
+export function savedAgents (dir) {
+  const names = (d) => {
+    try {
+      return fs.readdirSync(path.join(d, 'agents')).filter((f) => f.endsWith('.json') && !f.startsWith('.')).map((f) => f.slice(0, -5))
+    } catch {
+      return []
+    }
+  }
+  const all = dir ? names(dir) : [...names(quiltHome()), ...(projectAgentsHome() ? names(projectAgentsHome()) : [])]
+  return [...new Set(all)].sort()
+}
+
+/** Which saved agent a session joins as: the one named, or the only one there is. */
+export function pickAgent ({ agent, dir } = {}) {
+  if (agent) return agent
+  const all = savedAgents(dir)
+  if (all.length === 1) return all[0]
+  if (!all.length) throw new Error('This computer has no Quilt agent yet. The person you work with can invite one on heyquilt.com, then run: quilt agent join <link> --name <name>')
+  throw new Error(`This computer has several Quilt agents (${all.join(', ')}). Say which one to join as.`)
+}
+
+export function describeAgent (me) {
+  const where = me.agent.kind === 'org' ? `an agent in ${me.agent.org.name}` : 'your personal agent'
+  const lines = [`${me.agent.name} (${me.agent.provider}, ${me.agent.type}): ${where}`]
+  // Public: what the agent gives with a new invite to come back as itself.
+  if (me.agent.id) lines.push(`Agent id: ${me.agent.id}`)
+  if (me.role) lines.push(`Role: ${me.role.name}`)
+  for (const t of me.teams) lines.push(`Team ${t.name}: ${t.access}${t.scopes.length ? `, folders ${t.scopes.join(', ')}` : ''}`)
+  return lines.join('\n')
+}

package/src/agent-task-workflow.js

@@ -0,0 +1,176 @@
+// Required workflow every agent must follow when it picks up a ticket, the
+// briefing it gets when it does, and the notes it owes before QA (then Done).
+// Included in MCP server instructions (local + relay) and in the project
+// agent guides written by `quilt setup` (AGENTS.md / CLAUDE.md).
+
+/** Heading of the project's own checks in AGENTS.md / CLAUDE.md (matched case-insensitively on "## Verif…"). */
+export const CHECKLIST_HEADING = '## Verifying a change'
+const CHECKLIST_RE = /^##\s+verif[^\n]*\n([\s\S]*?)(?=^##\s|(?![\s\S]))/im
+
+/** The least an agent must say about what it verified before a ticket may be Done. */
+export const MIN_VERIFIED = 12
+export const MAX_VERIFIED = 1000
+
+/**
+ * One short paragraph: grok → plan → build → test → QA with qaNotes.
+ * Keep this the single source of truth so every briefing path says the same thing.
+ */
+export const TASK_WORKFLOW =
+  'When you pick up a ticket (move it to In progress, or start work on one assigned to you): ' +
+  'first grok the codebase and workspace (explore the relevant files, how they fit together, and quilt_history for recent changes to them) ' +
+  'and read the project\'s rules and design system with quilt_project_rules (the same whatever tool you run in), ' +
+  'then implement a plan, then build the change, then test it (confirm the tests you touch pass) ' +
+  'and run the project\'s own checks under "Verifying a change" in AGENTS.md. ' +
+  'When finished, move the ticket to QA (not straight to Done) with `qaNotes`: describe the changes you made and how you self-validated them. ' +
+  'Keep qaNotes, verified and task comments brief: a few short sentences, no logs or play-by-play. ' +
+  'Moving to Done still requires `verified` (what you ran and what you saw). Unit tests passing is not enough when the app itself was not exercised. ' +
+  'Taking a task puts your folder on a branch of your own for it (quilt/<you>/<task>). Get the task\'s files into git before you move it to QA: commit only those files and push the branch; Quilt opens the pull request and ties it to the task. Done merges that pull request once its checks pass: a person moves it to Done (you may, when the owner lets agents push to any branch). Without a folder, `quilt_git_commit` with the task (the pull request opens by itself); when agents may not commit, ask with `quilt_request_commit`. Work only in the session has not shipped.'
+
+/** Markdown bullets for AGENTS.md / CLAUDE.md (same steps as TASK_WORKFLOW). */
+export const TASK_WORKFLOW_MD =
+  '- When you pick up a ticket (move it to In progress, or start work on one assigned to you):\n' +
+  '  1. **Grok** the codebase and workspace - explore the relevant files, how they fit together, and `quilt_history` for recent changes to them; read the project\'s rules and design system with `quilt_project_rules`.\n' +
+  '  2. **Plan** the change.\n' +
+  '  3. **Build** it.\n' +
+  '  4. **Test** it: confirm the tests you touch pass, then run the project\'s own checks under "Verifying a change" below.\n' +
+  '  5. **QA**: move to `qa` (not straight to Done) with `qaNotes` describing the changes and how you self-validated them.\n' +
+  '     Keep `qaNotes`, `verified` and task comments brief: a few short sentences, no logs or play-by-play.\n' +
+  '  6. **Done** (after QA): `quilt_move_task` to `done` needs `verified`, what you ran and what you saw. Unit tests passing is not enough when the app itself was not exercised. Done merges the task\'s pull request once its checks pass; when the owner keeps agents to branches of their own, a person moves it to Done.\n' +
+  '  7. **Commit and push** before QA: only the task\'s files, with a message, on the branch Quilt put your folder on when you took the task (quilt/<you>/<task>); Quilt opens the pull request. Without a folder, `quilt_git_commit` with the task. When agents may not commit, ask with `quilt_request_commit`. Work only in the session has not shipped.'
+
+/** Scaffolded into AGENTS.md by `quilt setup` when the project has no checklist yet. Owners edit it in place. */
+export const CHECKLIST_SCAFFOLD = `${CHECKLIST_HEADING}
+
+Every agent reads this when it picks up a ticket and must run these checks before moving
+it to QA. Replace the examples with what proves a change works in this project.
+
+- Run the test suite and make sure it passes.
+- Start the app and exercise the part you changed; confirm it loads and behaves.
+- Note anything this project needs that tests do not catch (allowlists, registrations, config).
+`
+
+const PLACEHOLDER = /Replace the examples with what proves a change works/
+
+/**
+ * The checklist body under "## Verifying a change" in an agent guide, trimmed.
+ * '' when the text has no such section.
+ */
+export function extractChecklist (text) {
+  const m = CHECKLIST_RE.exec(String(text || ''))
+  if (!m) return ''
+  return m[1].replace(/\s+$/, '').replace(/^\s*\n/, '')
+}
+
+/** The first non-empty checklist among several guide texts (AGENTS.md first, then CLAUDE.md). */
+export function pickChecklist (...texts) {
+  for (const t of texts) { const c = extractChecklist(t); if (c) return c }
+  return ''
+}
+
+function checklistBlock (checklist) {
+  if (!checklist) {
+    return 'This project has no "Verifying a change" section in AGENTS.md yet. Run its tests and exercise the app yourself, ' +
+      'and ask the owner what proves a change works here.'
+  }
+  const head = PLACEHOLDER.test(checklist)
+    ? 'This project\'s checks (AGENTS.md, still the template: ask the owner what proves a change works here):'
+    : 'This project\'s checks (from AGENTS.md):'
+  return `${head}\n${checklist}`
+}
+
+function agoText (ts, now) {
+  const s = Math.max(0, Math.round((now - ts) / 1000))
+  if (s < 60) return `${s}s ago`
+  if (s < 3600) return `${Math.floor(s / 60)}m ago`
+  if (s < 172800) return `${Math.floor(s / 3600)}h ago`
+  return `${Math.floor(s / 86400)}d ago`
+}
+
+/**
+ * What an agent gets when it moves a ticket to In progress: the ticket, its files,
+ * recent changes to them (from the chronology), who holds claims on them, the
+ * workflow and the project's checks.
+ * @param {object} o
+ * @param {{id:string,title:string,files?:string[]}} o.task
+ * @param {Array<{by:string,path:string,kind:string,detail?:string,ts:number,task?:{title:string}|null}>} [o.history] oldest first
+ * @param {Array<{by:string,pattern:string,note?:string}>} [o.claims]
+ * @param {string} [o.checklist]
+ * @param {string} [o.me]
+ * @param {number} [o.now]
+ */
+export function pickupBrief ({ task, history = [], claims = [], checklist = '', me = '', now = Date.now() }) {
+  const files = task?.files || []
+  const lines = [`Picked up "${task?.title || 'this ticket'}" [${task?.id || ''}].`]
+  lines.push(files.length ? `Files: ${files.join(', ')}` : 'Files: none listed. Add them with quilt_assign_task once you know which you will touch.')
+  const recent = history.slice(-8)
+  if (recent.length) {
+    lines.push('', files.length ? 'Recent changes to these files (oldest first):' : 'Recent changes in the project (oldest first):')
+    for (const e of recent) {
+      const who = e.by === me ? 'you' : e.by
+      const forTask = e.task?.title ? ` for "${e.task.title}"` : ''
+      lines.push(`- [${agoText(e.ts, now)}] ${who} ${e.kind} ${e.path}${e.detail ? ` (${e.detail})` : ''}${forTask}`)
+    }
+    lines.push('Read the diffs with quilt_history before building on them.')
+  } else {
+    lines.push('', files.length ? 'No recorded changes to these files yet.' : 'No recorded changes yet.')
+  }
+  const comments = Array.isArray(task?.comments) ? task.comments.slice(-5) : []
+  if (comments.length) {
+    lines.push('', 'Comments on the task (latest last):')
+    for (const c of comments) lines.push(`- ${c.by === me ? 'you' : c.by} [${agoText(c.ts, now)}]: ${String(c.text).replace(/\n/g, '\n  ')}`)
+  }
+  const others = claims.filter((c) => c.by !== me)
+  if (others.length) {
+    lines.push('', 'Claims to respect (ask for the file with quilt_request_file instead of editing it):')
+    for (const c of others) lines.push(`- ${c.pattern} by ${c.by}${c.note ? ` (${c.note})` : ''}`)
+  }
+  lines.push('', TASK_WORKFLOW, '', checklistBlock(checklist))
+  return lines.join('\n')
+}
+
+/** Reminder appended when an agent moves a task to In progress (short form, no context). */
+export function pickupReminder (title) {
+  const who = title ? `"${title}"` : 'this ticket'
+  return `Picked up ${who}. ${TASK_WORKFLOW}`
+}
+
+/** True when `verified` is enough evidence to move a ticket to Done. */
+export function verifiedEnough (verified) {
+  return String(verified || '').trim().length >= MIN_VERIFIED
+}
+
+/** Why a move to Done was refused, and what to do instead. */
+export function doneRefusal ({ task, checklist = '' } = {}) {
+  const title = task?.title ? `"${task.title}"` : 'this ticket'
+  return `Not moved: ${title} needs \`verified\` before it can be Done. ` +
+    'Say what you ran and what you saw (for example: "npm test passed, 612 tests; launched the app and the session page rendered with the new column"). ' +
+    'Vague words like "tested" are not enough.\n\n' + checklistBlock(checklist)
+}
+
+/** The line shown on the board for a finished ticket's evidence. */
+export function verifiedLine (task) {
+  const v = String(task?.verified || '').replace(/\s+/g, ' ').trim()
+  if (!v) return ''
+  return v.length > 160 ? `${v.slice(0, 157)}…` : v
+}
+
+/** True when `qaNotes` is enough to move a ticket to QA. */
+export function qaNotesEnough (qaNotes) {
+  return String(qaNotes || '').trim().length >= MIN_VERIFIED
+}
+
+/** Why a move to QA was refused, and what to do instead. */
+export function qaRefusal ({ task, checklist = '' } = {}) {
+  const title = task?.title ? `"${task.title}"` : 'this ticket'
+  return `Not moved: ${title} needs \`qaNotes\` before it can go to QA. ` +
+    'Describe the changes you made and how you self-validated them ' +
+    '(for example: "Added QA column and qaNotes field; npm test passed; board shows four columns"). ' +
+    'Vague words like "done" are not enough.\n\n' + checklistBlock(checklist)
+}
+
+/** The line shown for a QA ticket's change description. */
+export function qaNotesLine (task) {
+  const v = String(task?.qaNotes || '').replace(/\s+/g, ' ').trim()
+  if (!v) return ''
+  return v.length > 160 ? `${v.slice(0, 157)}…` : v
+}

package/src/agents/actions.js

@@ -0,0 +1,85 @@
+// Turns an AI tool call into one short, shareable line ("Edited src/app.ts",
+// "Ran npm test"). Deliberately lossy: command arguments, file contents and
+// output never leave the machine.
+import path from 'node:path'
+
+const EDIT = new Set(['edit', 'multiedit', 'notebookedit', 'edit_file', 'search_replace', 'str_replace', 'strreplace', 'apply_patch', 'write'])
+const READ = new Set(['read', 'read_file'])
+const SEARCH = new Set(['grep', 'glob', 'grep_search', 'file_search', 'glob_file_search', 'codebase_search', 'list_dir', 'ls'])
+const RUN = new Set(['bash', 'run_terminal_cmd', 'run_terminal_command', 'run_command', 'shell'])
+const DELETE = new Set(['delete_file'])
+
+/**
+ * @param {string} tool   tool name as the agent reported it
+ * @param {object} input  tool input
+ * @param {string} dir    the synced folder, for relative paths
+ * @param {{ existed?: (abs: string) => boolean }} [opts]
+ */
+export function describeAction (tool, input = {}, dir = '', opts = {}) {
+  const name = String(tool || '').trim()
+  // Cursor versions its tools ("edit_file_v2"); the suffix doesn't change what they do.
+  const key = name.toLowerCase().replace(/_v\d+$/, '')
+  input = input && typeof input === 'object' ? input : {}
+
+  if (EDIT.has(key)) {
+    const file = pickPath(input)
+    const shown = file ? rel(file, dir) : 'a file'
+    if (key === 'write' && file && opts.existed && !opts.existed(path.resolve(dir || '/', file))) return `Created ${shown}`
+    return `Edited ${shown}`
+  }
+  if (DELETE.has(key)) {
+    const file = pickPath(input)
+    return file ? `Deleted ${rel(file, dir)}` : 'Deleted a file'
+  }
+  if (READ.has(key)) {
+    const file = pickPath(input)
+    return file ? `Read ${rel(file, dir)}` : 'Read a file'
+  }
+  if (SEARCH.has(key)) return 'Searched the code'
+  if (RUN.has(key)) {
+    const cmd = summarizeCommand(input.command ?? input.cmd ?? '')
+    return cmd ? `Ran ${cmd}` : 'Ran a command'
+  }
+  return `Used ${name || 'a tool'}`
+}
+
+function pickPath (input) {
+  for (const k of ['file_path', 'path', 'target_file', 'notebook_path', 'filePath', 'relative_workspace_path']) {
+    if (typeof input[k] === 'string' && input[k]) return input[k]
+  }
+  return null
+}
+
+function rel (file, dir) {
+  if (!dir || !path.isAbsolute(file)) return file.replace(/^\.\//, '')
+  const r = path.relative(dir, file)
+  // Paths outside the project are reduced to their file name.
+  if (r.startsWith('..') || path.isAbsolute(r)) return path.basename(file)
+  return r.split(path.sep).join('/')
+}
+
+const SETUP = new Set(['cd', 'pushd', 'export', 'set', 'source', '.', 'true'])
+
+/** "FOO=1 npm test -- --watch" -> "npm test". Only the program and one plain word survive. */
+export function summarizeCommand (command) {
+  // "cd app && npm test" is really "npm test": skip setup steps.
+  const steps = String(command).split(/&&|;|\|\|/).map((s) => s.trim()).filter(Boolean)
+  const main = steps.find((s) => {
+    const w = s.split(/\s+/).filter((x) => !/^[A-Za-z_][A-Za-z0-9_]*=/.test(x))
+    return w.length && !SETUP.has(w[0])
+  })
+  // Only setup steps (e.g. just "cd somewhere"): show the program, not where it went.
+  return main ? summarizeStep(main) : summarizeStep(steps[0] || '').split(' ')[0]
+}
+
+function summarizeStep (step) {
+  const words = String(step).trim().split(/\s+/).filter(Boolean)
+  while (words.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(words[0])) words.shift()
+  if (!words.length) return ''
+  let program = words[0]
+  // Show a program's name, never where it lives (paths can contain user names).
+  if (program.includes('/')) program = program.split('/').filter(Boolean).pop() || ''
+  if (!/^[A-Za-z0-9][\w.+-]*$/.test(program)) return ''
+  const next = words[1]
+  return next && /^[a-z][\w:-]*$/.test(next) ? `${program} ${next}` : program
+}