@heyquilt/seam 0.27.0 → 0.131.0

package/bin/seam.js

@@ -5,7 +5,7 @@ import fs from 'node:fs'
 import path from 'node:path'
 import { spawn } from 'node:child_process'
 import { fileURLToPath } from 'node:url'
-import { readAccount, login, logout, resume, call } from '../lib/account.js'
+import { readAccount, login, logout, resume, call, seamHome } from '../lib/account.js'
 
 const here = path.dirname(fileURLToPath(import.meta.url))
 // In the repo the client is read straight from the server's src/quilts (never a stale build);
@@ -19,42 +19,92 @@ Docs: https://seam.heyquilt.com/docs
 
   seam login [--no-browser]          Sign in with your Seam account (seam.heyquilt.com)
   seam logout | seam whoami
+  seam computers [list | signout <id or name>]   computers signed in to your account (seam login)
+  seam account delete --confirm <your email>   delete your Seam account (your patches stay)
   seam agent new <name> | list | key <name> | revoke <name> | relink [agent:<id>]   your agents and their keys
   seam oauth client new <name> --redirect <uri> | list | revoke <client_id>   apps that ask people for access (OAuth 2, PKCE)
   seam quilts [new <slug> | show <q>]  Your quilts (repositories)
-  seam import git <path> [--into <slug>]
+  seam import git <path> [--into <slug>] [--authors <file>]
   seam github [import <owner/name> --installation <id> [--into <slug>]]   from GitHub, followed
-  seam import git <remote-url> --into <slug> [--follow] [--interval <s>] [--credential <name>]
+  seam import git <remote-url> --into <slug> [--authors <file>] [--follow] [--interval <s>] [--credential <name>]
   seam import status <id> | seam import poke <id> | seam import cutover <id>   an import that follows git
+  seam export tarball [rev] [--paths a,b] [--out file]   one commit as a .tar.gz (git archive)
+  seam export archive [--out file]                       the whole quilt as one .tar (admin): segments, packs, members
+  seam export check <file>                               checks an archive (sizes, BLAKE3s, the log chain) offline
+  seam export extract <file> [rev] --to <dir>            one commit's files out of an archive, offline
+  seam export git <dir> --from <archive> [--line main]   a line's git history rebuilt from an archive, offline
   seam export remote <url> --quilt <q> [--line main,release/*] [--releases] [--credential <name>] | seam export status
+  seam clone <q> [folder] [--line <line>]   main into a folder, ready to work: the first commit opens a square
+  seam pull                          bring the line's new patches in (or rebase this folder's square onto them)
   seam square open "<title>" --quilt <q> [--dir <folder>]
   seam checkout <sq:id | revision> --quilt <q> [--dir <folder>] [-- paths]
   seam status | diff | commit -m "<message>"   in a block folder
   seam restore <paths> | reset [rev] | clean [-f]   throw away uncommitted edits
-  seam live [sq] | live share | live clear   uncommitted work others read as sq:<id>:live
-  seam merge [sq:id] [--into main]   seam rebase | revert <patch:n> | cherry-pick <rev>
-  seam resolve <path>... --ours | --theirs | --base | --side n | --delete
+  seam daemon [--debounce ms] | daemon status | daemon flush | daemon rebuild | daemon stop   watch this block folder, share each change as live work
+  seam live [sq] | live share [paths] | live clear | live join [sq] [--member m]   uncommitted work others read as sq:<id>:live
+  seam merge [sq:id] [--into main] [--no-commit-live]   seam rebase | revert <patch:n> | cherry-pick <rev>
+  seam resolve <path>... --ours | --theirs | --base | --side n | --delete | --keep-both | --rule <step>
   seam log [rev] [-n 20] [--oneline]  seam show <rev>  seam blame <path>[@rev]  seam cat | ls
   seam key [add [--name n] | remove <key>]   seam commit --sign | sign [rev]   seam log --show-signature
   seam line [new <name> [--from rev] | freeze | unfreeze]  Lines: main, release/<name>
   seam tag [<name> [rev]]            seam release [<name> [rev] -m <notes>]  Read as tag:<name>
   seam commit --amend [-m "<message>"]   change your square's last commit
   seam square open "<title>" --on sq:<id>   a square stacked on another
-  seam claim <path|glob> [--note why] | unclaim <id>   files your square is working on
-  seam review approve|request-changes|comment|dismiss <sq>   seam line require <line> [--approvals n] [--checks a,b] [--runners ci=<member>]
-  seam check <name> green|red [--square sq | --patch n] [--run-key k]   report a check (a red one on a patch reverts it)
+  seam square open "<title>" --stack-keys db_branch=supabase:<ref>   stack keys its first commit carries
+  seam claim <path|glob> [--note why] [--expires secs] | unclaim <id>   files your square is working on
+  seam claim request <claim> --title what | withdraw <id> | handoff <claim> [--note ...]   wait for a claim, hand one over
+  seam claim finish [--note ...]   let go of your square's auto-claims now (queued ones go to the first in line)
+  seam watch [<glob>... [--classes logic] [--min-lines 50]] | watch remove <id>   hear of patches that change them
+  seam review approve|request-changes|comment|dismiss <sq> [--scope <glob>,<glob>]   seam review comment [sq] --path <f> --line <n> [--to-line <m>] --suggest <text>   seam review apply <review id> [sq]   seam review request [sq] [--to <member>[,<member>]] [-m <why>]   seam review interdiff [sq] [--since <rev>]   seam line require <line> [--approvals n] [--checks a,b] [--runners ci=<member>] [--auto-combine lines|additive|whitespace] [--approval-survives none|whitespace|comment-only|docs|default] [--needs-stack db_branch|none] [--monotonic-stack db_migration] [--migrations-in-order on] [--stack-defaults db_branch=supabase:<ref>|none]
+  seam check <name> green|red [--square sq | --patch n] [--run-key k]   report a check (a red one after a merge is bisected; on a patch it reverts it)
+  seam check pipeline <name> [--line main]   the bisect of a red check, and what the last one found
+  seam check pipeline <name> --stop          stop that bisect (admin): its waiting runs are cancelled
   seam checks [--state queued] [--name ci] [--tier pre_merge|post_merge]   check runs Seam asked runners for
   seam runner --check ci --run "npm test" [--quilt <q>] [--once]   run the checks Seam asks you for, on this machine
-  seam resolutions [forget <key>]    conflicts settled before, settled the same way again
-  seam bisect <bad> <good> --run "<check>"   seam grep <pattern> [rev] [--all]   seam describe [rev]   seam merge-base <a> <b>
-  seam log --follow <path> | log -S <text>
+  seam runner --config runner.json [--listen <port>] [--idle-exit <s>]   a command per check; woken by Seam's webhook
+  seam resolutions [--hunks] [forget <key>]   conflicts settled before, settled the same way again
+  seam bisect <bad> <good> --run "<check>" [-- paths]   seam grep <pattern> [rev] [--all]   seam describe [rev]   seam merge-base <a> <b>
+  seam stack [rev]   the full-stack pointers at a revision (db_migration, db_branch, …) and where each was set   seam diff <a> <b> --stack   which of them changed
+  seam quilts infra-paths <glob,glob>|default|none --quilt <q>   what seam stack derives infra from
+  seam quilts owner-idle-hours <1..24>|default --quilt <q>   how long an owner claim holds after the last write
+  seam quilts public-reads --quilt <q>   what readers with no sign-in fetched (90 days, address hashed)
+  seam quilts migrations-dir <folder>|none|default --quilt <q>   where seam stack derives db_migration from
+  seam contains <rev>   lines that have it, and where it was cherry-picked or reverted   seam merge-base --is-ancestor <a> <b>
+  seam log --follow <path> | log -S <text> | -G <regex> | --grep <text> [-E] [-i] | --author <who> --task <id> --since 3d --until <t>
+  seam log --group-by author|on_behalf_of|task|tool   seam log --graph | --include-hidden | --cursor <c>
+  seam diff <a> <b> [--stat | --name-status] [--no-renames | --renames exact] [-w | --ignore-space-at-eol] [-U <n>]
+  seam search <query> [--at <rev>] [--all]   words, "phrases", /regex/, path:, lang:, symbol:, class:, -term, OR
+  seam blame <path>[@rev] [-L a,b] [--ignore-rev <rev,…>] [-M] [--reverse <rev>]
+  seam block [rebuild | open <square> [--paths a,b] [--mode m] [--read-only] | touch <id> | close <id>]   blocks on the server
   seam token [new <name> [--level read|write] | revoke <name>]   a key for one quilt, for CI
-  seam events [--webhook <url>]      What happened to your squares
+  seam token agent [new [--agent agent:<id>] [--level write] [--paths src] [--hours 8] | revoke <id>]   the key an agent writes with
+  seam protect [add <path> <who> <level> [--exclude] | remove <n> | set <file> | reset | check <path>]   who may do what under which path
+  seam team [set <name> <member>... | remove <name>]   teams the protections name
+  seam verify [--after <seq>] [--keys <file>]   check the quilt's log against the server's signatures
+  seam metrics   the quilt's numbers the monitors watch (archiver lag, open scrub findings, …) and which are past their threshold
+  seam redact <blob | path[@rev]> --reason "<why>" --yes | redact list   remove a secret's bytes for good, history kept
+  seam quilts secret-scanning [refuse|warn|off]   seam commit --allow sf_…   commits that look like they hold secrets
+  seam policy [sq]   seam line require <line> --rules rules.json   change classes and rules by path and class
+  seam policy versions <line> | approve|reject|confirm <line> <version>   a line's policy versions and their approval
+  seam org [new <slug> | show <org> | add <org> <member> [--role r] | remove <org> <member>]   orgs that own quilts
+  seam org log <org> [-n <count>] [--before <id>]   what happened in an org: members, roles, teams, quilts (owners and admins)
+  seam org team <org> <name> [<member>...]   an org's team, named org_team:<name> in its quilts' protections
+  seam quilts new <slug> --org <org> | quilts move --quilt <q> --org <org>   a quilt that belongs to an org
+  seam quilts agents-make-lines on|off   whether agents may make lines, tags and releases
+  seam quilts public on|off           anyone may read the quilt, signed in or not
+  seam quilts add <email|member> [--level read|write|admin]   add a member; an email with no account yet is invited
+  seam quilts new <slug> --sealed     a quilt the server never reads: its key lives on members' computers
+  seam quilts sealed on|off --quilt <q>   switch a quilt that holds no files yet to sealed or back
+  seam seal [status] | key | grant <member> | rotate [--without <member>]   a sealed quilt's key
+  seam events [--follow|--webhook <url>]  What happened to your squares
   seam export git <dir>              Back to git
   seam mcp                           The same commands as MCP tools, for your AI tool
+  seam mcp --as-agent [--merge]      The same, with the AI tool as an agent of yours, on a token of its own
   seam serve                         Run a Seam server (SEAM_AUTH_URL: its own accounts; SEAM_IDENTITY_URL: a sign-in service)
+  seam worker                        Run Seam's derived jobs and events off the API machines (they set SEAM_DERIVE_WORKERS=queue)
 
-Agents: set SEAM_TOKEN to the agent's key instead of signing in.`
+Agents: set SEAM_TOKEN to the agent's key instead of signing in.
+SEAM_CONFLICT_STYLE=git writes conflicts with git's <<<<<<< markers.`
 
 const cmd = process.argv[2]
 const argv = process.argv.slice(3)
@@ -73,6 +123,14 @@ async function main () {
   if (cmd === 'logout') { const a = await logout(); return console.log(a ? `Signed out of ${a.account.email}.` : 'Not signed in.') }
   if (cmd === 'whoami') { const a = readAccount(); if (!a) { process.exitCode = 1; return console.log('Not signed in.') } return console.log(`${a.account.name} (${a.account.email})`) }
   if (cmd === 'agent') return agentCommand(argv[0], argv[1])
+  if (cmd === 'computers') return computersCommand(argv[0], argv[1])
+  if (cmd === 'account') {
+    const i = argv.indexOf('--confirm')
+    if (argv[0] !== 'delete' || i < 0 || !argv[i + 1]) fail('seam account delete --confirm <your email>')
+    const r = await signedIn()('DELETE', `/v1/me?confirm=${encodeURIComponent(argv[i + 1])}`)
+    await logout().catch(() => {})
+    return console.log(`Deleted your Seam account. Your patches stay as ${r.member_id}.`)
+  }
   if (cmd === 'oauth') return oauthCommand(argv)
   if (cmd === 'mcp') return mcp()
   // The server is not in the package (it ships the client): it runs from Seam's source or its image.
@@ -80,6 +138,10 @@ async function main () {
     if (QUILTS === '../lib/quilts') fail('seam serve runs from Seam\'s source: node src/quilts/server.js in the repository, or the Dockerfile.seam image (docs/seam-service.md).')
     return (await quilts('server.js')).serveFromEnv(process.env)
   }
+  if (cmd === 'worker') {
+    if (QUILTS === '../lib/quilts') fail('seam worker runs from Seam\'s source: node src/quilts/server.js worker in the repository, or the Dockerfile.seam image (docs/seam-service.md).')
+    return (await quilts('server.js')).workerFromEnv(process.env)
+  }
   const { SEAM_VERBS, runSeamCommand } = await quilts('cli.js')
   if (!SEAM_VERBS.has(cmd)) fail(`seam: '${cmd}' is not a seam command. See seam help.`)
   try {
@@ -127,10 +189,11 @@ async function oauthCommand (argv) {
 }
 
 // `seam agent …`: an account's agents, each with its own key (SEAM_TOKEN for that agent).
-async function agentCommand (sub, name) {
+// A call as the signed-in computer, resuming once when its key has expired.
+function signedIn () {
   const a = readAccount()
   if (!a) fail('Not signed in: run seam login.')
-  const go = async (method, route, body) => {
+  return async (method, route, body) => {
     try { return await call(method, route, body, a.token) } catch (err) {
       if (err.status !== 401) throw err
       const back = await resume().catch(() => null)
@@ -138,6 +201,29 @@ async function agentCommand (sub, name) {
       return call(method, route, body, back.token)
     }
   }
+}
+
+// `seam computers`: the computers signed in to your account with seam login; `signout <id or name>` ends one.
+async function computersCommand (sub, which) {
+  const go = signedIn()
+  const { keys } = await go('GET', '/v1/me/keys')
+  if (!sub || sub === 'list') {
+    for (const k of keys) console.log(`${k.name}  ${k.id}  since ${new Date(k.created_at).toISOString().slice(0, 10)}${k.current ? '  (this computer)' : ''}`)
+    return
+  }
+  if (sub === 'signout') {
+    if (!which) fail('seam computers signout <id or name>')
+    const found = keys.filter((k) => k.id === which || k.name === which)
+    if (!found.length) fail(`No signed-in computer ${which}: seam computers lists them.`)
+    if (found.length > 1) fail(`${found.length} computers are named ${which}; use its id.`)
+    const r = await go('DELETE', `/v1/me/keys/${encodeURIComponent(found[0].id)}`)
+    return console.log(`Signed out ${r.name}${found[0].current ? ' (this computer: run seam login to sign in again)' : ''}.`)
+  }
+  fail(`seam computers: '${sub}' is not a computers command (list, signout).`)
+}
+
+async function agentCommand (sub, name) {
+  const go = signedIn()
   const showKey = (r) => console.log(`${r.name} (${r.member_id})\n\n  SEAM_TOKEN=${r.key}\n\nThis key is shown once. Give it to the agent as SEAM_TOKEN; seam agent key ${r.name} makes a new one and ends this one.`)
   if (sub === 'new') { if (!name) fail('seam agent new <name>'); return showKey(await go('POST', '/v1/agents', { name })) }
   if (sub === 'key') { if (!name) fail('seam agent key <name>'); return showKey(await go('POST', `/v1/agents/${encodeURIComponent(name)}/key`)) }
@@ -168,7 +254,22 @@ async function mcp () {
   const { connect } = await quilts('cli.js')
   const { findBlock } = await quilts('block.js')
   const server = new McpServer({ name: 'seam', version }, { instructions: SEAM_GUIDE })
-  registerSeamTools(server, { client: () => connect(findBlock()?.block, readAccount()?.token).client, found: () => findBlock() })
+  // --as-agent (SEAM_MCP_AGENT=1): the AI tool is an agent of yours, with a token of its own (11.5).
+  const asAgent = process.argv.includes('--as-agent') || process.env.SEAM_MCP_AGENT === '1'
+  let tokens = null
+  const client = async (args = {}) => {
+    const block = findBlock()?.block
+    const person = connect(block, readAccount()?.token)
+    const quilt = args.quilt || block?.quilt
+    if (!asAgent || !quilt) return person.client
+    const { personaTokens } = await quilts('persona.js')
+    const { quiltClient } = await quilts('client.js')
+    tokens ||= personaTokens({ client: person.client, home: seamHome(), merge: process.argv.includes('--merge') })
+    const square = !args.quilt || args.quilt === block?.quilt ? block?.square : null
+    const t = await tokens({ tool: server.server.getClientVersion()?.name, quilt, square })
+    return quiltClient({ api: person.api, token: t.token })
+  }
+  registerSeamTools(server, { client, found: () => findBlock() })
   await server.connect(new StdioServerTransport())
 }
 

package/lib/quilts/agent-tokens.js

@@ -0,0 +1,148 @@
+// Agent quilt tokens (plans/quilt-source-control/11.5, 04 "Credentials"; TODO 3.1): an agent works
+// in a quilt with a token scoped to that quilt, to squares (`own`: the ones it holds or writes;
+// or a list), to paths, and to a level (read, write or merge; never admin), that ends after hours
+// (8 by default, 7 days at most). A person mints one for an agent working for them, or the agent
+// trades its own key for one; either way it never does more than its person can. On a server
+// started with SEAM_AGENT_TOKENS=1, an agent's own key reads but no longer writes: it writes with
+// a token. Quilt tokens for CI (sqt_, tokens.js) are a different kind and work as before.
+import crypto from 'node:crypto'
+import { QuiltError, squareShort } from './errors.js'
+import { uuidv7 } from './ids.js'
+import { cleanPrefix } from './records.js'
+import { RATE_NAMES, rateDefault } from './limits.js'
+
+export const AGENT_TOKEN_PREFIX = 'sat_'
+export const MAX_LIVE = 20 // per agent per quilt
+export const DEFAULT_TTL_MS = 8 * 60 * 60 * 1000
+export const MAX_TTL_MS = 7 * 24 * 60 * 60 * 1000
+const SECRET = /^sat_[A-Za-z0-9_-]{43}$/
+const LEVELS = ['read', 'write', 'merge']
+const RANK = { read: 1, write: 2, merge: 3, admin: 4 }
+
+const sha = (s) => crypto.createHash('sha256').update(String(s)).digest('hex')
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+export const isAgentToken = (s) => SECRET.test(String(s || ''))
+
+/** Whether an agent token lets its agent write to square `sq` (11.5: `own` is checked every time). */
+export function tokenReachesSquare (token, sq, agent) {
+  if (!token || token.kind !== 'agent') return true
+  if (token.squares === 'own') return sq.holder === agent || (sq.writers || []).includes(agent)
+  return token.squares.includes(sq.id)
+}
+
+/** 11.5 `checks`: a token with `checks: false` reports no check verdicts (13). Tokens made before the field (null) still do. */
+export function refuseChecks (me) {
+  if (me && me.token && me.token.kind === 'agent' && me.token.checks === false) throw new QuiltError(403, 'not_in_token', 'this token does not report check verdicts: mint one with checks: true (seam token agent new --checks)', { need: 'checks' })
+}
+
+/** 11.9 QuiltToken.rate: lower numbers for 04's per-token rows, never higher. */
+function cleanRate (rate) {
+  if (rate == null) return null
+  if (typeof rate !== 'object' || Array.isArray(rate)) throw new QuiltError(400, 'bad_request', `rate is an object of ${RATE_NAMES.join(', ')}`)
+  const out = {}
+  for (const [name, v] of Object.entries(rate)) {
+    if (!RATE_NAMES.includes(name)) throw new QuiltError(400, 'bad_request', `rate: ${name} is not a per-token limit (${RATE_NAMES.join(', ')})`)
+    if (!Number.isInteger(v) || v < 1) throw new QuiltError(400, 'bad_request', `rate.${name} is a whole number of 1 or more`)
+    if (v > rateDefault(name)) throw new QuiltError(400, 'bad_request', `rate.${name}: ${v} is above Seam's ${rateDefault(name)}; a token's rate lowers limits, it never raises them`)
+    out[name] = v
+  }
+  return Object.keys(out).length ? out : null
+}
+
+export function agentTokenOps (svc, { required = false } = {}) {
+  const { store, now, quiltFor, fromStore } = svc.internals
+  // A Seam agent's row (keys.js), when the member id names one; agents from another sign-in have none.
+  const seamAgent = async (member) => store.getAgent && UUID.test(member.slice(6)) ? store.getAgent(member.slice(6)) : null
+
+  const view = (r) => ({ id: r.id, agent: r.agent, on_behalf_of: r.on_behalf_of, squares: r.squares, paths: r.paths, max_level: r.max_level, checks: r.checks ?? null, rate: r.rate ?? null, expires_at: r.expires_at, issued_by: r.issued_by, created_at: r.created_at, ...(r.revoked_at ? { revoked_at: r.revoked_at } : {}) })
+
+  /**
+   * POST /agent-tokens { agent?, squares?, paths?, max_level?, ttl_s? }: a token for an agent in
+   * this quilt. A person names their agent (`agent: agent:<id>`); an agent asks for itself.
+   */
+  async function createAgentToken (me, ref, body = {}) {
+    if (me.token) throw new QuiltError(403, 'forbidden', 'a token cannot mint a token')
+    // An agent asking for itself reaches the quilt through the person it works for.
+    const q = await quiltFor(me.kind === 'person' || !me.on_behalf_of ? me : { member_id: me.on_behalf_of, kind: 'person', name: me.name }, ref, 'read')
+    let agent, person
+    if (me.kind === 'person') {
+      agent = String(body.agent || '')
+      if (!/^agent:\S{1,190}$/.test(agent)) throw new QuiltError(400, 'bad_request', 'agent: the agent this token is for (agent:<id>)')
+      // A Seam agent belongs to an account: only that account's person mints for it.
+      const a = await seamAgent(agent)
+      if (a && store.getAccount) { const acc = await store.getAccount(a.account_id); if (acc && acc.member_id !== me.member_id) throw new QuiltError(403, 'forbidden', `${agent} is not one of your agents`) }
+      person = me.member_id
+    } else {
+      if (body.agent && body.agent !== me.member_id) throw new QuiltError(403, 'forbidden', 'an agent mints a token for itself only')
+      if (!me.on_behalf_of) throw new QuiltError(403, 'forbidden', 'an agent working for nobody gets no token; a person mints one for it')
+      agent = me.member_id
+      person = me.on_behalf_of
+    }
+    const level = body.max_level || 'write'
+    if (!LEVELS.includes(level)) throw new QuiltError(400, 'bad_request', 'max_level is read, write or merge (a token never carries admin)')
+    // Never more than the person holds (11.5: minted by a person who holds at least the level asked).
+    const personRole = await svc.internals.levelIn(q, person)
+    const personAccess = personRole ? await svc.internals.accessOfMember(q, person) : null
+    if (!personAccess || RANK[personAccess.max] < RANK[level]) throw new QuiltError(403, 'forbidden', `${person} does not hold ${level} on this quilt, so no token for it can`)
+    const squares = body.squares == null || body.squares === 'own' ? 'own' : body.squares
+    if (squares !== 'own') {
+      if (!Array.isArray(squares) || squares.length > 100) throw new QuiltError(400, 'bad_request', 'squares is own, or a list of up to 100 squares')
+      for (let i = 0; i < squares.length; i++) squares[i] = (await svc.internals.squareByRef(q.id, squares[i])).id
+    }
+    const paths = (body.paths || []).map(cleanPrefix)
+    if (paths.length > 50) throw new QuiltError(400, 'bad_request', 'paths is up to 50 prefixes')
+    const ttl = body.ttl_s == null ? DEFAULT_TTL_MS : Number(body.ttl_s) * 1000
+    if (!Number.isFinite(ttl) || ttl < 60 * 1000 || ttl > MAX_TTL_MS) throw new QuiltError(400, 'bad_request', 'ttl_s is from 60 seconds to 7 days')
+    if (body.checks != null && typeof body.checks !== 'boolean') throw new QuiltError(400, 'bad_request', 'checks is true or false: whether the token reports check verdicts')
+    // Default (11.5): false. Without SEAM_AGENT_TOKENS a token says nothing (null), so nothing that reports verdicts today breaks.
+    const checks = body.checks ?? (required ? false : null)
+    const rate = cleanRate(body.rate)
+    const live = (await store.agentTokens(q.id)).filter((t) => t.agent === agent && !t.revoked_at && t.expires_at > now())
+    if (live.length >= MAX_LIVE) throw new QuiltError(409, 'too_many_tokens', `an agent holds at most ${MAX_LIVE} live tokens per quilt; revoke one first`)
+    const secret = AGENT_TOKEN_PREFIX + crypto.randomBytes(32).toString('base64url')
+    const at = now()
+    try {
+      const row = await store.createAgentToken({ id: uuidv7(at), quilt_id: q.id, agent, on_behalf_of: person, squares, paths, max_level: level, checks, rate, hash: sha(secret), issued_by: me.member_id, created_at: at, expires_at: at + ttl })
+      return { ...view(row), quilt: q.slug, token: secret }
+    } catch (err) { throw fromStore(err) }
+  }
+
+  /** GET /agent-tokens: the quilt's agent tokens (a person sees theirs, an admin every one), never secrets. */
+  async function agentTokens (me, ref) {
+    const q = await quiltFor(me, ref, 'read')
+    const all = await store.agentTokens(q.id)
+    const admin = q.access.can('', 'admin')
+    return { quilt: q.slug, tokens: all.filter((t) => admin || t.on_behalf_of === me.member_id || t.agent === me.member_id).map(view) }
+  }
+
+  /** DELETE /agent-tokens/:id: ends a token at once (its person, its agent, or an admin). */
+  async function revokeAgentToken (me, ref, id) {
+    const q = await quiltFor(me, ref, 'read')
+    const t = (await store.agentTokens(q.id)).find((x) => x.id === String(id))
+    if (!t) throw new QuiltError(404, 'not_found', `no agent token ${id}`)
+    if (!(q.access.can('', 'admin') || t.on_behalf_of === me.member_id || t.agent === me.member_id)) throw new QuiltError(403, 'forbidden', 'only its person, its agent or an admin revokes a token')
+    if (t.revoked_at) return view(t)
+    try { return view(await store.revokeAgentToken({ quilt_id: q.id, id: t.id, actor: me.member_id, at: now() })) } catch (err) { throw fromStore(err) }
+  }
+
+  /** The caller an agent token stands for, or null when it is unknown, revoked, expired, or its agent was revoked. */
+  async function agentTokenCaller (secret) {
+    if (!isAgentToken(secret)) return null
+    const t = await store.agentTokenByHash(sha(secret))
+    if (!t || t.revoked_at || t.expires_at <= now()) return null
+    const a = await seamAgent(t.agent)
+    if (a && a.revoked_at) return null
+    return { member_id: t.agent, kind: 'agent', name: a?.name || t.agent, tool: 'seam', on_behalf_of: t.on_behalf_of, token: { id: t.id, kind: 'agent', quilt_id: t.quilt_id, level: t.max_level, squares: t.squares, paths: t.paths, checks: t.checks ?? null, rate: t.rate ?? null, expires_at: t.expires_at } }
+  }
+
+  /** With SEAM_AGENT_TOKENS=1, an agent's own key reads only: a write needs a token (403 token_required). */
+  function guardKey (me, need) {
+    if (!required || me.kind === 'person' || me.public || me.token || need === 'read') return
+    throw new QuiltError(403, 'token_required', 'an agent writes with a quilt token, not its own key: mint one with seam token agent new (POST /v1/quilts/<q>/agent-tokens), then use it as SEAM_TOKEN')
+  }
+
+  return { createAgentToken, agentTokens, revokeAgentToken, agentTokenCaller, internals: { guardKey } }
+}
+
+export const describeAgentToken = (t) => `Agent token ${t.id} for ${t.agent} (working for ${t.on_behalf_of}) on ${t.quilt}: ${t.max_level}, ${t.squares === 'own' ? 'its own squares' : `squares ${t.squares.map(squareShort).join(', ')}`}${t.paths.length ? `, paths ${t.paths.join(', ')}` : ''}${t.checks ? ', reports checks' : ''}${t.rate ? `, rate ${Object.entries(t.rate).map(([k, v]) => `${k} ${v}`).join(', ')}` : ''}, until ${new Date(t.expires_at).toISOString()}. Its secret, shown only this once:\n\n  ${t.token}\n\nSet it as SEAM_TOKEN for the agent.`
+export const describeAgentTokens = (r) => r.tokens.length ? r.tokens.map((t) => `${t.id}  ${t.agent}  ${t.max_level}  ${t.squares === 'own' ? 'own' : `${t.squares.length} squares`}${t.paths.length ? `  ${t.paths.join(',')}` : ''}  ${t.revoked_at ? 'revoked' : `until ${new Date(t.expires_at).toISOString()}`}`).join('\n') : `${r.quilt} has no agent tokens.`

package/lib/quilts/archiver.js

@@ -0,0 +1,241 @@
+// The log archiver (plans/quilt-source-control/03, "The log order and the archiver"; 15
+// invariant 5): copies a quilt's log rows, with the commit rows they write, into immutable WAL
+// segments in object storage, so the database is rebuildable by replay. A segment is written when
+// 1,000 rows are waiting or the oldest waiting row is 5 minutes old, holds at most 1,000 rows, and
+// names the segment before it by hash, so a quilt's segments are one chain. archive_seq then moves
+// by compare-and-swap (setArchive), so two archivers never both advance one quilt; a loser's
+// segment has the same name and the same bytes as the winner's (rows are immutable and the
+// encoding is deterministic), and object storage keeps the first.
+//
+// Segment bytes: 'QWS1', a flag byte (0 deflate-raw, 1 zstd), the compressed body (one canonical
+// JSON record a line: { t: 'log', row } or { t: 'commit', row }), the trailer JSON
+// { quilt_id, from_seq, to_seq, row_count, prev, blake3 } and its length as a u32. `blake3` is
+// the hash of everything before the trailer; `prev` the previous segment's (64 zeros first).
+import zlib from 'node:zlib'
+import { blake3 } from '@noble/hashes/blake3.js'
+import { readJournal } from './journal.js'
+import { recoverGap } from './recover.js'
+
+export const SEGMENT_ROWS = 1000
+export const SEGMENT_AGE_MS = 5 * 60 * 1000
+const MAGIC = Buffer.from('QWS1')
+const LEASE = ' archive' // a line lease name no real line can have (names never start with a space)
+const LEASE_MS = 5 * 60 * 1000
+export const LAG_ROWS = 10000
+export const LAG_MS = 30 * 60 * 1000
+const ZERO = '0'.repeat(64)
+const HAS_ZSTD = typeof zlib.zstdCompressSync === 'function'
+
+const pad = (n) => String(n).padStart(12, '0')
+/** 03's key w/<from_seq>-<to_seq>.qws, zero-padded so names sort in seq order. */
+export const segmentName = (from, to) => `${pad(from)}-${pad(to)}.qws`
+const hashOf = (bytes) => Buffer.from(blake3(bytes)).toString('hex')
+
+/** Canonical JSON: keys sorted at every level, so the same rows always give the same bytes. */
+function canonical (v) {
+  if (Array.isArray(v)) return '[' + v.map(canonical).join(',') + ']'
+  if (v && typeof v === 'object') return '{' + Object.keys(v).sort().filter((key) => v[key] !== undefined).map((key) => JSON.stringify(key) + ':' + canonical(v[key])).join(',') + '}'
+  return JSON.stringify(v ?? null)
+}
+
+// Commit-row columns that change after the row is written (03's replay table derives them):
+// hidden_seq from successors' `predecessor`, patch from merge rows, snapshot_root from the merge
+// row or the deriver. A segment keeps only what never changes.
+const LATER = ['hidden_seq', 'patch', 'snapshot_root']
+export const frozenCommit = (c) => { const out = { ...c }; for (const key of LATER) delete out[key]; return out }
+
+export function encodeSegment ({ quilt_id: q, from_seq: from, to_seq: to, prev, records }) {
+  const body = Buffer.from(records.map(canonical).join('\n'), 'utf8')
+  const head = Buffer.concat([MAGIC, Buffer.from([HAS_ZSTD ? 1 : 0]), HAS_ZSTD ? zlib.zstdCompressSync(body) : zlib.deflateRawSync(body, { level: 6 })])
+  const trailer = { quilt_id: q, from_seq: from, to_seq: to, row_count: records.filter((r) => r.t === 'log').length, prev, blake3: hashOf(head) }
+  const tb = Buffer.from(canonical(trailer), 'utf8')
+  const len = Buffer.alloc(4); len.writeUInt32BE(tb.length)
+  return { bytes: Buffer.concat([head, tb, len]), trailer }
+}
+
+export function decodeSegment (bytes) {
+  if (bytes.length < 9 || !bytes.subarray(0, 4).equals(MAGIC)) throw new Error('not a WAL segment')
+  const tl = bytes.readUInt32BE(bytes.length - 4)
+  const head = bytes.subarray(0, bytes.length - 4 - tl)
+  const trailer = JSON.parse(bytes.subarray(head.length, bytes.length - 4).toString('utf8'))
+  if (hashOf(head) !== trailer.blake3) throw new Error(`segment ${trailer.from_seq}-${trailer.to_seq}: its bytes do not match its hash`)
+  const flag = head[4]
+  if (flag === 1 && !HAS_ZSTD) throw new Error('this segment is zstd and this Node cannot read zstd (needs Node 22.15 or later)')
+  // Bounded as pack entries are (pack.js): a segment of 1,000 log rows is far under 64 MiB.
+  const body = (flag === 1 ? zlib.zstdDecompressSync : zlib.inflateRawSync)(head.subarray(5), { maxOutputLength: 64 * 1024 * 1024 }).toString('utf8')
+  return { trailer, records: body ? body.split('\n').map((l) => JSON.parse(l)) : [] }
+}
+
+/**
+ * The archiver over a store and an object store. `archive(q, { force })` writes every segment
+ * that is due (with `force`, the rest too, in segments of at most 1,000 rows) and returns
+ * { segments, archive_seq }. `maybe(q)` runs it in the background, once at a time per quilt.
+ */
+export function createArchiver ({ store, objects, now = Date.now, rows = SEGMENT_ROWS, ageMs = SEGMENT_AGE_MS, log = () => {}, holder = `archiver:${process.pid}:${Math.random().toString(36).slice(2, 10)}`, leaseMs = LEASE_MS }) {
+  const running = new Map()
+  const alerting = new Set()
+
+  async function writeOne (q, quilt, to) {
+    const from = (quilt.archive_seq || 0) + 1
+    const records = []
+    for (let after = from - 1; after < to;) {
+      const page = await store.logRows(q, { after, limit: Math.min(1000, to - after) })
+      if (!page.length) throw new Error(`log rows ${after + 1}..${to} are missing: the archiver never writes past a gap`)
+      for (const row of page) {
+        if (row.seq !== after + 1) throw new Error(`log row ${after + 1} is missing (found ${row.seq}): the archiver never writes past a gap`)
+        records.push({ t: 'log', row })
+        after = row.seq
+        // The commit row this log row wrote (a commit, or the rebased commit of a merge).
+        const id = row.kind === 'commit' || row.kind === 'merge' ? row.commit || row.commit_id : null
+        if (id) {
+          const c = await store.getCommit(q, id)
+          if (c && c.seq === row.seq) records.push({ t: 'commit', row: frozenCommit(c) })
+        }
+      }
+    }
+    // Every check run not yet in a segment (03); a run that changes later goes in again, and
+    // replay keeps the last copy of each run_key.
+    const runs = store.unarchivedCheckRuns ? await store.unarchivedCheckRuns(q) : []
+    for (const run of runs) records.push({ t: 'check_run', row: run })
+    const prev = quilt.last_segment || ZERO
+    const { bytes, trailer } = encodeSegment({ quilt_id: q, from_seq: from, to_seq: to, prev, records })
+    await objects.putFile(q, 'w', segmentName(from, to), bytes)
+    const r = await store.setArchive({ quilt_id: q, expect_seq: from - 1, to_seq: to, segment: trailer.blake3 })
+    if (runs.length) await store.markCheckRunsArchived({ quilt_id: q, runs: runs.map(({ run_key, state, verdict }) => ({ run_key, state, verdict: verdict ?? null })), at: now() })
+    return { ...trailer, archive_seq: r.archive_seq }
+  }
+
+  // One archiver per quilt at a time, across processes (03: "per quilt, under a lease"). A second
+  // one finds the lease held and writes nothing; CAS on archive_seq still guards a lease that lapsed.
+  async function archive (q, opts = {}) {
+    const lease = await store.takeLease({ kind: 'line', quilt_id: q, line: LEASE, holder, ttl_ms: leaseMs, at: now() })
+    if (!lease.held) {
+      const quilt = await store.getQuilt(q)
+      return { segments: [], archive_seq: quilt?.archive_seq || 0, leased_by: lease.holder }
+    }
+    try { return await archiveHeld(q, opts) } finally {
+      await store.giveLease({ kind: 'line', quilt_id: q, line: LEASE, holder }).catch(() => {})
+    }
+  }
+
+  /** Archiver lag (15): rows since the last segment and the age of the oldest of them; `alert` past 10,000 rows or 30 minutes. */
+  async function lag (q) {
+    const quilt = await store.getQuilt(q)
+    if (!quilt) throw new Error('no such quilt')
+    const done = quilt.archive_seq || 0
+    const waiting = Math.max(0, quilt.head_seq - done)
+    let ageMsOut = 0
+    if (waiting) { const [oldest] = await store.logRows(q, { after: done, limit: 1 }); if (oldest) ageMsOut = Math.max(0, now() - Number(oldest.at)) }
+    return { archive_seq: done, head_seq: quilt.head_seq, rows: waiting, age_ms: ageMsOut, alert: waiting > LAG_ROWS || ageMsOut > LAG_MS }
+  }
+
+  async function archiveHeld (q, { force = false } = {}) {
+    const segments = []
+    for (;;) {
+      const quilt = await store.getQuilt(q)
+      if (!quilt) throw new Error('no such quilt')
+      const done = quilt.archive_seq || 0
+      const waiting = quilt.head_seq - done
+      if (waiting <= 0) return { segments, archive_seq: done }
+      let due = force || waiting >= rows
+      if (!due) {
+        const [oldest] = await store.logRows(q, { after: done, limit: 1 })
+        due = !!oldest && now() - Number(oldest.at) >= ageMs
+      }
+      if (!due) return { segments, archive_seq: done }
+      try {
+        segments.push(await writeOne(q, quilt, done + Math.min(rows, waiting)))
+      } catch (err) {
+        if (err.code === 'archive_moved') continue // another archiver advanced it: read again
+        throw err
+      }
+    }
+  }
+
+  function maybe (q) {
+    if (running.has(q)) return running.get(q)
+    const p = archive(q).catch(() => null).then(() => lag(q)).then((l) => {
+      // The lag alert is logged once when it starts and once when it clears.
+      if (l.alert && !alerting.has(q)) { alerting.add(q); log(`seam: archiver lag alert on quilt ${q}: ${l.rows} rows, oldest ${Math.round(l.age_ms / 1000)} s`) }
+      if (!l.alert && alerting.delete(q)) log(`seam: archiver lag cleared on quilt ${q}`)
+      return l
+    }).catch(() => null).finally(() => running.delete(q))
+    running.set(q, p)
+    return p
+  }
+
+  return { archive, maybe, lag }
+}
+
+/**
+ * Replay (03's table, for the rows segments carry): reads a quilt's segments from object storage
+ * alone, checks the chain end to end (each segment's hash, `prev`, and seq continuity from 1), and
+ * rebuilds the log, the commit rows (with hidden_seq and patch derived again) and every line's tip.
+ */
+export async function replaySegments (objects, q, { journal = false, recover = false } = {}) {
+  const names = await objects.listFiles(q, 'w')
+  const log = []
+  const commits = new Map()
+  const checkRuns = new Map()
+  const lines = new Map()
+  let prev = ZERO
+  let at = 0
+  for (const name of names) {
+    const { trailer, records } = decodeSegment(await objects.readFile(q, 'w', name))
+    if (trailer.quilt_id !== q) throw new Error(`segment ${name} belongs to quilt ${trailer.quilt_id}`)
+    if (trailer.prev !== prev) throw new Error(`segment ${name} does not follow the one before it (chain broken)`)
+    if (trailer.from_seq !== at + 1) throw new Error(`segment ${name} starts at ${trailer.from_seq}, expected ${at + 1} (a gap)`)
+    if (name !== segmentName(trailer.from_seq, trailer.to_seq)) throw new Error(`segment ${name} says it holds ${trailer.from_seq}-${trailer.to_seq}`)
+    for (const r of records) {
+      if (r.t === 'commit') { commits.set(r.row.id, { ...r.row, hidden_seq: null }); continue }
+      if (r.t === 'check_run') { checkRuns.set(r.row.run_key, r.row); continue }
+      const row = r.row
+      if (row.seq !== at + 1) throw new Error(`segment ${name}: row ${row.seq} out of order`)
+      at = row.seq
+      log.push(row)
+    }
+    if (at !== trailer.to_seq || log.length < trailer.row_count) throw new Error(`segment ${name} ends at ${at}, its trailer says ${trailer.to_seq}`)
+    prev = trailer.blake3
+  }
+  // Then the tip journal (journal.js): merge, move, square and line rows past the last segment.
+  // The log it leaves has gaps where `commit` rows were (15's recover-gap fills those).
+  let journalSeq = at
+  if (journal) {
+    for (const row of await readJournal(objects, q, at)) { log.push(row); journalSeq = row.seq }
+  }
+  for (const c of commits.values()) {
+    const p = c.predecessor && commits.get(c.predecessor)
+    if (p && p.hidden_seq == null) p.hidden_seq = c.seq
+  }
+  const squares = new Map()
+  for (const row of log) {
+    // The last `square` row per id names its state (03's replay table; `head` comes from its commits).
+    if (row.kind === 'square' && row.square) {
+      const sq = squares.get(row.square) || { id: row.square }
+      if (row.line) sq.line = row.line
+      if (row.payload?.title) sq.title = row.payload.title
+      if (row.payload?.op) sq.last_op = row.payload.op
+      if (row.payload?.op === 'open') { sq.opened_by = row.actor; sq.base = row.payload.base || null }
+      if (row.payload?.state) sq.state = row.payload.state
+      else if (row.payload?.op === 'merged') sq.state = 'merged'
+      sq.seq = row.seq
+      squares.set(row.square, sq)
+      continue
+    }
+    // A line made from a commit, and a line frozen or unfrozen (policy rows naming the line).
+    if (row.kind === 'policy' && row.line && row.payload) {
+      const op = row.payload.op
+      if (op === 'line') lines.set(row.line, { name: row.line, tip: row.payload.tip || null, tip_seq: row.seq, patch_count: 0, frozen: false })
+      else if ((op === 'freeze' || op === 'unfreeze') && lines.has(row.line)) lines.get(row.line).frozen = op === 'freeze'
+      continue
+    }
+    if (row.kind !== 'merge') continue
+    const id = row.commit || row.to || row.commit_id
+    lines.set(row.line, { ...lines.get(row.line), name: row.line, tip: id, tip_seq: row.seq, patch_count: row.patch_no })
+    const c = commits.get(id)
+    if (c) { c.patch = { line: row.line, patch_no: row.patch_no }; if (row.snapshot_root) c.snapshot_root = row.snapshot_root }
+  }
+  // Then recover-gap (recover.js): commits past the last segment, from the packs alone.
+  const recovered = recover ? await recoverGap(objects, q, commits) : []
+  return { archive_seq: at, journal_seq: journalSeq, last_segment: prev === ZERO ? null : prev, log, commits, lines, squares, recovered, checkRuns }
+}