@heyquilt/seam 0.27.0 → 0.131.0

package/lib/quilts/pack.js

@@ -6,48 +6,147 @@
 // trailer, so it names every entry's location and id.
 import zlib from 'node:zlib'
 import { idOf } from './hash.js'
+import { BUILTIN_DICT } from './dict.js'
 
 export const MAGIC = Buffer.from('QPK1')
 export const MAX_PACK = 64 * 1024 * 1024
 
 /** Entry kinds, and the id context each one's (decompressed) bytes hash under. */
-export const KIND = { blob: 1, delta: 2, chunked: 3, chunk: 4, manifest: 5, tree: 6, term: 7, commit: 8 }
+export const KIND = { blob: 1, delta: 2, chunked: 3, chunk: 4, manifest: 5, tree: 6, term: 7, commit: 8, dict: 9 }
 const NAME = Object.fromEntries(Object.entries(KIND).map(([k, v]) => [v, k]))
-const CONTEXT = { blob: 'blob', delta: 'blob', chunked: 'blob', chunk: 'chunk', manifest: 'manifest', tree: 'tree', term: 'term', commit: 'commit' }
+const CONTEXT = { blob: 'blob', delta: 'blob', chunked: 'blob', chunk: 'chunk', manifest: 'manifest', tree: 'tree', term: 'term', commit: 'commit', dict: 'dict' }
 
 // Compression, in the entry's flags. zstd when this Node has it (≥ 22.15), else deflate.
 export const RAW = 0
 export const DEFLATE = 1
 export const ZSTD = 2
-const HAS_ZSTD = typeof zlib.zstdCompressSync === 'function'
+// The same, with the built-in dictionary (dict.js): only a blob of at most 64 KiB, and only when
+// the seal asks for it (SEAM_DICTIONARY). Every reader reads both, whatever the setting.
+export const DEFLATE_DICT = 3
+export const ZSTD_DICT = 4
+// The same, with a dictionary trained for the quilt (03 Dictionaries; dict-train.js): the stored
+// bytes are the dictionary's id (32 bytes, as a delta names its base), then the compressed blob. The
+// reader resolves the dictionary by that id, never by the quilt's current one. Only the server's seal
+// writes them (SEAM_TRAINED_DICTIONARY); every reader reads them.
+export const DEFLATE_TRAINED = 5
+export const ZSTD_TRAINED = 6
+const DICT_MAX = 64 * 1024
+/** In a blob row's flags (not a pack's): the row names a chunked file's root manifest (10). */
+export const CHUNKED = 8
+/** In a tree row's flags (not a pack's): a node a lazy derivation wrote, so a GC candidate (03 Bounded marking). */
+export const UNPINNED = 16
+/** In a blob row's flags (not a pack's): the row names a delta entry; the row's base_id is its base (03 The background squeeze). */
+export const DELTA = 32
+export const HAS_ZSTD = typeof zlib.zstdCompressSync === 'function'
 
-function squeeze (bytes) {
+/** `bytes` compressed with `dict` as zstd's dictionary or deflate's preset window. */
+const withDictionary = (bytes, dict, zstd = HAS_ZSTD) => zstd ? zlib.zstdCompressSync(bytes, { dictionary: dict }) : zlib.deflateRawSync(bytes, { level: 6, dictionary: dict })
+
+/** Whether entry flags name a trained dictionary (the stored bytes then start with its id). */
+export const usesTrained = (flags) => flags === DEFLATE_TRAINED || flags === ZSTD_TRAINED
+
+/** The id of the trained dictionary an entry's stored bytes name (flags 5 and 6). */
+export function trainedDictOf (stored) {
+  if (!stored || stored.length < 32) throw Object.assign(new Error('a dictionary entry is shorter than its dictionary id'), { code: 'pack_corrupt' })
+  return Buffer.from(stored.subarray(0, 32)).toString('hex')
+}
+
+/** { flags, data }: `bytes` with a trained dictionary ({ id, bytes }), its id first. `zstd` forces the path. */
+export function encodeTrained (bytes, dict, { zstd = HAS_ZSTD } = {}) {
+  if (zstd && !HAS_ZSTD) throw new Error('this Node cannot write zstd (needs Node 22.15 or later)')
+  return { flags: zstd ? ZSTD_TRAINED : DEFLATE_TRAINED, data: Buffer.concat([Buffer.from(dict.id, 'hex'), withDictionary(bytes, dict.bytes, zstd)]) }
+}
+
+function squeeze (bytes, dict = false, trained = null) {
   if (bytes.length < 64) return { flags: RAW, data: bytes }
-  const data = HAS_ZSTD ? zlib.zstdCompressSync(bytes) : zlib.deflateRawSync(bytes, { level: 6 })
+  let flags = HAS_ZSTD ? ZSTD : DEFLATE
+  let data = HAS_ZSTD ? zlib.zstdCompressSync(bytes) : zlib.deflateRawSync(bytes, { level: 6 })
+  if (dict && bytes.length <= DICT_MAX) {
+    const withDict = withDictionary(bytes, BUILTIN_DICT)
+    if (withDict.length < data.length) { data = withDict; flags = HAS_ZSTD ? ZSTD_DICT : DEFLATE_DICT }
+    // The quilt's own dictionary, where smaller still, its 32-byte id counted (03 Dictionaries).
+    if (trained?.bytes?.length) {
+      const t = encodeTrained(bytes, trained)
+      if (t.data.length < data.length) ({ data, flags } = t)
+    }
+  }
   // Stored raw unless compression saves at least 5% (03's rule for chunks, used for everything).
   if (data.length > bytes.length * 0.95) return { flags: RAW, data: bytes }
-  return { flags: HAS_ZSTD ? ZSTD : DEFLATE, data }
+  return { flags, data }
 }
 
-/** The bytes of a stored entry, decompressed by its flags. */
-export function unsqueeze (flags, data) {
+// The allocation bound (15 "Fuzzers"): an entry does not declare its decompressed size, so every
+// decompression stops at MAX_PACK, which no entry of a sealed pack can exceed (a pack is at most
+// MAX_PACK of entries, each its own plaintext or smaller). Past it, zlib throws ERR_BUFFER_TOO_LARGE
+// before allocating more, and readEntry reports the entry as damage.
+const BOUND = { maxOutputLength: MAX_PACK }
+
+/**
+ * The bytes of a stored entry, decompressed by its flags. `dict`: the bytes of the trained
+ * dictionary the entry names (flags 5 and 6; trainedDictOf), which the caller resolves by id.
+ */
+export function unsqueeze (flags, data, dict = null) {
   if (flags === RAW) return Buffer.from(data)
-  if (flags === DEFLATE) return zlib.inflateRawSync(data)
-  if (flags === ZSTD) {
+  if (usesTrained(flags)) {
+    if (!dict) throw new Error(`this entry needs dictionary ${trainedDictOf(data).slice(0, 12)}, which was not given`)
+    const body = data.subarray(32)
+    if (flags === DEFLATE_TRAINED) return zlib.inflateRawSync(body, { ...BOUND, dictionary: dict })
     if (!HAS_ZSTD) throw new Error('this pack entry is zstd and this Node cannot read zstd (needs Node 22.15 or later)')
-    return zlib.zstdDecompressSync(data)
+    return zlib.zstdDecompressSync(body, { ...BOUND, dictionary: dict })
+  }
+  if (flags === DEFLATE) return zlib.inflateRawSync(data, BOUND)
+  if (flags === DEFLATE_DICT) return zlib.inflateRawSync(data, { ...BOUND, dictionary: BUILTIN_DICT })
+  if (flags === ZSTD || flags === ZSTD_DICT) {
+    if (!HAS_ZSTD) throw new Error('this pack entry is zstd and this Node cannot read zstd (needs Node 22.15 or later)')
+    return flags === ZSTD ? zlib.zstdDecompressSync(data, BOUND) : zlib.zstdDecompressSync(data, { ...BOUND, dictionary: BUILTIN_DICT })
   }
   throw new Error(`unknown pack entry flags ${flags}`)
 }
 
+// Deltas (03 Blob encodings, written only by the squeeze): an entry of kind `delta` holds the
+// base blob's id (32 bytes), then the target compressed with the base's plaintext as the
+// dictionary. Its flags say how: ZSTD (zstd with { dictionary: base }) or DEFLATE (deflate-raw with
+// the base as its preset dictionary, of which deflate uses the last 32 KiB). The id an entry is
+// stored under is the target's blob id, checked after it is rebuilt.
+
+/** The base blob id a delta entry's stored bytes name. */
+export function deltaBase (stored) {
+  if (!stored || stored.length < 32) throw Object.assign(new Error('a delta entry is shorter than its base id'), { code: 'pack_corrupt' })
+  return Buffer.from(stored.subarray(0, 32)).toString('hex')
+}
+
+/** { flags, data }: `target` as a delta against `base` (plaintext), whose blob id is `baseId`. `zstd` forces the path (default: zstd where this Node has it). */
+export function encodeDelta (baseId, base, target, { zstd = HAS_ZSTD } = {}) {
+  if (zstd && !HAS_ZSTD) throw new Error('this Node cannot write zstd (needs Node 22.15 or later)')
+  const body = zstd
+    ? zlib.zstdCompressSync(target, { dictionary: base, params: { [zlib.constants.ZSTD_c_compressionLevel]: 19 } })
+    : zlib.deflateRawSync(target, { level: 9, dictionary: base.length ? base : undefined })
+  return { flags: zstd ? ZSTD : DEFLATE, data: Buffer.concat([Buffer.from(baseId, 'hex'), body]) }
+}
+
+/** The target bytes of a delta entry (`stored`, base id included), rebuilt against the base's plaintext. */
+export function decodeDelta (flags, stored, base) {
+  const body = stored.subarray(32)
+  if (flags === DEFLATE) return zlib.inflateRawSync(body, base.length ? { ...BOUND, dictionary: base } : BOUND)
+  if (flags === ZSTD) {
+    if (!HAS_ZSTD) throw new Error('this delta entry is zstd and this Node cannot read zstd (needs Node 22.15 or later)')
+    return zlib.zstdDecompressSync(body, { ...BOUND, dictionary: base })
+  }
+  throw new Error(`unknown delta entry flags ${flags}`)
+}
+
 const ENTRY_HEAD = 1 + 32 + 4
 const INDEX_ENTRY = 1 + 32 + 4 + 4 + 1
 
 /**
  * Builds a pack from [{ kind: 'blob' | 'tree' | 'term' | 'commit' | ..., id, bytes }]
  * (duplicate ids are written once). Returns { id, bytes, index: [{ kind, id, offset, len, flags }] }.
+ * `dict`: compress small blobs with the built-in dictionary where that is smaller (SEAM_DICTIONARY);
+ * `trained` ({ id, bytes }, with `dict`): also with the quilt's trained dictionary where smaller still.
+ * An entry given as { kind, id, stored, flags } is written as those stored bytes, unchanged (a
+ * delta, or an entry carried over from another pack).
  */
-export function buildPack (objects) {
+export function buildPack (objects, { dict = false, trained = null } = {}) {
   const parts = [MAGIC]
   let at = MAGIC.length
   const index = []
@@ -57,7 +156,10 @@ export function buildPack (objects) {
     seen.add(o.id)
     const kind = KIND[o.kind]
     if (!kind) throw new Error(`unknown pack entry kind ${o.kind}`)
-    const { flags, data } = squeeze(Buffer.from(o.bytes))
+    // The write side of the allocation bound (unsqueeze): no entry is over MAX_PACK as plaintext,
+    // so every reader can stop there. A larger file is stored in chunks (10, SEAM_CHUNKING=1).
+    if (!o.stored && o.bytes.length > MAX_PACK) throw Object.assign(new Error(`${o.kind} ${String(o.id).slice(0, 12)} is ${o.bytes.length} bytes whole, over 64 MiB: store it in chunks (SEAM_CHUNKING=1)`), { code: 'pack_too_large' })
+    const { flags, data } = o.stored ? { flags: o.flags, data: Buffer.from(o.stored) } : squeeze(Buffer.from(o.bytes), dict && o.kind === 'blob', o.kind === 'blob' ? trained : null)
     const h = Buffer.alloc(ENTRY_HEAD)
     h[0] = kind; Buffer.from(o.id, 'hex').copy(h, 1); h.writeUInt32BE(data.length, 33)
     parts.push(h, data)
@@ -88,7 +190,10 @@ function trailerBytes (index) {
 export function readIndex (bytes) {
   const b = Buffer.from(bytes)
   if (!b.subarray(0, 4).equals(MAGIC)) throw new Error('not a Quilt pack')
+  // A pack cut short or with a trailer length past its own bytes is damaged, not a crash (15).
+  if (b.length < MAGIC.length + 8) throw new Error('pack trailer is damaged')
   const tlen = b.readUInt32BE(b.length - 4)
+  if (tlen < 8 || tlen > b.length - MAGIC.length) throw new Error('pack trailer is damaged')
   const t = b.subarray(b.length - tlen)
   const n = t.readUInt32BE(0)
   if (tlen !== 4 + n * INDEX_ENTRY + 4) throw new Error('pack trailer is damaged')
@@ -99,9 +204,27 @@ export function readIndex (bytes) {
   return { id: idOf('pack', t), index }
 }
 
-/** The object `e` (an index entry) of a pack, from its stored bytes, checked against its id. */
-export function readEntry (e, stored) {
-  const bytes = unsqueeze(e.flags, stored)
+/**
+ * The object `e` (an index entry) of a pack, from its stored bytes, checked against its id.
+ * `sealed`: a sealed quilt's blob (11.11), whose keyed id only a key holder can check.
+ * `base`: a delta entry's base plaintext (a delta cannot be read without it). `dict`: the trained
+ * dictionary's bytes for an entry of flags 5 or 6 (resolved by the id its stored bytes start with).
+ */
+export function readEntry (e, stored, { sealed = false, base = null, dict = null } = {}) {
+  let bytes
+  if (e.kind === 'delta') {
+    if (!base) throw Object.assign(new Error(`pack entry ${e.id} is a delta and its base was not given`), { code: 'pack_corrupt', id: e.id })
+    try { bytes = decodeDelta(e.flags, stored, base) } catch (err) { throw Object.assign(new Error(`pack entry ${e.id} does not decompress: ${err.message}`), { code: 'pack_corrupt', id: e.id }) }
+    if (idOf('blob', bytes) !== e.id) throw Object.assign(new Error(`pack entry ${e.id} does not match its id`), { code: 'pack_corrupt', id: e.id })
+    return bytes
+  }
+  // Bytes damaged on the way back can fail to decompress before any id check: that is the same
+  // corruption (15's checksum path), so it carries the same code and the reader reads once more.
+  try { bytes = unsqueeze(e.flags, stored, dict) } catch (err) { throw Object.assign(new Error(`pack entry ${e.id} does not decompress: ${err.message}`), { code: 'pack_corrupt', id: e.id }) }
+  if (sealed && e.kind === 'blob') return bytes
+  // A chunked entry is the root manifest under the file's id: only reassembly can check that id,
+  // which the reader (readChunked) and the seal of a client pack (uploadPack) do.
+  if (e.kind === 'chunked') return bytes
   if (idOf(CONTEXT[e.kind], bytes) !== e.id) throw Object.assign(new Error(`pack entry ${e.id} does not match its id`), { code: 'pack_corrupt', id: e.id })
   return bytes
 }
@@ -109,10 +232,15 @@ export function readEntry (e, stored) {
 /**
  * What sealing checks before any row is written (03, "Sealing a pack"): the pack id is the
  * trailer's, and every entry decompresses to bytes whose id is the one claimed. Returns the index.
+ * `bases`: base id → plaintext, for the pack's delta entries (a delta with no base given fails).
+ * `dicts`: dictionary id → bytes, for entries with a trained dictionary (one not given fails).
  */
-export function verifyPack (bytes, expectId) {
+export function verifyPack (bytes, expectId, { sealed = false, bases = null, dicts = null } = {}) {
   const { id, index } = readIndex(bytes)
   if (expectId && id !== expectId) throw Object.assign(new Error('pack id does not match its trailer'), { code: 'pack_corrupt' })
-  for (const e of index) readEntry(e, bytes.subarray(e.offset, e.offset + e.len))
+  for (const e of index) {
+    const stored = bytes.subarray(e.offset, e.offset + e.len)
+    readEntry(e, stored, { sealed, base: e.kind === 'delta' ? bases?.get(deltaBase(stored)) || null : null, dict: usesTrained(e.flags) && stored.length >= 32 ? dicts?.get(trainedDictOf(stored)) || null : null })
+  }
   return { id, index }
 }

package/lib/quilts/persona.js

@@ -0,0 +1,70 @@
+// Local AI tools as agent members of their own (plans/quilt-source-control/11.5; TODO 3.8). With
+// `seam mcp --as-agent` (or SEAM_MCP_AGENT=1) each AI tool that connects is one of the signed-in
+// person's agents, named from its MCP `initialize` client name, and its seam_* calls carry an agent
+// token (sat_, agent-tokens.js) minted for it: `write` (or `merge` with --merge), for the block's
+// square (or its own squares outside a block), 8 hours. So the agent fences hold for it (token
+// caps, human-only paths, `agents` rows) and its commits name it, working for the person.
+// The secrets stay in <seam home>/personas.json (0600), renewed when under 15 minutes are left or
+// the block moves to another square; the token they replace is revoked.
+import fs from 'node:fs'
+import path from 'node:path'
+import crypto from 'node:crypto'
+
+const TTL_S = 8 * 60 * 60
+const RENEW_MS = 15 * 60 * 1000
+
+/** The agent's name for an MCP client name: printable, up to 80 characters; a tool that gives none is `ai-tool`. */
+export function personaName (clientName) {
+  const n = String(clientName || '').replace(/\s+/g, ' ').replace(/[^\w .@~+-]/g, '').trim().slice(0, 80).trim()
+  return n || 'ai-tool'
+}
+
+/**
+ * A function from { tool, quilt, square? } to { token, agent, id, expires_at }, for the person
+ * `client` signs in as (it needs agents, createAgent, createAgentToken, revokeAgentToken).
+ */
+export function personaTokens ({ client, home, merge = false, now = Date.now }) {
+  const file = path.join(home, 'personas.json')
+  const level = merge ? 'merge' : 'write'
+  const read = () => { try { return JSON.parse(fs.readFileSync(file, 'utf8')) || {} } catch { return {} } }
+  const write = (all) => {
+    fs.mkdirSync(home, { recursive: true, mode: 0o700 })
+    if (fs.existsSync(file) && fs.lstatSync(file).isSymbolicLink()) throw new Error(`Refusing to write ${file}: it's a symlink`)
+    const tmp = `${file}.tmp-${process.pid}-${crypto.randomBytes(6).toString('hex')}`
+    fs.writeFileSync(tmp, JSON.stringify(all, null, 2), { mode: 0o600, flag: 'wx' })
+    fs.renameSync(tmp, file)
+  }
+  const flight = new Map()
+
+  async function agentFor (name) {
+    const { agents } = await client.agents()
+    const a = agents.find((x) => x.name === name && !x.revoked_at)
+    return a ? a.member_id : (await client.createAgent({ name })).member_id
+  }
+
+  async function mint ({ tool, quilt, square }) {
+    const name = personaName(tool)
+    const key = `${quilt}|${name}|${level}`
+    const all = read()
+    const hit = all[key]
+    if (hit && (hit.square || null) === (square || null) && hit.expires_at - now() > RENEW_MS) return hit
+    // The agent is looked up again on each mint, so one its person revoked is not reused.
+    const agent = await agentFor(name)
+    const t = await client.createAgentToken(quilt, { agent, squares: square ? [square] : 'own', max_level: level, ttl_s: TTL_S })
+    const entry = { token: t.token, id: t.id, agent, square: square || null, expires_at: t.expires_at }
+    const next = Object.fromEntries(Object.entries(read()).filter(([, v]) => v.expires_at > now()))
+    next[key] = entry
+    write(next)
+    if (hit && hit.expires_at > now()) await client.revokeAgentToken(quilt, hit.id).catch(() => {})
+    return entry
+  }
+
+  // One mint at a time per tool and quilt: parallel tool calls share it.
+  return function tokenFor (want) {
+    const k = `${want.quilt}|${personaName(want.tool)}`
+    const prev = flight.get(k) || Promise.resolve()
+    const run = prev.catch(() => {}).then(() => mint(want))
+    flight.set(k, run)
+    return run
+  }
+}

package/lib/quilts/records.js

@@ -42,7 +42,9 @@ function side (s) {
     ...(s.mode ? { m: s.mode } : {}),
     ...(s.from_commit ? { fc: idBytes(s.from_commit) } : {}),
     ...(s.from_square ? { fs: s.from_square } : {}),
-    ...(s.by ? { by: s.by } : {})
+    ...(s.by ? { by: s.by } : {}),
+    // Where a side has the file when the sides disagree on its path (two renames of one file, 07).
+    ...(s.path ? { p: s.path } : {})
   }
 }
 const unside = (s) => ({
@@ -50,7 +52,8 @@ const unside = (s) => ({
   ...(s.m ? { mode: s.m } : {}),
   ...(s.fc ? { from_commit: hex(s.fc) } : {}),
   ...(s.fs ? { from_square: s.fs } : {}),
-  ...(s.by ? { by: s.by } : {})
+  ...(s.by ? { by: s.by } : {}),
+  ...(s.p ? { path: s.p } : {})
 })
 
 /** A conflict term's canonical bytes (kind, N adds, N−1 removes, origin). */
@@ -147,7 +150,8 @@ export function cleanCommit (c) {
   if (Buffer.byteLength(message) > MAX_MESSAGE) throw new Error('commit message over 64 KiB')
   const changes = cleanChanges(c.changes || [])
   const stack = {}
-  for (const [k, v] of Object.entries(c.stack || {})) if (v != null) stack[k] = String(v)
+  // null is kept: it hands the key back to derivation from this commit on (10 rule 2).
+  for (const [k, v] of Object.entries(c.stack || {})) if (v !== undefined) stack[k] = v === null ? null : String(v)
   return {
     quilt_id: String(c.quilt_id),
     square_id: String(c.square_id),

package/lib/quilts/recover.js

@@ -0,0 +1,37 @@
+// recover-gap (plans/quilt-source-control/03 and 15, "Backups and restore drills"): every commit
+// record is in a sealed pack before its row commits, so commits made after the last WAL segment
+// (whose `commit` rows the tip journal does not carry) come back from the packs alone. It lists
+// the quilt's packs, reads each trailer's index, decodes every `commit` entry, and returns the
+// ones replay did not already rebuild, parents before children.
+//
+// Their `seq` is not in any pack: 03 takes it from the relays' event hour, which Seam does not
+// keep, so recovered commits come back with `seq: null` and the order above (ruling 2026-10-26,
+// recorded in 03). A merge row in the journal still places each merged commit on its line.
+import { readIndex, readEntry } from './pack.js'
+import { decodeCommit } from './records.js'
+
+export async function recoverGap (objects, q, known = new Map()) {
+  const found = new Map()
+  for (const packId of await objects.listPacks(q)) {
+    const bytes = await objects.readPack(q, packId)
+    const { index } = readIndex(bytes)
+    for (const e of index) {
+      if (e.kind !== 'commit' || known.has(e.id) || found.has(e.id)) continue
+      const record = decodeCommit(readEntry(e, bytes.subarray(e.offset, e.offset + e.len)))
+      if (record.quilt_id !== q) continue
+      found.set(e.id, { id: e.id, ...record, seq: null, pack: packId })
+    }
+  }
+  // Parents (and predecessors) first, then by authored time; ids break ties so the order is stable.
+  const out = []
+  const placed = new Set()
+  const visit = (c, path = new Set()) => {
+    if (placed.has(c.id) || path.has(c.id)) return
+    path.add(c.id)
+    for (const p of [...c.parents, c.predecessor].filter(Boolean)) if (found.has(p)) visit(found.get(p), path)
+    placed.add(c.id)
+    out.push(c)
+  }
+  for (const c of [...found.values()].sort((a, b) => a.authored_at - b.authored_at || (a.id < b.id ? -1 : 1))) visit(c)
+  return out
+}

package/lib/quilts/runner.js

@@ -6,8 +6,10 @@
 import fs from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
+import http from 'node:http'
 import { spawn } from 'node:child_process'
 import { checkout } from './block.js'
+import { verifyWebhook } from './webhook.js'
 
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
 const safe = (key) => key.replace(/[^\w.-]+/g, '_').slice(0, 180)
@@ -19,10 +21,14 @@ export function logLink (template, runKey, file) {
 }
 
 /** The environment a run's command gets: what to run and, when Seam knows, which tests the change reaches. */
+// The runner's own sign-in to Seam: a check runs the patch's code, which never gets it (its tests
+// would reach the real server with the runner's key, and any patch could read the key).
+const RUNNER_ONLY = new Set(['SEAM_TOKEN', 'SEAM_API_URL', 'SEAM_QUILT', 'SEAM_WEBHOOK_SECRET', 'SEAM_HOME'])
+
 export function runEnv (run, base = process.env) {
   const a = run.affected || { confidence: 'all' }
   return {
-    ...base,
+    ...Object.fromEntries(Object.entries(base).filter(([k]) => !RUNNER_ONLY.has(k))),
     SEAM_CHECK: run.name, SEAM_TIER: run.tier, SEAM_COMMIT: run.commit, SEAM_RUN_KEY: run.run_key,
     SEAM_LINE: run.line || '', SEAM_SQUARE: run.square || '',
     SEAM_AFFECTED_CONFIDENCE: a.confidence, SEAM_AFFECTED_TESTS: a.confidence === 'all' ? '' : (a.tests || []).join('\n')
@@ -30,27 +36,58 @@ export function runEnv (run, base = process.env) {
 }
 
 /**
- * Runs checks for one quilt. { client, quilt, checks: ['ci'], run: 'npm test', dir (where block
+ * A runner config file: { quilt?, checks: { "<check>": "<command>", … } }, so one runner runs
+ * each check with its own command (CI and each deploy, say).
+ */
+export function readRunnerConfig (text) {
+  let c
+  try { c = JSON.parse(text) } catch (err) { throw new Error(`seam runner --config: not JSON (${err.message})`) }
+  const checks = c && typeof c.checks === 'object' && !Array.isArray(c.checks) ? c.checks : null
+  if (!checks || !Object.keys(checks).length || Object.values(checks).some((v) => typeof v !== 'string' || !v.trim())) throw new Error('seam runner --config: { "checks": { "<check>": "<command>" } }')
+  return { quilt: typeof c.quilt === 'string' ? c.quilt : null, commands: checks }
+}
+
+/**
+ * Runs checks for one quilt. { client, quilt, checks: ['ci'], run: 'npm test' (or commands: { ci:
+ * 'npm test', deploy: '…' }, one command per check), dir (where block
  * folders and logs go), api, once (handle what is queued now, then return), intervalMs, logUrl,
  * say(line) }. Returns the runs it finished: [{ run_key, status | 'cancelled', url }].
  */
-export async function runChecks ({ client, quilt, checks, run: command, dir = path.join(os.tmpdir(), 'seam-runner'), api, once = false, intervalMs = 5000, logUrl, say = () => {}, keep = false }) {
+export async function runChecks ({ client, quilt, checks, run: command, commands = null, dir = path.join(os.tmpdir(), 'seam-runner'), api, once = false, intervalMs = 5000, logUrl, say = () => {}, keep = false, wake = null, idleExitMs = 0, retryMs = 1000 }) {
   if (!checks?.length) throw new Error('seam runner needs --check <name>[,<name>]')
-  if (!command) throw new Error('seam runner needs --run "<command>"')
+  if (!command && !commands) throw new Error('seam runner needs --run "<command>" or --config <file>')
+  const commandOf = (name) => commands?.[name] || command
+  // Seam restarting (a deploy of Seam itself, run by this runner) answers 5xx or drops the
+  // connection for a moment: a call to it waits and tries again, for about a minute and a half.
+  const patiently = async (fn) => {
+    for (let i = 1; ; i++) {
+      try { return await fn() } catch (err) {
+        if (i >= 8 || (err.status && err.status < 500 && err.status !== 429)) throw err
+        await sleep(Math.min(retryMs * 2 ** (i - 1), retryMs * 15))
+      }
+    }
+  }
   const logs = path.join(dir, 'logs')
   fs.mkdirSync(logs, { recursive: true })
   const done = []
   const seen = new Set()
+  let lastWork = Date.now()
   for (;;) {
     const queued = []
-    for (const name of checks) queued.push(...(await client.checkRuns(quilt, { state: 'queued', name })).runs)
+    for (const name of checks) queued.push(...(await patiently(() => client.checkRuns(quilt, { state: 'queued', name }))).runs)
     const todo = queued.filter((r) => !seen.has(r.run_key)).sort((a, b) => a.at - b.at)
     for (const r of todo) {
       seen.add(r.run_key)
       done.push(await runOne(r))
+      lastWork = Date.now()
     }
     if (once) return done
-    await sleep(intervalMs)
+    // --idle-exit: nothing to do for that long, so stop (a stopped machine costs nothing; Seam's
+    // webhook starts it again on the next request).
+    if (idleExitMs && !todo.length && Date.now() - lastWork >= idleExitMs) return done
+    const nap = idleExitMs ? Math.max(50, Math.min(intervalMs, idleExitMs - (Date.now() - lastWork))) : intervalMs
+    // A wake (Seam's webhook) counts as work coming: the idle clock starts again.
+    if (wake) { if (await Promise.race([sleep(nap).then(() => false), wake().then(() => true)])) lastWork = Date.now() } else await sleep(nap)
   }
 
   async function runOne (r) {
@@ -59,17 +96,21 @@ export async function runChecks ({ client, quilt, checks, run: command, dir = pa
     const url = logLink(logUrl, r.run_key, file)
     say(`${r.name} (${r.tier}) on ${r.commit.slice(0, 12)}${r.square ? ` in ${r.square}` : ` at ${r.line}`}: running`)
     const out = fs.openSync(file, 'w')
+    const cmd = commandOf(r.name)
     let status
     try {
-      fs.writeSync(out, `seam runner: ${r.name} ${r.tier} ${r.commit} run_key ${r.run_key}\n$ ${command}\n`)
-      await checkout(client, { quilt, rev: r.commit, dir: work, api })
-      const child = spawn(command, { cwd: work, shell: true, env: runEnv(r), stdio: ['ignore', out, out], detached: process.platform !== 'win32' })
+      fs.writeSync(out, `seam runner: ${r.name} ${r.tier} ${r.commit} run_key ${r.run_key}\n$ ${cmd}\n`)
+      // The checkout waits out a restart too (a deploy of Seam landing as a check starts), each
+      // try into an empty folder.
+      await patiently(async () => { fs.rmSync(work, { recursive: true, force: true }); fs.mkdirSync(work, { recursive: true }); return checkout(client, { quilt, rev: r.commit, dir: work, api }) })
+      const child = spawn(cmd, { cwd: work, shell: true, env: runEnv(r), stdio: ['ignore', out, out], detached: process.platform !== 'win32' })
       const exited = new Promise((resolve) => child.on('close', (code) => resolve(code)))
       let cancelled = false
       for (;;) {
         const code = await Promise.race([exited, sleep(Math.min(intervalMs, 2000)).then(() => undefined)])
         if (code !== undefined) { status = code === 0 ? 'green' : 'red'; break }
-        const gone = (await client.checkRuns(quilt, { state: 'cancelled', name: r.name, limit: 50 })).runs.some((x) => x.run_key === r.run_key)
+        // Seam not answering just now is no cancellation: the next look asks again.
+        const gone = await client.checkRuns(quilt, { state: 'cancelled', name: r.name, limit: 50 }).then((x) => x.runs.some((y) => y.run_key === r.run_key), () => false)
         if (gone && !cancelled) {
           cancelled = true
           try { process.kill(process.platform !== 'win32' ? -child.pid : child.pid, 'SIGTERM') } catch { child.kill('SIGTERM') }
@@ -86,10 +127,36 @@ export async function runChecks ({ client, quilt, checks, run: command, dir = pa
     }
     if (status !== 'cancelled') {
       const body = { check: r.name, status, run_key: r.run_key, url }
-      if (r.tier === 'pre_merge' && r.square) await client.reportSquareCheck(quilt, r.square, { ...body, head: r.commit })
-      else await client.reportCheck(quilt, r.line, body)
+      if (r.tier === 'pre_merge' && r.square) await patiently(() => client.reportSquareCheck(quilt, r.square, { ...body, head: r.commit }))
+      else await patiently(() => client.reportCheck(quilt, r.line, body))
     }
     say(`${r.name} on ${r.commit.slice(0, 12)}: ${status} (log ${url})`)
     return { run_key: r.run_key, status, url }
   }
 }
+
+/**
+ * `seam runner --listen <port>`: an HTTP server Seam's webhook (seam events --webhook) POSTs
+ * check.requested to, so the runner starts at once instead of at its next poll, and a host that
+ * stops idle machines (Fly) starts this one when there is work. A POST signed with another secret
+ * than `secret` (when given) is refused. Returns { server, wake } for runChecks.
+ */
+export function listenForWork ({ port, secret = null, say = () => {} }) {
+  let waiting = []
+  const wake = () => new Promise((resolve) => { waiting.push(resolve) })
+  const ring = () => { const w = waiting; waiting = []; for (const r of w) r() }
+  const server = http.createServer((req, res) => {
+    if (req.method === 'GET') { res.writeHead(200, { 'content-type': 'text/plain' }); res.end('seam runner\n'); return }
+    const chunks = []
+    req.on('data', (c) => { chunks.push(c); if (chunks.reduce((n, x) => n + x.length, 0) > 1 << 20) req.destroy() })
+    req.on('end', () => {
+      const body = Buffer.concat(chunks).toString('utf8')
+      if (secret && !verifyWebhook(secret, req.headers['x-quilt-timestamp'], body, req.headers['x-quilt-signature'])) { res.writeHead(401); res.end(); return }
+      res.writeHead(202); res.end()
+      say(`seam runner: woken by ${req.headers['x-quilt-event'] || 'a request'}`)
+      ring()
+    })
+  })
+  server.listen(port)
+  return { server, wake }
+}