heyquilt 0.3.121 → 0.3.122

package/src/quilts/cli.js

@@ -6,16 +6,43 @@ import path from 'node:path'
 import fs from 'node:fs'
 import os from 'node:os'
 import { quiltClient } from './client.js'
+import { runChecks } from './runner.js'
 import { findBlock, checkout, status as blockStatus, commitFolder, amendFolder, syncTo, localDiff, saveBlock, restore, reset, clean, localChanges } from './block.js'
-import { describeLog, describeShow, describeDiff, describeBlame, describeStatus, describeMerge, describeWrite, describeSquare, describeSquareStatus, describeEvents, describeTag, describeRelease, describeImport, describeRestore, describeReset, describeClean, describeLive, describeClaims, describeResolutions, describeLiveSet, describeMergeBase, describeGrep, describeBisect, describeCheck, describeReviews, describeReviewed, describeSquareCheck, describePolicy, describeKeys, describeTokens, describeNewToken } from './describe.js'
+import { describeLog, describeShow, describeDiff, describeBlame, describeStatus, describeMerge, describeWrite, describeSquare, describeSquareStatus, describeEvents, describeTag, describeRelease, describeImport, describeImportRecord, describeRestore, describeReset, describeClean, describeLive, describeClaims, describeResolutions, describeLiveSet, describeMergeBase, describeGrep, describeBisect, describeCheck, describeReviews, describeReviewed, describeSquareCheck, describePolicy, describeKeys, describeTokens, describeNewToken, describeCheckRuns, describeRerun } from './describe.js'
 import { signWithLocalKey, localKey, makeLocalKey, signingKeyFile } from './signing.js'
 
-export const API_URL = 'https://api.heyquilt.com'
+export const API_URL = 'https://api.seam.heyquilt.com'
 
 /** The verbs `seam` answers. */
-export const SEAM_VERBS = new Set(['quilts', 'square', 'checkout', 'status', 'commit', 'log', 'show', 'diff', 'merge', 'rebase', 'revert', 'cherry-pick', 'blame', 'resolve', 'cat', 'ls', 'import', 'export', 'events', 'tag', 'release', 'line', 'restore', 'reset', 'clean', 'live', 'bisect', 'grep', 'describe', 'merge-base', 'claim', 'unclaim', 'check', 'resolutions', 'review', 'sign', 'key', 'token'])
+export const SEAM_VERBS = new Set(['quilts', 'square', 'checkout', 'status', 'commit', 'log', 'show', 'diff', 'merge', 'rebase', 'revert', 'cherry-pick', 'blame', 'resolve', 'cat', 'ls', 'import', 'export', 'events', 'tag', 'release', 'line', 'restore', 'reset', 'clean', 'live', 'bisect', 'grep', 'describe', 'merge-base', 'claim', 'unclaim', 'check', 'checks', 'resolutions', 'review', 'sign', 'key', 'token', 'runner'])
 
-const VALUE_FLAGS = new Set(['-m', '--quilts', '--message', '-n', '--max-count', '--into', '--onto', '--on-conflict', '--quilt', '--square', '--dir', '--line', '--task', '--level', '--title', '--slug', '--format', '--expect-tip', '--side', '--file', '--batch', '--to', '--note', '--after', '--kinds', '--webhook', '--secret', '--branch', '--from', '-S', '--run', '--marks', '--patch', '--on', '--path', '--checks', '--name', '--public-key'])
+/** `ci=agent:ci,lint=agent:a+agent:b` → { ci: ['agent:ci'], lint: ['agent:a', 'agent:b'] }; `none` clears them. */
+export function parseRunners (text) {
+  if (text === 'none') return null
+  const out = {}
+  for (const part of text.split(',').map((x) => x.trim()).filter(Boolean)) {
+    const i = part.indexOf('=')
+    if (i < 1) throw new Error(`--runners: <check>=<member>[+<member>], e.g. ci=agent:ci (got ${part})`)
+    out[part.slice(0, i)] = part.slice(i + 1).split('+').map((m) => m.trim()).filter(Boolean)
+  }
+  return out
+}
+
+/** `e2e=post_merge,ci=pre_merge+post_merge` → { e2e: ['post_merge'], ci: ['pre_merge', 'post_merge'] }; `none` clears them. */
+export function parseTiers (text) {
+  if (text === 'none') return null
+  const out = {}
+  for (const part of text.split(',').map((x) => x.trim()).filter(Boolean)) {
+    const i = part.indexOf('=')
+    if (i < 1) throw new Error(`--tiers: <check>=<tier>[+<tier>], e.g. e2e=post_merge (got ${part})`)
+    out[part.slice(0, i)] = part.slice(i + 1).split('+').map((m) => m.trim()).filter(Boolean)
+  }
+  return out
+}
+
+/** `test/**,**\/*.test.js` → a list; `none` clears it. */
+export const parseGlobs = (text) => text === 'none' ? null : text.split(',').map((x) => x.trim()).filter(Boolean)
+const VALUE_FLAGS = new Set(['-m', '--quilts', '--message', '-n', '--max-count', '--into', '--onto', '--on-conflict', '--quilt', '--square', '--dir', '--line', '--task', '--level', '--title', '--slug', '--format', '--expect-tip', '--side', '--file', '--batch', '--to', '--note', '--after', '--kinds', '--webhook', '--secret', '--branch', '--from', '-S', '--run', '--marks', '--patch', '--on', '--path', '--checks', '--name', '--public-key', '--interval', '--credential', '--as', '--runners', '--run-key', '--state', '--tier', '--tiers', '--tests', '--ci-config', '--commit', '--check', '--log-url'])
 
 export function parse (argv) {
   const pos = []; const flags = {}; const paths = []
@@ -81,11 +108,18 @@ export async function runSeamCommand (cmd, argv, { cwd = process.cwd(), token, o
       if (sub === 'require') {
         if (!pos[1]) throw new Error('Which line? seam line require <line> [<approvals>] [--checks ci,lint]')
         const checks = flags['--checks'] === undefined ? undefined : String(flags['--checks']).split(',').map((c) => c.trim()).filter(Boolean)
-        if (pos[2] === undefined && checks === undefined) { const p = await client.linePolicy(needQuilt(), pos[1]); return print(p, describePolicy(p)) }
-        const p = await client.setLinePolicy(needQuilt(), pos[1], { ...(pos[2] !== undefined ? { approvals: Number(pos[2]) } : {}), ...(checks ? { checks } : {}) })
+        // --runners ci=agent:ci,lint=agent:ci+agent:lint: who runs each check (their verdicts count; anyone else's is advisory)
+        const runners = flags['--runners'] === undefined ? undefined : parseRunners(String(flags['--runners']))
+        // --tiers e2e=post_merge: where each check runs; --tests / --ci-config: globs for the affected set
+        const tiers = flags['--tiers'] === undefined ? undefined : parseTiers(String(flags['--tiers']))
+        const tests = flags['--tests'] === undefined ? undefined : parseGlobs(String(flags['--tests']))
+        const ciConfig = flags['--ci-config'] === undefined ? undefined : parseGlobs(String(flags['--ci-config']))
+        const extra = { ...(tiers !== undefined ? { tiers } : {}), ...(tests !== undefined ? { tests } : {}), ...(ciConfig !== undefined ? { ci_config: ciConfig } : {}) }
+        if (pos[2] === undefined && checks === undefined && runners === undefined && !Object.keys(extra).length) { const p = await client.linePolicy(needQuilt(), pos[1]); return print(p, describePolicy(p)) }
+        const p = await client.setLinePolicy(needQuilt(), pos[1], { ...(pos[2] !== undefined ? { approvals: Number(pos[2]) } : {}), ...(checks ? { checks } : {}), ...(runners !== undefined ? { runners } : {}), ...extra })
         return print(p, describePolicy(p))
       }
-      throw new Error('seam line [list] | new release/<name> [--from <rev>] | freeze <line> | unfreeze <line> | require <line> [<approvals>] [--checks ci,lint]')
+      throw new Error('seam line [list] | new release/<name> [--from <rev>] | freeze <line> | unfreeze <line> | require <line> [<approvals>] [--checks ci,lint] [--runners ci=<member>] [--tiers e2e=post_merge] [--tests test/**] [--ci-config ops/**]')
     }
     case 'tag':
     case 'release': {
@@ -126,6 +160,12 @@ export async function runSeamCommand (cmd, argv, { cwd = process.cwd(), token, o
       // seam square handoff [sq] --to <member> [--note text] | abandon [sq] | reopen [sq]
       if (sub === 'handoff') { const sq = await client.handoff(needQuilt(), pos[1] || needSquare(), { to: flags['--to'], note: flags['--note'] }); return print(sq, `Handed ${sq.short || sq.id} to ${sq.holder}.`) }
       if (sub === 'abandon') { const sq = await client.abandon(needQuilt(), pos[1] || needSquare()); return print(sq, `Abandoned ${sq.short || sq.id}; seam square reopen brings it back.`) }
+      // seam square merged [sq] --as <git sha>: closes a square whose work went into git by hand (admins, during a follow)
+      if (sub === 'merged') {
+        if (!flags['--as']) throw new Error('Which git commit holds the work? seam square merged [sq:id] --as <sha>')
+        const sq = await client.squareMerged(needQuilt(), pos[1] || needSquare(), { git_sha: flags['--as'] })
+        return print(sq, `${sq.short || sq.id} is merged by hand: patch ${sq.merged.patch_no} on ${sq.merged.line} (git ${sq.merged.git_sha.slice(0, 12)}).`)
+      }
       if (sub === 'reopen') { const sq = await client.reopen(needQuilt(), pos[1] || needSquare()); return print(sq, `Reopened ${sq.short || sq.id}; you hold it.`) }
       // seam square fold [sq] --into sq:<id> | split [sq] <paths,...> <paths,...> [--title t]
       if (sub === 'fold') {
@@ -164,6 +204,16 @@ export async function runSeamCommand (cmd, argv, { cwd = process.cwd(), token, o
       const r = await checkout(client, { quilt: needQuilt(), ...(isSquare ? { square: target } : { rev: target }), paths, dir, api })
       return print({ dir, files: r.files, block: { ...r.block, files: undefined } }, `Checked out ${r.files} file(s) of ${isSquare ? target : target} under ${r.block.paths.map((p) => p || '/').join(', ')} into ${dir}.`)
     }
+    case 'runner': {
+      // seam runner --check ci[,lint] --run "npm test" [--dir <folder>] [--interval <s>] [--log-url <template>] [--once] [--keep]
+      const checks = String(flags['--check'] || '').split(',').map((c) => c.trim()).filter(Boolean)
+      if (!checks.length || !flags['--run'] || flags['--run'] === true) throw new Error('seam runner --check <name>[,<name>] --run "<command>" [--dir <folder>] [--interval <seconds>] [--log-url <template>] [--once]')
+      const q = needQuilt()
+      const say = (l) => { if (!flags['--json']) console.log(l) }
+      if (!flags['--once']) say(`seam runner: running ${checks.join(', ')} for ${q} with: ${flags['--run']} (Ctrl-C to stop)`)
+      const done = await runChecks({ client, quilt: q, checks, run: String(flags['--run']), api, once: !!flags['--once'], keep: !!flags['--keep'], ...(flags['--dir'] ? { dir: path.resolve(cwd, flags['--dir']) } : {}), ...(flags['--interval'] ? { intervalMs: Math.max(1, Number(flags['--interval'])) * 1000 } : {}), ...(flags['--log-url'] ? { logUrl: String(flags['--log-url']) } : {}), say })
+      return print({ runs: done }, done.length ? `Ran ${done.length} check run(s).` : 'Nothing queued.')
+    }
     case 'status': {
       if (!found) throw new Error('Not in a block folder (no .seam/block.json here or above).')
       const st = await blockStatus(client, found.dir, block)
@@ -190,15 +240,26 @@ export async function runSeamCommand (cmd, argv, { cwd = process.cwd(), token, o
     case 'check': {
       // seam check <name> red|green|flaky [--line main] [--patch n] | seam check <name> green|red --square <sq>
       const [name, status] = pos
+      if (name === 'rerun') {
+        // seam check rerun <check> --square <sq> | --line <line> [--commit <id>]: ask its runners again
+        if (!status) throw new Error('seam check rerun <check> --square <square> | --line <line> [--commit <id>]')
+        const r = await client.rerunCheck(needQuilt(), { check: status, ...(flags['--square'] ? { square: flags['--square'] } : { line: flags['--line'] || 'main' }), ...(flags['--commit'] ? { commit: flags['--commit'] } : {}) })
+        return print(r, describeRerun(r))
+      }
       if (!name || !['red', 'green', 'flaky'].includes(status)) throw new Error('seam check <name> red|green|flaky [--line <line>] [--patch <n>]')
       if (flags['--square']) {
         // seam check <name> green|red --square <sq>: a result for a square's latest commit (a line may require it before a merge)
-        const r = await client.reportSquareCheck(needQuilt(), flags['--square'], { check: name, status })
+        const r = await client.reportSquareCheck(needQuilt(), flags['--square'], { check: name, status, ...(flags['--run-key'] ? { run_key: flags['--run-key'] } : {}) })
         return print(r, describeSquareCheck(r))
       }
-      const r = await client.reportCheck(needQuilt(), flags['--line'] || 'main', { check: name, status, ...(flags['--patch'] != null ? { patch: Number(flags['--patch']) } : {}) })
+      const r = await client.reportCheck(needQuilt(), flags['--line'] || 'main', { check: name, status, ...(flags['--patch'] != null ? { patch: Number(flags['--patch']) } : {}), ...(flags['--run-key'] ? { run_key: flags['--run-key'] } : {}) })
       return print(r, describeCheck(r))
     }
+    case 'checks': {
+      // seam checks [--state queued] [--name ci] [--tier pre_merge|post_merge] [--line main] [--square sq]: the quilt's check runs
+      const r = await client.checkRuns(needQuilt(), { state: flags['--state'], name: flags['--name'], tier: flags['--tier'], line: flags['--line'], square: flags['--square'] })
+      return print(r, describeCheckRuns(r))
+    }
     case 'unclaim': {
       // seam unclaim <pattern|claim id>...
       if (!pos.length) throw new Error('Which claim? seam unclaim <pattern>')
@@ -431,7 +492,23 @@ export async function runSeamCommand (cmd, argv, { cwd = process.cwd(), token, o
       return print(r, r.entries.map((e) => `${e.mode}\t${e.blob ? e.blob.slice(0, 12) : e.term.slice(0, 12)}\t${e.path}`).join('\n'))
     }
     case 'import': {
-      if (pos[0] !== 'git' || !pos[1]) throw new Error('seam import git <path> [--into <quilt-slug>] [--validate]')
+      // From a git remote, on the server, and following it (14): status and poke name the import.
+      if (pos[0] === 'cutover') {
+        if (!pos[1]) throw new Error('seam import cutover <import-id> [--credential <name>]')
+        const r = await client.cutover(pos[1], { credential: flags['--credential'] || undefined })
+        return print(r, `Cut over: import ${r.import.id} is done for good, its lines take merges in Seam, and main exports to ${r.export.target} after each merge.\nseam export status --quilt ${r.import.id}`)
+      }
+      if (pos[0] === 'status' || pos[0] === 'poke') {
+        if (!pos[1]) throw new Error(`seam import ${pos[0]} <import-id>`)
+        const r = pos[0] === 'status' ? await client.importStatus(pos[1]) : await client.pokeImport(pos[1])
+        return print(r, pos[0] === 'poke' ? `Poked: import ${r.id} fetches the remote now.` : describeImportRecord(r))
+      }
+      if (pos[0] === 'git' && pos[1] && (flags['--follow'] || flags['--remote'] || /^(https?|ssh|git):\/\/|^[\w.-]+@[\w.-]+:/.test(pos[1]))) {
+        const slug = flags['--into'] || path.basename(String(pos[1]).replace(/\.git$/, '').replace(/\/+$/, '')).toLowerCase().replace(/[^a-z0-9-]/g, '-')
+        const r = await client.startImport({ url: pos[1], slug, follow: !!flags['--follow'], interval: flags['--interval'] ? Number(flags['--interval']) : undefined, credential: flags['--credential'] || undefined })
+        return print(r, `Importing ${pos[1]} into ${slug} on the server (import ${r.id}).${r.follow ? ` It follows main and release/* every ${r.interval_s} s; they are frozen until cut-over.\nPoke it from a git hook or cron job with: curl -X POST -H 'Authorization: Bearer ${r.poke_secret}' <server>/v1/imports/${r.id}/poke  (the secret is shown once)` : ''}\nseam import status ${r.id}`)
+      }
+      if (pos[0] !== 'git' || !pos[1]) throw new Error('seam import git <path> [--into <quilt-slug>] [--validate] | seam import git <remote-url> [--into <slug>] [--follow] [--interval <s>] [--credential <name>] | seam import status|poke <import-id>')
       const { importGit } = await import('./import-git.js')
       const repo = path.resolve(cwd, pos[1])
       if (!fs.existsSync(path.join(repo, '.git')) && !fs.existsSync(path.join(repo, 'HEAD'))) throw new Error(`${repo} is not a git repository`)
@@ -439,6 +516,16 @@ export async function runSeamCommand (cmd, argv, { cwd = process.cwd(), token, o
       return print(r, describeImport(r))
     }
     case 'export': {
+      // To a git remote, on the server, after each merge (14): seam export remote <url> | status.
+      if (pos[0] === 'remote' && pos[1]) {
+        const r = await client.setExport(needQuilt(), { target: pos[1], lines: flags['--line'] ? String(flags['--line']).split(',') : undefined, releases: !!flags['--releases'], credential: flags['--credential'] || undefined, scratch: !!flags['--scratch'], enabled: !flags['--off'] })
+        return print(r, r.enabled ? `Exporting ${r.lines.join(', ')} to ${r.target} after each merge${r.releases ? ', with release tags' : ''}. seam export status` : `The export to ${r.target} is off.`)
+      }
+      if (pos[0] === 'status') {
+        const r = await client.exportStatus(needQuilt())
+        const st = r.status || {}
+        return print(r, [`Export to ${r.target} (${r.lines.join(', ')}${r.releases ? ', releases' : ''}${r.enabled ? '' : ', off'}): ${st.state || 'idle'}${st.error ? ` - ${st.error}` : ''}`, ...Object.entries(st.lines || {}).map(([l, x]) => `  ${l}: patch ${x.patch_no} -> ${String(x.sha || '').slice(0, 12)}`)].join('\n'))
+      }
       if (pos[0] !== 'git' || !pos[1]) throw new Error('seam export git <dir> [--line main] [--branch <name>]')
       const { exportGit } = await import('./export-git.js')
       const r = await exportGit(client, { q: needQuilt(), dir: path.resolve(cwd, pos[1]), line: flags['--line'] || 'main', branch: flags['--branch'] || undefined, log: (s) => { if (!json) out(s) } })

package/src/quilts/client.js

@@ -48,6 +48,7 @@ export function quiltClient ({ api, token, fetch: fetchImpl = globalThis.fetch,
     amend: (q, s, b) => call('POST', `${Q(q)}/squares/${enc(s)}/amend`, b),
     handoff: (q, s, b) => call('POST', `${Q(q)}/squares/${enc(s)}/handoff`, b),
     abandon: (q, s, b = {}) => call('POST', `${Q(q)}/squares/${enc(s)}/abandon`, b),
+    squareMerged: (q, s, b) => call('POST', `${Q(q)}/squares/${enc(s)}/merged`, b),
     reopen: (q, s) => call('POST', `${Q(q)}/squares/${enc(s)}/reopen`, {}),
     mergeSquare: (q, s, b) => call('POST', `${Q(q)}/squares/${enc(s)}/merge`, b),
     fold: (q, s, b) => call('POST', `${Q(q)}/squares/${enc(s)}/fold`, b),
@@ -91,6 +92,8 @@ export function quiltClient ({ api, token, fetch: fetchImpl = globalThis.fetch,
     reviews: (q, sq) => call('GET', `${Q(q)}/squares/${enc(sq)}/reviews`),
     review: (q, sq, b) => call('POST', `${Q(q)}/squares/${enc(sq)}/reviews`, b),
     reportSquareCheck: (q, sq, b) => call('POST', `${Q(q)}/squares/${enc(sq)}/checks`, b),
+    rerunCheck: (q, { check, square, line, commit }) => call('POST', square ? `${Q(q)}/squares/${enc(square)}/checks/${enc(check)}/rerun` : `${Q(q)}/lines/${enc(line || 'main')}/checks/${enc(check)}/rerun`, commit ? { commit } : {}),
+    checkRuns: (q, o = {}) => call('GET', `${Q(q)}/checks${qs(o)}`),
     linePolicy: (q, line) => call('GET', `${Q(q)}/lines/${enc(line)}/policy`),
     setLinePolicy: (q, line, b) => call('PUT', `${Q(q)}/lines/${enc(line)}/policy`, b),
     claims: async (q, square) => (await call('GET', `${Q(q)}/claims${square ? `?square=${enc(square)}` : ''}`)).claims,
@@ -106,6 +109,12 @@ export function quiltClient ({ api, token, fetch: fetchImpl = globalThis.fetch,
     uploadPack: (q, bytes) => call('POST', `${Q(q)}/packs`, bytes, { raw: true }),
     importCommits: (q, items, lines = []) => call('POST', `${Q(q)}/import/commits`, { items, ...(lines.length ? { lines } : {}) }),
     importKnown: (q, shas) => call('POST', `${Q(q)}/import/known`, { shas }),
+    setExport: (q, b) => call('PUT', `${Q(q)}/export`, b),
+    exportStatus: (q) => call('GET', `${Q(q)}/export`),
+    startImport: (b) => call('POST', '/v1/imports', b),
+    importStatus: (id) => call('GET', `/v1/imports/${enc(id)}`),
+    cutover: (id, b = {}) => call('POST', `/v1/imports/${enc(id)}/cutover`, b),
+    pokeImport: (id) => call('POST', `/v1/imports/${enc(id)}/poke`),
 
     /**
      * Uploads objects the server does not have yet ([{ kind, id, bytes }]), in packs of at most

package/src/quilts/describe.js

@@ -117,6 +117,8 @@ export function describeEvents (r) {
     const p = e.payload || {}
     if (e.kind === 'patch.merged') return `#${e.event_seq} patch.merged: patch ${e.patch_no} by ${e.by.member_id} "${first(p.message || '')}" changed ${e.paths.join(', ')} in your square ${e.square_short}${p.would_conflict ? `; would conflict in ${p.would_conflict_paths.join(', ')}` : '; merges cleanly'}`
     if (e.kind === 'conflict.added') return `#${e.event_seq} conflict.added: ${p.path} (${p.kind}) in ${e.square_short}${p.caused_by && p.caused_by.patch_no ? `, against patch ${p.caused_by.patch_no}` : ''}; settle it and merge again`
+    if (e.kind === 'check.cancelled') return `#${e.event_seq} check.cancelled: stop ${p.check} (${p.tier}) on ${p.commit.slice(0, 12)}, run_key ${p.run_key}: ${p.superseded_by} replaces it`
+    if (e.kind === 'check.requested') return `#${e.event_seq} check.requested: run ${p.check} (${p.tier}) on ${p.commit.slice(0, 12)}${e.square_short ? ` in ${e.square_short}` : ` at ${e.line}:${p.patch_no}`}; report with run_key ${p.run_key}`
     if (e.kind === 'square.handoff') return `#${e.event_seq} square.handoff: ${e.square_short} from ${p.from} to ${p.to}${p.note ? `: ${p.note}` : ''}`
     return `#${e.event_seq} ${e.kind}`
   }
@@ -195,6 +197,7 @@ export function describeClaims (claims) {
 
 export function describeCheck (r) {
   const lines = [`${r.line}: merge window ${r.window} an hour${r.red.length ? ` (red: ${r.red.join(', ')})` : ''}.`]
+  if (r.advisory) lines.push('Your verdict is advisory: you are not one of the check\'s runners, so it changes nothing.')
   const v = r.revert
   if (v && v.reverted) lines.push(`Reverted patch ${r.line}:${v.patch_no} as patch ${r.line}:${v.revert_patch_no}.${v.fix_square ? ` The change is again in square ${v.fix_square.short}, held by ${v.fix_square.holder}: fix it there, commit, merge.` : ''}`)
   else if (v) lines.push(`Did not revert patch ${r.line}:${v.patch_no}: ${(v.refused && (v.refused.detail || v.refused.code)) || 'refused'}.${v.square ? ` The revert waits in square ${v.square.short}.` : ''}`)
@@ -238,11 +241,32 @@ export function describePolicy (p) {
   const parts = []
   if (p.approvals) parts.push(`${p.approvals} approval${p.approvals === 1 ? '' : 's'} of a square's latest commit from someone other than its holder`)
   if (p.checks?.length) parts.push(`check${p.checks.length === 1 ? '' : 's'} ${p.checks.join(', ')} green on it`)
-  return parts.length ? `${p.line} needs ${parts.join(' and ')} to take a merge.` : `${p.line} takes merges without approvals or checks.`
+  const run = Object.entries(p.runners || {}).map(([c, ms]) => `${c} by ${ms.join(', ')}`)
+  const runs = run.length ? ` Runners: ${run.join('; ')} (asked to run their checks; anyone else's verdict is advisory).` : ''
+  const tiers = Object.entries(p.tiers || {}).map(([c, ts]) => `${c} ${ts.length ? ts.join(' and ') : 'never'}`)
+  const tg = (tiers.length ? ` Tiers: ${tiers.join('; ')}.` : '') +
+    (p.tests?.length ? ` Tests: ${p.tests.join(', ')} (a pre-merge run names the ones a change reaches).` : '') +
+    (p.ci_config?.length ? ` CI config: ${p.ci_config.join(', ')} (a change there runs everything).` : '')
+  return (parts.length ? `${p.line} needs ${parts.join(' and ')} to take a merge.` : `${p.line} takes merges without approvals or checks.`) + runs + tg
+}
+
+/** A run's affected set in a few words. */
+const affectedWords = (a) => !a ? '' : a.confidence === 'all' ? '  runs all' : `  runs ${a.tests.length} test${a.tests.length === 1 ? '' : 's'}`
+
+/** Check runs, newest first: one per line. */
+export function describeCheckRuns (r) {
+  if (!r.runs.length) return 'No check runs.'
+  return r.runs.map((x) => `${x.name}  ${x.tier}  ${x.state}${x.verdict ? ` ${x.verdict}` : ''}${x.advisory ? ' (advisory)' : ''}${affectedWords(x.affected)}  ${x.commit.slice(0, 12)}${x.square ? ` ${x.square}` : ` ${x.line}${x.patch_no != null ? `:${x.patch_no}` : ''}`}  run_key ${x.run_key}${x.by ? `  by ${x.by}` : ''}`).join('\n')
+}
+
+/** A check asked to run again. */
+export function describeRerun (r) {
+  return `Asked ${r.check}'s runners to run it again (${r.tier}) on ${r.commit.slice(0, 12)}${r.square ? ` in ${r.square}` : ` at the tip of ${r.line}`}: run_key ${r.run_key}. An open run of it there is cancelled (check.cancelled).`
 }
 
 /** A check reported on a square. */
 export function describeSquareCheck (r) {
+  if (r.advisory) return `${r.check} is ${r.status} on ${r.square} (${r.head.slice(0, 12)}), advisory: you are not one of its runners (${(r.runners || []).join(', ')}), so it gates nothing.`
   const req = r.checks.filter((c) => c.required)
   const left = req.filter((c) => c.status !== 'green').map((c) => `${c.name} ${c.status}`)
   return `${r.check} is ${r.status} on ${r.square} (${r.head.slice(0, 12)}).${req.length ? (left.length ? ` Its line still needs: ${left.join(', ')}.` : ' Every check its line requires is green.') : ''}`
@@ -264,3 +288,9 @@ export function describeTokens (r) {
 }
 
 export const describeNewToken = (t) => `Made token ${t.name} (${t.level} on ${t.quilt}, id ${t.id}). Its secret, shown only this once:\n\n  ${t.token}\n\nSet it as SEAM_TOKEN (or send it as Authorization: Bearer <token>).`
+
+/** An import record (14) in a few lines. */
+export function describeImportRecord (r) {
+  const lines = (r.lines || []).map((l) => `  ${l.line}: ${l.patches} patches, git ${l.tip_sha ? l.tip_sha.slice(0, 12) : '(none)'}`)
+  return [`Import ${r.id} of ${r.source?.url}: ${r.state}${r.follow ? `, following every ${r.interval_s} s` : ''}${r.error ? ` (${r.error})` : ''}`, ...lines].join('\n')
+}

package/src/quilts/events.js

@@ -6,7 +6,7 @@
 import { QuiltError, squareShort } from './service.js'
 import { makeSubscription, deliverWebhook, RETRY_DELAYS_MS } from './webhook.js'
 
-export const QUILT_EVENT_KINDS = ['patch.merged', 'patch.reverted', 'conflict.added', 'square.handoff']
+export const QUILT_EVENT_KINDS = ['patch.merged', 'patch.reverted', 'conflict.added', 'square.handoff', 'check.requested', 'check.cancelled']
 const MAX_DIFF_PATHS = 200
 
 export function eventOps (svc, sq, { allowLocalWebhooks = false, fetch, delays = RETRY_DELAYS_MS, log = () => {} } = {}) {
@@ -24,6 +24,8 @@ export function eventOps (svc, sq, { allowLocalWebhooks = false, fetch, delays =
   /** The events one log row causes. */
   async function derive (qid, row) {
     const out = []
+    // check.requested (13, checks.js): to the runners a line's policy names.
+    if (svc.internals.checkRequests) out.push(...await svc.internals.checkRequests(qid, row))
     if (row.kind === 'merge' && row.payload?.reverts) {
       // patch.reverted: the reverted patch's holder (and whom they acted for) learns it is gone (07 step 4).
       const c = await getCommit(qid, row.commit)
@@ -93,10 +95,19 @@ export function eventOps (svc, sq, { allowLocalWebhooks = false, fetch, delays =
         const cursor = await store.eventCursor(qid)
         const rows = await store.logRows(qid, { after: cursor, limit: 200 })
         if (!rows.length) return made
-        const events = []
+        let events = []
         for (const r of rows) events.push(...await derive(qid, r))
+        // A new check request cancels what it supersedes (checks.js settleRuns).
+        let cancels = []
+        if (svc.internals.settleRuns) ({ events, cancels } = await svc.internals.settleRuns(qid, events))
+        // A check.requested event's run record is stored first (idempotent on run_key), so a
+        // runner polling GET /checks finds every run it is woken for.
+        const runs = events.filter((e) => e.run).map((e) => e.run)
+        if (runs.length) await store.addCheckRuns({ quilt_id: qid, runs })
+        for (const e of events) delete e.run
         try {
           made.push(...await store.addEvents({ quilt_id: qid, events, expect_cursor: cursor, cursor: rows.at(-1).seq }))
+          if (cancels.length) await svc.internals.applyCancels(qid, cancels)
         } catch (err) { if (err.code !== 'cursor_moved') throw err }
       }
     })

package/src/quilts/export-remote.js

@@ -0,0 +1,156 @@
+// Export to a git remote (plans/quilt-source-control/14, "Export"): `settings.export` names a
+// remote (any: GitHub, GitLab, a bare repository), a credential the owner gives by name, the
+// lines to export (names, or `release/*`) and whether releases go out as tags. After each merge
+// on those lines the server writes the new patches as 14's commits (export.js and export-git.js:
+// deterministic, so the same patch gives the same sha on any machine) in a bare repository in
+// scratch and pushes them, fast-forward only: a remote that moved is refused, never forced, and
+// the status says which line and sha. Failures to reach the remote retry with backoff. A
+// quilt that an import made continues git's own history when the target is the import's source:
+// the first exported patch's parent is the last imported sha (14, cut-over). While its import
+// follows git, the export may go only to a scratch remote that is not the source.
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import crypto from 'node:crypto'
+import { QuiltError } from './service.js'
+import { exportGit } from './export-git.js'
+import { remoteUrl, run, authArgs, localClient } from './import-follow.js'
+
+const LEASE = ' export'
+const matches = (patterns, line) => patterns.some((p) => p === line || (p.endsWith('/*') && line.startsWith(p.slice(0, -1))))
+const BACKOFF = [30_000, 60_000, 5 * 60_000, 15 * 60_000, 60 * 60_000]
+
+export function exportRemoteOps (svc, api, { scratch = path.join(os.tmpdir(), 'seam-imports'), allowLocal = false, secret = (name) => process.env[`SEAM_SECRET_${String(name).toUpperCase().replace(/[^A-Z0-9]/g, '_')}`] || null, holder = `exporter:${process.pid}:${crypto.randomBytes(4).toString('hex')}` } = {}) {
+  const { store, now, quiltFor, fromStore } = svc.internals
+  const running = new Map()
+  const again = new Set() // a write came in while a pass ran: run once more after it
+  const retryAt = new Map() // quilt id → when to try again (this server)
+
+  const save = async (qid, rec, actor, logged = false) => { try { return await store.setExport({ quilt_id: qid, export: rec, logged, actor, at: now() }) } catch (err) { throw fromStore(err) } }
+
+  /** PUT /v1/quilts/:q/export { target, credential?, lines?, releases?, scratch?, enabled? } (admin). */
+  async function setExport (me, ref, { target, credential = null, lines = ['main'], releases = false, scratch: isScratch = false, enabled = true } = {}) {
+    const q = await quiltFor(me, ref, 'admin')
+    const url = remoteUrl(target, { allowLocal })
+    const list = (Array.isArray(lines) ? lines : [lines]).map(String)
+    if (!list.length || list.some((l) => !/^[A-Za-z0-9._-][A-Za-z0-9._/-]{0,99}(\/\*)?$/.test(l))) throw new QuiltError(400, 'bad_request', 'lines: line names, or a prefix such as release/*')
+    if (credential != null && !/^[A-Za-z0-9_.-]{1,100}$/.test(String(credential))) throw new QuiltError(400, 'bad_request', 'credential: the name of a secret, not the secret')
+    const imp = q.settings?.import
+    if (imp && imp.follow && ['reading', 'following'].includes(imp.state)) {
+      // 14: never push to the source while git is the authority, and only to a remote nothing pins.
+      if (url === imp.source?.url) throw new QuiltError(409, 'export_is_source', `${url} is the source this quilt's import follows; export to a scratch remote until cut-over`)
+      if (!isScratch) throw new QuiltError(409, 'scratch_required', 'while the import follows git, the export goes only to a scratch remote: say scratch: true (--scratch) to state that nothing pins a sha from it')
+    }
+    const prev = q.settings?.export || null
+    const rec = { target: url, ...(credential ? { credential: String(credential) } : {}), lines: list, releases: !!releases, scratch: !!isScratch, enabled: !!enabled, by: { member_id: me.member_id, kind: me.kind || 'person', name: me.name || null }, status: prev && prev.target === url ? prev.status : { state: 'idle', lines: {} } }
+    await save(q.id, rec, me.member_id, true)
+    if (rec.enabled) kick(q.id)
+    return view(rec)
+  }
+
+  const view = (rec) => rec
+  async function exportStatus (me, ref) {
+    const q = await quiltFor(me, ref, 'read')
+    if (!q.settings?.export) throw new QuiltError(404, 'not_found', 'this quilt exports nowhere')
+    return view(q.settings.export)
+  }
+
+  /** One pass: every exported line's new patches, pushed; then the release tags. */
+  async function pass (qid) {
+    const q = await store.getQuilt(qid)
+    const rec = q?.settings?.export
+    if (!rec || !rec.enabled) return
+    const lease = await store.takeLease({ kind: 'line', quilt_id: qid, line: LEASE, holder, ttl_ms: 30 * 60_000, at: now() })
+    if (!lease.held) { retryAt.set(qid, now() + 30_000); return }
+    const status = { ...(rec.status || {}), lines: { ...(rec.status?.lines || {}) } }
+    try {
+      const dir = path.join(scratch, `export-${qid}.git`)
+      if (!fs.existsSync(path.join(dir, 'HEAD'))) { fs.mkdirSync(dir, { recursive: true }); await run(['init', '-q', '--bare', dir]) }
+      const auth = authArgs(rec.credential ? await secret(rec.credential, { quilt_id: qid }) : null)
+      const env = { GIT_ALLOW_PROTOCOL: allowLocal ? 'https:http:ssh:git:file' : 'https:http:ssh:git' }
+      const client = localClient(api, rec.by)
+      const imp = q.settings?.import
+      const stateFile = path.join(dir, 'quilt-export.json')
+      for (const ln of await store.lines(qid)) {
+        if (!matches(rec.lines, ln.name) || !ln.tip) continue
+        // What the remote has now; the export only ever adds to it.
+        const remoteRef = `refs/seam-remote/${ln.name}`
+        await run([...auth, '-C', dir, 'fetch', '--quiet', '--no-tags', rec.target, `+refs/heads/${ln.name}:${remoteRef}`], { env }).catch(() => run(['-C', dir, 'update-ref', '-d', remoteRef]).catch(() => {}))
+        const remoteSha = (await run(['-C', dir, 'rev-parse', '--verify', '-q', remoteRef]).catch(() => '')).trim() || null
+        const all = fs.existsSync(stateFile) ? JSON.parse(fs.readFileSync(stateFile, 'utf8')) : {}
+        const key = `${ln.name}→${ln.name}`
+        // An imported quilt exporting to its source continues git's history from the import's tip.
+        const base = imp && imp.source?.url === rec.target ? (imp.lines || []).find((l) => l.line === ln.name) : null
+        if (!all[key] && base?.tip_sha && remoteSha === base.tip_sha) {
+          await run(['-C', dir, 'update-ref', `refs/heads/${ln.name}`, base.tip_sha])
+          all[key] = { quilt: qid, line: ln.name, branch: ln.name, patch_no: base.patches, sha: base.tip_sha, version: null }
+          fs.writeFileSync(stateFile, JSON.stringify(all, null, 2) + '\n')
+        }
+        const r = await exportGit(client, { q: qid, dir, line: ln.name })
+        if (remoteSha && remoteSha !== r.sha) {
+          // Is the remote behind us (fine: fast-forward) or somewhere else (refused)?
+          const behind = await run(['-C', dir, 'merge-base', '--is-ancestor', remoteSha, `refs/heads/${ln.name}`]).then(() => true, () => false)
+          if (!behind) throw Object.assign(new Error(`the remote's ${ln.name} moved to ${remoteSha.slice(0, 12)}, which the export did not write: it never forces (bring the commit in with a square, or reset the remote's branch)`), { refused: true, line: ln.name, sha: remoteSha })
+        }
+        if (r.sha && r.sha !== remoteSha) await run([...auth, '-C', dir, 'push', '--quiet', rec.target, `refs/heads/${ln.name}:refs/heads/${ln.name}`], { env })
+        status.lines[ln.name] = { patch_no: r.patch_no, sha: r.sha }
+      }
+      if (rec.releases) await pushTags(qid, dir, rec, auth, env)
+      Object.assign(status, { state: 'ok', at: now(), attempts: 0 })
+      delete status.error; delete status.next_at
+      retryAt.delete(qid)
+    } catch (err) {
+      const attempts = (status.attempts || 0) + 1
+      if (err.refused) Object.assign(status, { state: 'refused', error: err.message, line: err.line, remote_sha: err.sha, at: now() })
+      else {
+        const wait = BACKOFF[Math.min(attempts - 1, BACKOFF.length - 1)]
+        Object.assign(status, { state: 'retrying', error: String(err.message || err), attempts, next_at: now() + wait, at: now() })
+        retryAt.set(qid, now() + wait)
+      }
+    } finally {
+      const cur = (await store.getQuilt(qid))?.settings?.export
+      if (cur && cur.target === rec.target) await save(qid, { ...cur, status }, rec.by.member_id, cur.status?.state !== status.state).catch(() => {})
+      await store.giveLease({ kind: 'line', quilt_id: qid, line: LEASE, holder }).catch(() => {})
+    }
+  }
+
+  /** Tags on exported commits: a release as an annotated tag with its notes, a tag as a plain one. Never moved. */
+  async function pushTags (qid, dir, rec, auth, env) {
+    const shaFile = path.join(dir, 'quilt-export-shas')
+    const shas = new Map()
+    if (fs.existsSync(shaFile)) for (const l of fs.readFileSync(shaFile, 'utf8').split('\n')) { const [line, n, sha] = l.split(' '); if (sha) shas.set(`${line}/${n}`, sha) }
+    const tags = await store.tags(qid)
+    for (const t of tags) {
+      const c = t.commit ? await store.getCommit(qid, t.commit) : null
+      const sha = c?.patch ? shas.get(`${c.patch.line}/${c.patch.patch_no}`) : null
+      if (!sha) continue
+      const have = (await run(['-C', dir, 'rev-parse', '--verify', '-q', `refs/tags/${t.name}`]).catch(() => '')).trim()
+      if (!have) {
+        if (t.release) {
+          // Deterministic: the tagger and date are the release's, not the clock's.
+          const at = Math.floor(Number(t.at || 0) / 1000)
+          await run(['-C', dir, '-c', 'user.name=Quilt', '-c', 'user.email=export@heyquilt.com', 'tag', '-a', t.name, sha, '-m', t.notes || t.name], { env: { GIT_COMMITTER_DATE: `${at} +0000` } })
+        } else await run(['-C', dir, 'tag', t.name, sha])
+      }
+    }
+    if (tags.length) await run([...auth, '-C', dir, 'push', '--quiet', rec.target, 'refs/tags/*:refs/tags/*'], { env })
+  }
+
+  function kick (qid) {
+    if (running.has(qid)) { again.add(qid); return running.get(qid) }
+    const p = pass(qid).catch(() => {}).finally(() => { running.delete(qid); if (again.delete(qid)) kick(qid) })
+    running.set(qid, p)
+    return p
+  }
+
+  /** After a write: export when the quilt exports. */
+  async function afterWrite (qid) {
+    const q = await store.getQuilt(qid)
+    if (q?.settings?.export?.enabled) kick(qid)
+  }
+
+  async function exportIdle (qid) { while (running.has(qid)) await running.get(qid) }
+  async function exportTick () { for (const [qid, at] of retryAt) if (now() >= at) kick(qid) }
+
+  return { setExport, exportStatus, exportIdle, exportTick, exportAfterWrite: afterWrite, exportPass: kick }
+}