@tonoid/agent-loop 1.0.0

package/docs/cutover.md

@@ -0,0 +1,121 @@
+# Cutover
+
+The command list. The reasoning behind the order is in the README.
+
+Every phase is reversible. The bash script stays on disk and its cron line stays
+one `#` from restoration until the last phase has survived a week.
+
+## Phase 0: freeze what the old pipelines know
+
+```
+agent-loop check
+```
+
+It resolves `gh`, `git` and `herdr`, checks that `gh` is authenticated, warns
+when herdr's protocol number is not the tested one, and validates every
+discovered workspace. Give the existing bash directories a private git remote so
+they are recoverable independently of the box, and delete worktrees whose pull
+requests already closed: adopting a bash-era worktree is worth less than
+deleting it.
+
+## Phase 1: a shadow week
+
+One cron line, no `--live`, its own log:
+
+```cron
+*/2 * * * * PATH=$HOME/.bun/bin:$HOME/.local/bin:/usr/local/bin:/usr/bin:/bin flock -n ~/.agent-loop/tick.lock agent-loop tick >>~/.agent-loop/shadow.log 2>&1
+```
+
+Spell `PATH` out: cron's own does not carry `bun`, so the command dies in its
+shebang before the loop runs, and it does not carry `herdr` either, so a tick
+that starts still fails every pass that touches an agent.
+
+A tick without `--live` performs every read, refuses every write at the gate in
+`src/adapters/run.ts`, and leaves its own marks database alone as well, so a
+week of shadow ticks records nothing the loop did not do. The one thing it does
+write is a usage sample per account per tick in the global database.
+
+Two things the week does not buy, both following from the same fact that it
+spawns nothing. The router's worker rate is not measured during it: a sample
+needs at least one worker in flight over the interval, so the rate stays at
+`workerRateSeed` until the first live day, and the pacing model has no evidence
+behind it on the day it starts deciding. And because a dry tick's marks do not
+survive it, a routine that is due stays due on every tick of the week; the
+spawn pass keeps walking the jobs without `--live` for exactly that reason, so
+every job still reports, but the first one reports the same occurrence all
+week rather than a sequence of them.
+
+Read it back with
+
+```
+grep -E "WOULD|SKIP|IDLE|ERROR" ~/.agent-loop/shadow.log
+```
+
+and compare against the bash logs for the same minutes. Only the ticks where
+either side acted are worth reading. The criterion is a full week where the
+intended decisions match line for line.
+
+## Phase 2: the routines
+
+A routine's occurrence stamp is the one piece of state that is not derived from
+the outside world, so it is the one thing that has to be imported. Without it a
+routine re-runs an occurrence the old pipeline already finished, and anything
+with outbound side effects does that visibly.
+
+For each routine, record the occurrence that is running right now:
+
+```
+agent-loop adopt <job> --workspace <name>
+```
+
+For an older occurrence, name its key, which is the slot's date and time:
+
+```
+agent-loop adopt <job> 20260820-0910 --workspace <name>
+```
+
+Check the import, then check what the loop makes of it:
+
+```
+agent-loop adopt --list --workspace <name>
+agent-loop tick --workspace <name>
+```
+
+The spawn line for that job must read `IDLE <job>`, which is the loop saying the
+occurrence is already accounted for. Anything else on that line, a
+`WOULD spawn` or a `SKIP` naming an account or a cap, means the occurrence is
+still due and the stamp you wrote is not the one the loop computes. Keys are the
+slot as `<YYYYMMDD>-<HHMM>`, in the box's own timezone, and an occurrence runs
+from its slot until the next one begins, so the occurrence running at 08:00 with
+slots at 09:10 and 21:10 is yesterday's `21:10`.
+
+Then comment out the bash cron line and watch two occurrences.
+
+## Phase 3: the one live reviewer
+
+Its state is labels plus worktrees keyed by pull request, both derived, so there
+is nothing to import. Pause the phase in bash, and let this one run. Both are
+installed, and exactly one is unpaused.
+
+## Phase 4: the paused service
+
+From a clean slate. Let its remaining workers finish or remove them by hand, so
+the new system starts with no inherited worktrees.
+
+## Phase 5: the remaining build and review phases
+
+Same shape as phase 3, one job at a time.
+
+## Stopping
+
+```
+agent-loop pause <job> --workspace <name>     stop spawning that job
+agent-loop pause --workspace <name>           stop spawning anything here
+agent-loop resume <job> --workspace <name>
+```
+
+Pause takes effect on the next tick and needs no crontab edit. Sweep and monitor
+keep running while a job is paused, which is deliberate: the monitor is what
+takes a claim label off finished work, and a pause that froze it would
+manufacture claims that lie. To stop a workspace altogether, remove its path
+from `workspaces` in `~/.agent-loop/config.yml`.

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@tonoid/agent-loop",
+  "version": "1.0.0",
+  "description": "Schedules autonomous coding agents across provider accounts and runs them as herdr agents in herdr panes.",
+  "license": "MIT",
+  "author": "melalj <3869766+melalj@users.noreply.github.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tonoid/agent-loop.git"
+  },
+  "homepage": "https://github.com/tonoid/agent-loop#readme",
+  "bugs": {
+    "url": "https://github.com/tonoid/agent-loop/issues"
+  },
+  "keywords": [
+    "herdr",
+    "agent",
+    "claude-code",
+    "codex",
+    "cron",
+    "scheduler",
+    "git-worktree",
+    "automation"
+  ],
+  "type": "module",
+  "bin": {
+    "agent-loop": "./src/cli.ts"
+  },
+  "scripts": {
+    "test": "bun test",
+    "test:live": "AGENT_LOOP_LIVE_HERDR=1 bun test test/integration/herdr-live.test.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5"
+  },
+  "files": [
+    "src",
+    "briefs",
+    "docs/cutover.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/adapters/gh.ts

@@ -0,0 +1,77 @@
+import type { Runner } from "./run"
+import type { WorkItem, ItemState } from "../types"
+
+export interface ListArgs { repo: string; state: "open" | "all"; limit?: number; label?: string }
+export interface Gh {
+  issueList(a: ListArgs): Promise<WorkItem[]>
+  prList(a: ListArgs): Promise<WorkItem[]>
+  prView(repo: string, ref: string, fields: string[]): Promise<any>
+  label(repo: string, kind: "issue" | "pr", number: number, o: { add?: string[]; remove?: string[] }): Promise<void>
+  comment(repo: string, kind: "issue" | "pr", number: number, body: string): Promise<void>
+  labelsOf(repo: string, kind: "issue" | "pr", number: number): Promise<string[]>
+}
+
+// `gh issue list` rejects headRefName, so the two field sets differ.
+const PR_FIELDS = "number,title,state,headRefName,labels,url,createdAt"
+const ISSUE_FIELDS = "number,title,state,labels,url,createdAt"
+
+// `gh` defaults --limit to 30 and truncates silently past it, with no error
+// and no marker in the output. A caller that omits limit still needs every
+// claimed item, so we send a high explicit default rather than gh's default.
+const DEFAULT_LIMIT = 1000
+
+function toItem(prefix: "pr" | "issue", raw: any): WorkItem {
+  return {
+    id: `${prefix}:${raw.number}`,
+    number: raw.number,
+    title: raw.title ?? "",
+    state: (raw.state ?? "OPEN") as ItemState,
+    labels: (raw.labels ?? []).map((l: any) => l.name),
+    headRef: raw.headRefName,
+    url: raw.url,
+    createdAt: raw.createdAt,
+  }
+}
+
+// Two runners, not one. The read verbs take --json and are parsed; the write
+// verbs print the item's URL on success, so parsing their output as JSON
+// throws AFTER the write has already landed. That failure mode is the worst
+// available: the label is applied, the caller sees an error, and the item is
+// left claimed by a spawn that then rolls back.
+export function makeGh(run: Runner, runText: (argv: string[]) => Promise<string>): Gh {
+  const listArgv = (kind: "pr" | "issue", a: ListArgs) => {
+    const fields = kind === "pr" ? PR_FIELDS : ISSUE_FIELDS
+    const argv = ["gh", kind, "list", "--repo", a.repo, "--state", a.state, "--json", fields]
+    argv.push("--limit", String(a.limit ?? DEFAULT_LIMIT))
+    if (a.label) argv.push("--label", a.label)
+    return argv
+  }
+  return {
+    async issueList(a) {
+      const raw = await run(listArgv("issue", a))
+      return (raw as any[]).map((r) => toItem("issue", r))
+    },
+    async prList(a) {
+      const raw = await run(listArgv("pr", a))
+      return (raw as any[]).map((r) => toItem("pr", r))
+    },
+    async prView(repo, ref, fields) {
+      return run(["gh", "pr", "view", ref, "--repo", repo, "--json", fields.join(",")])
+    },
+    async label(repo, kind, number, o) {
+      const argv = [kind, "edit", String(number), "--repo", repo]
+      if (o.add?.length) argv.push("--add-label", o.add.join(","))
+      if (o.remove?.length) argv.push("--remove-label", o.remove.join(","))
+      // Nothing to change is not an error, and an edit with neither flag is.
+      if (argv.length === 5) return
+      await runText(["gh", ...argv])
+    },
+    async comment(repo, kind, number, body) {
+      await runText(["gh", kind, "comment", String(number), "--repo", repo, "--body", body])
+    },
+    async labelsOf(repo, kind, number) {
+      const r = await run(["gh", kind, "view", String(number), "--repo", repo, "--json", "labels"])
+      return ((r as any)?.labels ?? []).map((l: any) => l.name)
+    },
+  }
+}

package/src/adapters/git.ts

@@ -0,0 +1,82 @@
+export interface Worktree { path: string; branch: string | null }
+export interface Git {
+  worktrees(): Promise<Worktree[]>
+  remoteSlug(): Promise<string>
+  lsRemote(pattern: string): Promise<string[]>
+  fetch(): Promise<void>
+  worktreeAdd(path: string, branch: string, base: string): Promise<void>
+  worktreeRemove(path: string): Promise<void>
+  branchDelete(branch: string): Promise<void>
+  remoteDelete(branch: string): Promise<void>
+}
+
+export function parseWorktrees(porcelain: string): Worktree[] {
+  const out: Worktree[] = []
+  let path: string | null = null
+  let branch: string | null = null
+  const flush = () => {
+    if (path !== null) out.push({ path, branch })
+    path = null
+    branch = null
+  }
+  for (const line of porcelain.split("\n")) {
+    if (line.startsWith("worktree ")) {
+      flush()
+      path = line.slice("worktree ".length)
+    } else if (line.startsWith("branch refs/heads/")) {
+      branch = line.slice("branch refs/heads/".length)
+    }
+  }
+  flush()
+  return out
+}
+
+// "owner/name" from any origin form: ssh, https, with or without .git. A job
+// names a local path, and `gh` wants a slug; deriving it beats configuring the
+// same repository twice and getting the two out of step.
+export function slugFromRemote(url: string): string {
+  const m = url.trim().replace(/\.git$/, "").match(/([^/:]+\/[^/]+)$/)
+  if (!m) throw new Error(`cannot read an owner/name out of origin "${url.trim()}"`)
+  return m[1]!
+}
+
+export function makeGit(runText: (argv: string[]) => Promise<string>, repo: string): Git {
+  return {
+    async worktrees() {
+      return parseWorktrees(await runText(["git", "-C", repo, "worktree", "list", "--porcelain"]))
+    },
+    async remoteSlug() {
+      return slugFromRemote(await runText(["git", "-C", repo, "remote", "get-url", "origin"]))
+    },
+    async lsRemote(pattern) {
+      const out = await runText(["git", "-C", repo, "ls-remote", "--heads", "origin", pattern])
+      const prefix = "refs/heads/"
+      return out
+        .split("\n")
+        .filter(Boolean)
+        .map((l) => {
+          const i = l.indexOf(prefix)
+          return i === -1 ? "" : l.slice(i + prefix.length)
+        })
+        .filter(Boolean)
+    },
+    async fetch() {
+      await runText(["git", "-C", repo, "fetch", "origin", "--prune"])
+    },
+    async worktreeAdd(path, branch, base) {
+      await runText(["git", "-C", repo, "worktree", "add", "-b", branch, path, base])
+    },
+    async worktreeRemove(path) {
+      // --force because a worker leaves build output behind and a worktree
+      // with untracked files is refused otherwise; the sweep has already
+      // established that this worktree is finished with.
+      await runText(["git", "-C", repo, "worktree", "remove", "--force", path])
+    },
+    async branchDelete(branch) {
+      await runText(["git", "-C", repo, "branch", "-D", branch])
+    },
+    async remoteDelete(branch) {
+      await runText(["git", "-C", repo, "push", "origin", "--delete", branch])
+    },
+  }
+}

package/src/adapters/herdr.ts

@@ -0,0 +1,121 @@
+import type { Runner } from "./run"
+import type { AgentView, AgentStatus } from "../types"
+
+export interface PaneView { cwd: string; paneId: string; tabId: string }
+export interface WorkspaceView { id: string; label: string }
+
+export interface TabCreateArgs {
+  workspaceId: string
+  cwd: string
+  label: string
+  env: Record<string, string>
+}
+
+export interface AgentStartArgs {
+  pane: string
+  kind: string
+  name: string
+  args: string[]
+}
+
+export interface Herdr {
+  agents(): Promise<AgentView[]>
+  panes(): Promise<PaneView[]>
+  protocol(): Promise<number>
+  workspaces(): Promise<WorkspaceView[]>
+  tabCreate(o: TabCreateArgs): Promise<void>
+  tabClose(tabId: string): Promise<void>
+  agentStart(o: AgentStartArgs): Promise<void>
+  agentPrompt(target: string, text: string, o?: { until?: string; timeoutMs?: number }): Promise<void>
+  agentSendKeys(target: string, keys: string[]): Promise<void>
+  agentRead(target: string, lines: number): Promise<string>
+  agentStatus(target: string): Promise<AgentStatus>
+  notify(title: string, body: string): Promise<void>
+}
+
+export type HerdrRead = Herdr
+
+// The herdr protocol this project was built and tested against. Section 9 of
+// the spec: check it, warn loudly on a mismatch, never refuse to run.
+export const TESTED_PROTOCOL = 19
+
+const KNOWN: AgentStatus[] = ["working", "blocked", "idle"]
+
+function toStatus(s: unknown): AgentStatus {
+  return KNOWN.includes(s as AgentStatus) ? (s as AgentStatus) : "missing"
+}
+
+export function makeHerdr(run: Runner): Herdr {
+  return {
+    async agents() {
+      const r = await run(["herdr", "agent", "list"])
+      return (r?.result?.agents ?? []).map((a: any) => ({
+        cwd: a.cwd,
+        status: toStatus(a.agent_status),
+        paneId: a.pane_id,
+      }))
+    },
+    async panes() {
+      const r = await run(["herdr", "pane", "list"])
+      return (r?.result?.panes ?? []).map((p: any) => ({
+        cwd: p.cwd,
+        paneId: p.pane_id,
+        tabId: p.tab_id,
+      }))
+    },
+    async protocol() {
+      const r = await run(["herdr", "api", "schema", "--json"])
+      return r?.protocol ?? r?.result?.protocol ?? -1
+    },
+    async workspaces() {
+      const r = await run(["herdr", "workspace", "list"])
+      return (r?.result?.workspaces ?? []).map((w: any) => ({
+        id: w.workspace_id,
+        label: w.label,
+      }))
+    },
+    async tabCreate(o) {
+      const argv = [
+        "herdr", "tab", "create",
+        "--workspace", o.workspaceId,
+        "--cwd", o.cwd,
+        "--label", o.label,
+      ]
+      // tab create is the only verb that accepts --env, and it is therefore
+      // the sole channel by which the router's account choice reaches a worker.
+      for (const [k, v] of Object.entries(o.env)) argv.push("--env", `${k}=${v}`)
+      argv.push("--no-focus")
+      await run(argv)
+    },
+    async tabClose(tabId) {
+      await run(["herdr", "tab", "close", tabId])
+    },
+    async agentStart(o) {
+      const argv = ["herdr", "agent", "start", o.name, "--kind", o.kind, "--pane", o.pane]
+      if (o.args.length > 0) argv.push("--", ...o.args)
+      await run(argv)
+    },
+    async agentPrompt(target, text, o) {
+      const argv = ["herdr", "agent", "prompt", target, text]
+      if (o?.until) argv.push("--wait", "--until", o.until)
+      if (o?.timeoutMs !== undefined) argv.push("--timeout", String(o.timeoutMs))
+      await run(argv)
+    },
+    async agentSendKeys(target, keys) {
+      await run(["herdr", "agent", "send-keys", target, ...keys])
+    },
+    async agentRead(target, lines) {
+      const r = await run([
+        "herdr", "agent", "read", target, "--source", "recent-unwrapped", "--lines", String(lines),
+      ])
+      return String(r?.result?.output ?? "")
+    },
+    async agentStatus(target) {
+      const r = await run(["herdr", "agent", "get", target])
+      return toStatus(r?.result?.agent?.agent_status)
+    },
+    async notify(title, body) {
+      await run(["herdr", "notification", "show", title, "--body", body, "--sound", "request"])
+    },
+  }
+}

package/src/adapters/run.ts

@@ -0,0 +1,64 @@
+export type Runner = (argv: string[]) => Promise<any>
+
+// Every read the loop performs, as an argv prefix. Git's "-C <repo>" is
+// stripped before matching, so only the verb matters here. Anything absent
+// from this list is a mutation as far as a dry run is concerned, including
+// commands nobody has thought of yet: refusing the unknown is what makes the
+// read-only claim hold when a later plan adds a verb and forgets this file.
+const READS: string[][] = [
+  ["gh", "auth", "status"],
+  ["gh", "issue", "list"],
+  ["gh", "pr", "list"],
+  ["gh", "pr", "view"],
+  ["gh", "issue", "view"],
+  ["gh", "api"],
+  ["git", "worktree", "list"],
+  ["git", "for-each-ref"],
+  ["git", "ls-remote"],
+  ["git", "remote", "get-url"],
+  ["herdr", "agent", "list"],
+  ["herdr", "agent", "read"],
+  ["herdr", "agent", "get"],
+  ["herdr", "pane", "list"],
+  ["herdr", "workspace", "list"],
+  ["herdr", "api", "schema"],
+]
+
+// `gh api` defaults to GET but switches to implicit POST when request parameters
+// are added via -f / -F / --input. Any explicit method flag also makes it a write.
+// The flag set covers both explicit methods and parameter flags that trigger POST.
+const GH_API_WRITE = new Set(["-X", "--method", "-f", "--raw-field", "-F", "--field", "--input"])
+
+function normalize(argv: string[]): string[] {
+  if (argv[0] === "git" && argv[1] === "-C") return ["git", ...argv.slice(3)]
+  return argv
+}
+
+export function assertReadOnly(argv: string[]): void {
+  const a = normalize(argv)
+  const allowed = READS.some((prefix) => prefix.every((word, i) => a[i] === word))
+  const ghApiWrite = a[0] === "gh" && a[1] === "api" && a.some((w) => GH_API_WRITE.has(w))
+  if (!allowed || ghApiWrite) {
+    throw new Error(`refusing to run "${argv.join(" ")}" without --live`)
+  }
+}
+
+async function spawnText(argv: string[]): Promise<string> {
+  const proc = Bun.spawn(argv, { stdout: "pipe", stderr: "pipe" })
+  const [out, err, code] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ])
+  if (code !== 0) throw new Error(`${argv[0]} exited ${code}: ${err.trim()}`)
+  return out
+}
+
+export function makeRunners(live: boolean) {
+  const runText = async (argv: string[]): Promise<string> => {
+    if (!live) assertReadOnly(argv)
+    return spawnText(argv)
+  }
+  const runJson = async <T,>(argv: string[]): Promise<T> => JSON.parse(await runText(argv)) as T
+  return { runText, runJson }
+}

package/src/adopt.ts

@@ -0,0 +1,47 @@
+import type { Ctx, Job, Marks, WorkItem } from "./types"
+import type { MarkRow } from "./state"
+
+// A routine's key() falls back to the occurrence due right now when the item
+// carries no key of its own, which is exactly the stamp a cutover imports.
+const BLANK: WorkItem = { id: "", number: 0, title: "", state: "OPEN", labels: [] }
+
+// The cutover's one import path (docs/cutover.md phase 2). A routine whose
+// done-marker lived in a file re-runs on a fresh state directory, and for
+// anything with outbound side effects that is not an acceptable cutover risk,
+// so the stamp the loop would have written gets written by hand instead.
+//
+// The marks handle is passed rather than taken from the context because a
+// context built without --live has a dryMarks overlay in ctx.marks, and this
+// command's whole purpose is to write.
+export async function adopt(
+  ctx: Ctx,
+  marks: Marks,
+  job: Job,
+  key?: string,
+): Promise<{ key: string; already: boolean }> {
+  const k = key ?? (await currentKey(ctx, job))
+  const already = marks.has(job.name, k, "spawned")
+  if (!already) marks.set(job.name, k, "spawned")
+  return { key: k, already }
+}
+
+async function currentKey(ctx: Ctx, job: Job): Promise<string> {
+  // Every other kind keys on an item, so there is no key it would use right
+  // now. Guessing one would stamp a real issue or pull request as done.
+  if (job.workload !== "routine") {
+    throw new Error(
+      `job "${job.name}" is a ${job.workload}, which keys on an item: name the key to adopt`,
+    )
+  }
+  const k = await job.key(ctx, BLANK)
+  if (!k) throw new Error(`job "${job.name}" has no occurrence due right now`)
+  return k
+}
+
+export function renderMarks(rows: MarkRow[], now: Date): string[] {
+  if (!rows.length) return ["no marks recorded"]
+  return rows.map((r) => {
+    const minutes = Math.max(0, Math.round((now.getTime() - r.at) / 60000))
+    return `${r.job} ${r.key} ${r.mark} ${minutes}m ago`
+  })
+}

package/src/brief.ts

@@ -0,0 +1,124 @@
+import { existsSync, readFileSync } from "node:fs"
+import type { Ctx, Job, WorkItem } from "./types"
+import { ghRepo } from "./engine/item"
+import { worktreePath, branchName } from "./engine/naming"
+
+export type Vars = Record<string, string | number>
+
+export interface BriefLayers {
+  // A role file under briefs/, named the way job.yml names it: "default/build".
+  extends?: string
+  // Shipped opt-in sections, by bare name: briefs/default/<name>.optional.md.
+  optional?: string[]
+  // The user's own prose, already an absolute path by the time the loader is done.
+  append?: string
+}
+
+// Beside the sources, so a checkout carries its briefs and no install step
+// copies them anywhere.
+export const BRIEFS_DIR = `${import.meta.dir}/../briefs`
+
+// Two segments of the safe alphabet. A name reaches the filesystem, so this is
+// the whole defence against "../../etc/passwd" arriving from a job.yml.
+const BRIEF_NAME = /^[a-z0-9-]+\/[a-z0-9-]+$/
+
+export function briefPath(name: string): string {
+  if (!BRIEF_NAME.test(name)) {
+    throw new Error(`brief.extends "${name}" must look like default/build`)
+  }
+  const path = `${BRIEFS_DIR}/${name}.md`
+  if (!existsSync(path)) throw new Error(`brief.extends "${name}" names no shipped brief`)
+  return path
+}
+
+function optionalPath(name: string): string {
+  if (!/^[a-z0-9-]+$/.test(name)) throw new Error(`optional brief section "${name}" is not a name`)
+  const path = `${BRIEFS_DIR}/default/${name}.optional.md`
+  if (!existsSync(path)) throw new Error(`optional brief section "${name}" names no shipped file`)
+  return path
+}
+
+// Append, never replace: the fences in core.md are the reason an unattended
+// worker is safe, and a user who could replace them would ship an agent that
+// force-pushes (spec 8).
+export function loadBrief(l: BriefLayers): string {
+  const parts = [readFileSync(`${BRIEFS_DIR}/default/core.md`, "utf8")]
+  if (l.extends) parts.push(readFileSync(briefPath(l.extends), "utf8"))
+  for (const name of l.optional ?? []) parts.push(readFileSync(optionalPath(name), "utf8"))
+  if (l.append) {
+    if (!existsSync(l.append)) throw new Error(`brief.append "${l.append}" does not exist`)
+    parts.push(readFileSync(l.append, "utf8"))
+  }
+  return parts.map((p) => p.trim()).join("\n\n") + "\n"
+}
+
+const VAR = /\{\{([a-zA-Z0-9_.]+)\}\}/g
+
+// Plain substitution and nothing else. A brief is prose, and a template engine
+// that can branch is a dependency and a second language to debug at 3am.
+export function render(template: string, vars: Vars): string {
+  return template.replace(VAR, (whole, name: string) => {
+    const v = vars[name]
+    return v === undefined ? whole : String(v)
+  })
+}
+
+export function unresolved(text: string): string[] {
+  return [...text.matchAll(VAR)].map((m) => m[1]!)
+}
+
+export async function briefVars(
+  ctx: Ctx,
+  job: Job,
+  item: WorkItem,
+  key: string,
+  extra: Vars = {},
+): Promise<Vars> {
+  const labels = ctx.workspace.naming.labels
+  // The account is what the PR body's "built-by:" line carries, which is what
+  // makes distinctFrom (spec 6.4) derive from the outside world. The router has
+  // already reserved the row by the time a brief is rendered.
+  const account = ctx.global.accountFor(ctx.workspace.name, job.name, key) ?? "unknown"
+  return {
+    item: `#${item.number}`,
+    number: item.number,
+    title: item.title,
+    itemUrl: item.url ?? "",
+    key,
+    worktree: worktreePath(ctx.workspace.worktreeBase, job.name, key),
+    branch: branchName(job.name, key),
+    headRef: item.headRef ?? "",
+    base: job.base ? await job.base(ctx, item) : "",
+    attempt: job.attempt ? await job.attempt(ctx, item) : 1,
+    attemptCap: 0,
+    repoSlug: ghRepo(item) ?? "",
+    journal: ctx.workspace.journalPath,
+    mergeMethod: ctx.workspace.naming.mergeMethod,
+    // The kind that merges writes this whole step, because the template has no
+    // conditionals. The default is the fail-safe direction: a job that renders
+    // a merge step without saying how to merge is not told to merge.
+    mergeInstruction: "Do not merge. The merge is not yours to make, so stop here and say so.",
+    assetBranch: "assets",
+    "labels.claim": labels.claim,
+    "labels.failed": labels.failed,
+    "labels.park": labels.park,
+    filingBudget: 0,
+    openQueue: 0,
+    dedupeBy: "path",
+    account,
+    commentPrefix: "",
+    passLabel: "",
+    ...extra,
+  }
+}
+
+export async function renderBrief(
+  ctx: Ctx,
+  job: Job,
+  item: WorkItem,
+  key: string,
+  layers: BriefLayers,
+  extra: Vars = {},
+): Promise<string> {
+  return render(loadBrief(layers), await briefVars(ctx, job, item, key, extra))
+}