create-open-autonomy 2.1.0

package/template/container/README.md

@@ -0,0 +1,45 @@
+# Running the agent
+
+Three containers in one VM, none holding a secret that matters:
+
+- **agent** — stock Hermes at the pinned tag (`hermes.pin`), with the project checkout at `/work/project`
+  and the home volume at `/opt/data`, seeded from `hermes/` and re-synced from the repository on every start.
+- **valve** — holds the developer's key (spend + narrate). The agent's model calls and the reporter's narration
+  go through it; key management and admin routes never do. It re-reads the key file when it changes, so a
+  rotated key needs no restart.
+- **valve-pay** — holds the treasurer's key, the only one with the `pay` scope. The treasurer profile alone is
+  pointed at it, so a purchase can only be made by the treasurer, within the owner's bounds.
+- **reporter** — keyless. Reads the agent's sessions through supercode and publishes them to the project's
+  page through the valve, as they happen.
+
+Every session's turns are published, so the agent's environment holds nothing whose leak matters:
+its `.env` says `OPEN_AUTONOMY_KEY=valve`; pushes sign through an ssh-agent forwarded from the host holding
+one repository-scoped deploy key; delivery uses at most a Discord bot token, which can only post as the bot.
+
+## The host
+
+`bun .open-autonomy/setup.ts` does the steps below, idempotently, and says what it cannot do and what to run
+next; the world's stack step calls the same file. By hand:
+
+- `~/.config/open-autonomy/agent.env` — the developer's key, from `bun .open-autonomy/mint-key.ts`;
+  `~/.config/open-autonomy/treasurer.env` — the treasurer's, from `bun .open-autonomy/mint-key.ts --scopes
+  spend,narrate,pay --out ~/.config/open-autonomy/treasurer.env`. Rotate it with
+  `bun .open-autonomy/mint-key.ts --rotate`: the valve takes the new key from the file without a restart, and its
+  `/healthz` (and its log, and the reporter's) say when the key expires; both warn inside fourteen days.
+- An ssh-agent holding only the deploy key, forwarded into the Docker host (on macOS with colima:
+  `SSH_AUTH_SOCK=~/.config/open-autonomy/agent.sock colima start <profile> --ssh-agent`).
+- The pinned Hermes image: `sh container/build-hermes.sh` builds it from `hermes.pin`.
+
+Then the two volumes, once: `oa-home` from your `hermes/` (with a `.env` naming
+`OPEN_AUTONOMY_BASE_URL=http://valve:8787/v1`, `OPEN_AUTONOMY_KEY=valve`, and the Discord token if any) and
+`oa-repo`, a clone made with the deploy key. Then:
+
+```bash
+AGENT_SECRETS=~/.config/open-autonomy docker compose -f container/compose.yml up -d --build
+docker exec -u $UID oa-agent hermes cron list            # the schedule: the PM, hourly, seeded from hermes/cron/jobs.seed.json
+docker exec -u $UID oa-agent hermes kanban create 'A task' --body '- its acceptance line' --assignee default --workspace dir:/work/project --skill develop   # file work
+docker exec -u $UID oa-agent hermes kanban list                  # the board: the task, its lane, its attempts
+docker logs -f oa-reporter                               # what is being published
+```
+
+The kit owns this directory; `create-open-autonomy upgrade .` brings it forward.

package/template/container/build-hermes.sh

@@ -0,0 +1,21 @@
+#!/bin/sh
+# Build the pinned Hermes image the agent runs on (container/hermes.pin). Clones the tag into a
+# temporary directory — this repository never vendors Hermes — verifies the commit, and builds
+# `hermes-agent:<tag>` in the current Docker context. Takes ~10 minutes the first time.
+set -eu
+here=$(cd "$(dirname "$0")" && pwd)
+. "$here/hermes.pin"
+image="hermes-agent:$HERMES_TAG"
+if [ "${FORCE:-}" != "1" ] && docker image inspect "$image" >/dev/null 2>&1; then
+  echo "$image already built (FORCE=1 to rebuild)"
+  exit 0
+fi
+work=$(mktemp -d)
+trap 'rm -rf "$work"' EXIT
+git clone -q --depth 1 --branch "$HERMES_TAG" "$HERMES_REPO" "$work/hermes"
+have=$(git -C "$work/hermes" rev-parse HEAD)
+[ "$have" = "$HERMES_COMMIT" ] || { echo "hermes.pin: $HERMES_TAG is $have, not the pinned $HERMES_COMMIT" >&2; exit 1; }
+# The upstream Dockerfile uses a symbolic --chmod, which needs a Dockerfile frontend newer than the
+# daemon's built-in one.
+docker build --build-arg BUILDKIT_SYNTAX=docker/dockerfile:1.17 -t "$image" "$work/hermes"
+echo "built $image ($HERMES_COMMIT)"

package/template/container/compose.yml

@@ -0,0 +1,99 @@
+# The project's agent, as it runs: three containers in one VM, none holding a secret that matters.
+#   agent      stock Hermes (the gateway: the schedule, and Discord when configured) with the project checkout;
+#              two profiles, the developer and the treasurer
+#   valve      holds the developer's key (spend + narrate): the model routes and the narration routes
+#   valve-pay  holds the treasurer's key (spend + narrate + pay): the same routes and the rails; only the
+#              treasurer profile is pointed at it
+#   reporter   keyless; reads the agent's sessions through supercode and publishes them through the valve
+# The home and the checkout live in Docker volumes: SQLite over a host bind mount is a bus error waiting
+# to happen, and nothing on the host needs them. Inspect with `docker exec`.
+#
+#   AGENT_SECRETS=~/.config/open-autonomy docker compose -f container/compose.yml up -d --build
+services:
+  valve:
+    build:
+      context: ..
+      dockerfile: container/Dockerfile.valve
+    image: __PROJECT__-valve:local
+    container_name: oa-valve
+    restart: unless-stopped
+    environment:
+      - AGENT_ENV_FILE=/secrets/agent.env
+    volumes:
+      - ${AGENT_SECRETS:-~/.config/open-autonomy}/agent.env:/secrets/agent.env:ro
+    networks: [agent]
+  valve-pay:
+    build:
+      context: ..
+      dockerfile: container/Dockerfile.valve
+    image: __PROJECT__-valve:local
+    container_name: oa-valve-pay
+    restart: unless-stopped
+    environment:
+      - AGENT_ENV_FILE=/secrets/treasurer.env
+    volumes:
+      - ${AGENT_SECRETS:-~/.config/open-autonomy}/treasurer.env:/secrets/treasurer.env:ro
+    networks: [agent]
+  # The committed home (SOUL, skills, config, the schedule seed) into the volume before the gateway starts:
+  # hermes/ in the repository is the source of truth for what the agent IS; the volume only holds what the
+  # agent has since done.
+  home-sync:
+    image: alpine:3
+    container_name: oa-home-sync
+    restart: "no"
+    command: ["sh", "-c", "cd /repo/hermes && find . -type f ! -name '.env' -exec cp -a --parents {} /opt/data/ \\; && chown -R ${AGENT_UID:-501}:${AGENT_GID:-20} /opt/data && echo 'home synced from the repository'"]
+    volumes:
+      - oa-home:/opt/data
+      - oa-repo:/repo:ro
+  agent:
+    build:
+      context: ..
+      dockerfile: container/Dockerfile
+      args:
+        HERMES_IMAGE: ${HERMES_IMAGE:-hermes-agent:v2026.8.31} # container/build-hermes.sh builds it
+    image: __PROJECT__-agent:local
+    container_name: oa-agent
+    restart: unless-stopped
+    depends_on:
+      valve: { condition: service_started }
+      home-sync: { condition: service_completed_successfully }
+    command: ["gateway", "run"]
+    environment:
+      # The host user's ids: the forwarded ssh-agent socket is theirs.
+      - HERMES_UID=${AGENT_UID:-501}
+      - HERMES_GID=${AGENT_GID:-20}
+      - SSH_AUTH_SOCK=/ssh-agent
+      - GIT_SSH_COMMAND=ssh -o StrictHostKeyChecking=accept-new
+    volumes:
+      - oa-home:/opt/data
+      - oa-repo:/work/project
+      - /run/host-services/ssh-auth.sock:/ssh-agent
+    networks: [agent]
+  reporter:
+    build:
+      context: ..
+      dockerfile: container/Dockerfile.reporter
+    image: __PROJECT__-reporter:local
+    container_name: oa-reporter
+    restart: unless-stopped
+    # The agent's own ids: the home it reads and the checkout it keeps its cursor in are the agent's.
+    user: "${AGENT_UID:-501}:${AGENT_GID:-20}"
+    depends_on:
+      valve: { condition: service_started }
+      agent: { condition: service_started }
+    environment:
+      - OPEN_AUTONOMY_BASE_URL=http://valve:8787/v1
+      - HERMES_HOME=/opt/data
+    volumes:
+      - oa-home:/opt/data:ro
+      - oa-repo:/work/project
+    networks: [agent]
+volumes:
+  oa-home:
+    name: oa-home
+    external: true # seeded once from hermes/ (container/README.md)
+  oa-repo:
+    name: oa-repo
+    external: true # the agent's clone
+networks:
+  agent: {}

package/template/container/hermes.pin

@@ -0,0 +1,6 @@
+# The Hermes the agent runs, pinned so the image is reproducible from a clean machine.
+# container/build-hermes.sh clones this exact tag and builds `hermes-agent:<tag>`, which
+# container/Dockerfile builds on. Bump both lines together, rebuild, and prove a run in the world.
+HERMES_REPO=https://github.com/NousResearch/hermes-agent.git
+HERMES_TAG=v2026.8.31
+HERMES_COMMIT=29112bef099274229cadff79cdff7bf7b99c4b77

package/template/container/key-valve.ts

@@ -0,0 +1,73 @@
+#!/usr/bin/env bun
+// The key valve: the project's key lives here and nowhere the agent or the reporter can read. Both point
+// at this process (OPEN_AUTONOMY_BASE_URL=http://valve:8787/v1, any dummy key) and it forwards to the
+// platform with the real bearer. Only the model routes and the narration route pass; key management and
+// admin routes never do, so a rotated key is never a key the agent could read.
+//
+//   AGENT_ENV_FILE=/secrets/agent.env bun key-valve.ts [--port 8787]
+//   (a KEY=value file, re-read when it changes: a rotated key is picked up without a restart)
+import { existsSync, readFileSync, statSync } from 'node:fs';
+
+const envFile = process.env.AGENT_ENV_FILE;
+let cached: { at: number; env: Record<string, string> } = { at: 0, env: {} };
+function keyEnv(): Record<string, string> {
+  if (process.env.OPEN_AUTONOMY_KEY) return { OPEN_AUTONOMY_KEY: process.env.OPEN_AUTONOMY_KEY, OPEN_AUTONOMY_BASE_URL: process.env.OPEN_AUTONOMY_BASE_URL ?? '' };
+  if (!envFile || !existsSync(envFile)) return {};
+  const at = statSync(envFile).mtimeMs;
+  if (at !== cached.at) {
+    const env: Record<string, string> = {};
+    for (const line of readFileSync(envFile, 'utf8').split('\n')) { const m = /^([A-Z_]+)=(.*)$/.exec(line.trim()); if (m) env[m[1]] = m[2]; }
+    cached = { at, env };
+    announce(env.OPEN_AUTONOMY_KEY);
+  }
+  return cached.env;
+}
+// The key says when it expires (its claims are readable; only the signature is not). Announced whenever the
+// file changes, warned inside fourteen days, and answered on /healthz so the reporter can log it too.
+function expiry(token: string | undefined): { kid: string; account: string; exp: string; days: number } | undefined {
+  try {
+    const claims = JSON.parse(Buffer.from((token ?? '').split('.')[0], 'base64url').toString('utf8')) as { kid?: string; account?: string; exp?: string };
+    if (!claims.exp) return undefined;
+    return { kid: claims.kid ?? '?', account: claims.account ?? '?', exp: claims.exp, days: Math.floor((Date.parse(claims.exp) - Date.now()) / 86_400_000) };
+  } catch { return undefined; }
+}
+const status = (): string => { const e = expiry(key()); return e ? `key ${e.kid} for ${e.account} expires ${e.exp} (${e.days} day${e.days === 1 ? '' : 's'})${e.days < 14 ? ' — rotate it: bun .open-autonomy/mint-key.ts --rotate' : ''}` : 'no key yet'; };
+function announce(token: string | undefined): void {
+  const e = expiry(token);
+  console.log(`key-valve: ${e ? status() : 'no readable key in the key file'}`);
+  if (e && e.days < 14) console.warn(`key-valve: WARNING the key expires in ${e.days} day${e.days === 1 ? '' : 's'}`);
+}
+const base = (): string => (keyEnv().OPEN_AUTONOMY_BASE_URL || 'https://open-autonomy.org/v1').replace(/\/$/, '');
+const key = (): string | undefined => keyEnv().OPEN_AUTONOMY_KEY;
+const portArg = process.argv.indexOf('--port');
+const port = Number((portArg >= 0 ? process.argv[portArg + 1] : undefined) || process.env.PORT || 8787);
+// The model routes, the narration routes (the stream and the roadmap), and the two other rails (a card, a partner charge): the platform
+// bounds each rail by the owner's config, and every settlement lands on the public audit trail.
+const FORWARDED = new Set(['/v1/chat/completions', '/v1/messages', '/v1/responses', '/v1/models', '/v1/agent/events', '/v1/agent/roadmap', '/v1/rails/card', '/v1/rails/partner']);
+// Public reads the reporter needs to resume where the platform is (its own account's sessions).
+const isPublicRead = (path: string, method: string) => method === 'GET' && /^\/v1\/accounts\/[^/]+\/(sessions|items)(\/|$)/.test(path);
+
+Bun.serve({
+  hostname: '0.0.0.0',
+  port,
+  idleTimeout: 255,
+  async fetch(req) {
+    const url = new URL(req.url);
+    if (url.pathname === '/healthz') return new Response(key() ? `ok · ${status()}` : 'no key yet');
+    if (!FORWARDED.has(url.pathname) && !isPublicRead(url.pathname, req.method)) return Response.json({ error: { code: 'not_forwarded', message: 'the valve forwards the model routes, the narration route, the rails and public reads of this account only' } }, { status: 403 });
+    const bearer = key();
+    if (!bearer) return Response.json({ error: { code: 'no_key', message: 'the valve has no key yet' } }, { status: 503 });
+    // A clean request: the body buffered (one honest Content-Length), only the headers that carry meaning.
+    const headers = new Headers();
+    for (const h of ['content-type', 'accept', 'anthropic-version', 'anthropic-beta', 'last-event-id']) { const v = req.headers.get(h); if (v) headers.set(h, v); }
+    headers.set('authorization', `Bearer ${bearer}`);
+    headers.set('user-agent', 'open-autonomy-key-valve');
+    const body = req.method === 'GET' || req.method === 'HEAD' ? undefined : await req.arrayBuffer();
+    const upstream = await fetch(`${base()}${url.pathname.replace(/^\/v1/, '')}${url.search}`, { method: req.method, headers, body });
+    const out = new Headers(upstream.headers);
+    out.delete('content-encoding');
+    out.delete('content-length');
+    return new Response(upstream.body, { status: upstream.status, headers: out });
+  },
+});
+console.log(`key-valve: forwarding ${[...FORWARDED].join(', ')} → ${base()} on :${port}`);

package/template/hermes/README.md

@@ -0,0 +1,19 @@
+# This project's agent
+
+This directory is a complete Hermes home (`HERMES_HOME`), from the Open Autonomy Hermes kit. Everything the
+agent is lives here and is committed: `SOUL.md` (identity), `skills/` (the two things it does beyond what Hermes
+brings: `develop`, `pm`), `kanban.seed.json` (the board's first tasks, in order; one with a `held` reason is filed parked, the owner's to release with `hermes kanban unblock`), `cron/jobs.seed.json` (its one job: the
+PM, hourly), `config.yaml` (which model, through the platform; a worker takes it at dispatch, so a model change
+never strands anything), `hooks/` (the seed: the schedule and the board, on every boot, idempotent). Its runtime
+state (sessions, logs, caches, `.env`, the board's database) is git-ignored.
+
+The agent's model calls go through the Open Autonomy platform on the project's key, so every call is metered
+to this project's account and paid for by its patrons. The board is the roadmap: the owner files tasks
+(`hermes kanban create`), the gateway's dispatcher pulls them down in order and runs each as a worker session
+that builds it and lands it on an `agent/<task id>` branch, the review lane (Hermes's own) verifies the handoff
+against `CONSTITUTION.md` and `CONTRIBUTING.md` in a session of its own, and once an hour the PM job reads the whole board and unsticks what is
+stuck. The reporter beside it (`.open-autonomy/reporter.ts`) publishes the board, every session, the agent's setup,
+and the project's documents (`CONSTITUTION.md` as what it is, `CHANGELOG.md` as what shipped) to the project's
+page as they happen. The platform reads none of these files itself.
+
+How it runs, and how to run it yourself: `container/README.md`.

package/template/hermes/SOUL.md

@@ -0,0 +1,7 @@
+You are this project's agent: the checked-in Hermes agent that builds the project you run in, month after month, on a token budget its sponsors fund through Open Autonomy. Your home is the repository you run in. Everything you are is readable there: this file, your two skills, your one scheduled job.
+
+The board is the roadmap. The owner files tasks on it; your dispatcher pulls them down in order and runs each as a worker session (the develop skill), the review lane verifies every handoff, and once an hour you look at the whole board and unstick what is stuck (the pm skill). When you review, the bar is two documents: `CONSTITUTION.md`, whose invariants no change may violate and whose out-of-scope no change may enter, and `CONTRIBUTING.md`, which the diff is held to. Every acceptance line made true and verified, and nothing in the diff that no line asked for, tests included. Approve in one paragraph naming what you checked; otherwise send it back naming each failing line. You finish things: a task is done when its acceptance lines are true in the running system, not when code exists. You never invent tasks; filing is the owner's job.
+
+You spend sponsors' money. Every model call you make is metered to this project's account and shown in public. Be economical: read before you write, run the check once, and stop when the work is verified. Do not loop on a failure you cannot explain; say what you found and block the task with what is missing.
+
+Be direct. Report what changed, what is verified, and what is left. No filler, no narration of tool calls, no restating the ask.

package/template/hermes/config.yaml

@@ -0,0 +1,32 @@
+# The project agent's Hermes configuration. The model is this project's choice (runtime config, seeded by
+# the kit, never checked by it). Secrets live in hermes/.env (git-ignored):
+#   OPEN_AUTONOMY_BASE_URL / OPEN_AUTONOMY_KEY  — inside the stack, the key valve's address and a dummy
+#   DISCORD_BOT_TOKEN / DISCORD_HOME_CHANNEL    — optional Discord delivery
+model:
+  default: zai/glm-5.3-flash
+  provider: custom
+  base_url: ${OPEN_AUTONOMY_BASE_URL}
+  api_key: ${OPEN_AUTONOMY_KEY}
+  api_mode: chat_completions
+
+terminal:
+  backend: local
+  timeout: 300
+
+# Everything the agent is must be readable in the repository, so it carries no private memory between runs.
+memory:
+  memory_enabled: false
+  user_profile_enabled: false
+
+compression:
+  enabled: true
+  threshold: 0.50
+
+agent:
+  max_turns: 80
+
+# The board (Hermes Kanban) the schedule files roadmap items on. Its dispatcher runs inside the gateway and
+# the review lane verifies every handoff; the interval is how soon a filed task is picked up.
+kanban:
+  dispatch_interval_seconds: 15
+  review_dispatch: true

package/template/hermes/cron/jobs.seed.json

@@ -0,0 +1,12 @@
+{
+  "jobs": [
+    {
+      "name": "pm",
+      "prompt": "You are this project's PM for the hour. Run the pm skill: read the board, unstick what is stuck, report.",
+      "schedule": "every 60m",
+      "skills": ["pm"],
+      "deliver": "discord",
+      "workdir": "/work/project"
+    }
+  ]
+}

package/template/hermes/hooks/seed/HOOK.yaml

@@ -0,0 +1,4 @@
+name: seed
+description: Seed the schedule from cron/jobs.seed.json and the board from kanban.seed.json on gateway startup
+events:
+  - gateway:startup

package/template/hermes/hooks/seed/handler.py

@@ -0,0 +1,220 @@
+"""Seed the schedule and the board from the committed seeds on gateway startup.
+
+Two seeds, both in the agent's home: cron/jobs.seed.json (the schedule) and kanban.seed.json (the board's
+starting tasks, in order, each waiting on the one before it). Both are idempotent: a job is matched by name, a
+task by its idempotency key `seed:<key>`, so a boot never files twice and the owner's own tasks are untouched.
+
+The Open Autonomy repository commits the schedule definition in
+hermes/cron/jobs.seed.json (byte-stable) and git-ignores the runtime store
+hermes/cron/jobs.json, which Hermes rewrites on every tick with next_run_at /
+last_run_at / fire_claim etc. This hook reconciles the runtime store to the
+seed on every gateway boot so the committed definition stays the source of
+truth and no scheduler run-state ever churns the commit.
+
+Every seeded job is pinned to the provider and model hermes/config.yaml names,
+at creation and again on every boot the config moved: an unpinned job snapshots
+the global model when created and Hermes's drift guard skips its fires once the
+owner changes the model, stranding the schedule. Pinned, the job runs on the
+config's model, and the next boot after a change re-pins it.
+
+Idempotent: it only creates jobs that are in the seed and missing from the
+live store (matched by name). It never deletes, pauses, or edits existing
+jobs, so runtime state (completed runs, next_run_at) is preserved across
+restarts and an operator can still add jobs by hand without the seed
+clobbering them.
+"""
+
+import json
+import logging
+import re
+import time
+from pathlib import Path
+
+logger = logging.getLogger("hooks.seed")
+
+
+def _hermes_home() -> Path:
+    import os
+    return Path(os.environ.get("HERMES_HOME") or Path.home() / ".hermes")
+
+
+# A seed may name a delivery platform the project has not configured (the template says `discord`; Discord is
+# optional). Hermes blocks such a job before any model call, so the job is created delivering `local` instead —
+# the run still happens and the platform's receipts remain the record — and the fallback is logged. Platforms
+# are matched by the credential their gateway needs; anything else passes through untouched.
+_PLATFORM_CREDENTIALS = {
+    "discord": ("DISCORD_BOT_TOKEN",),
+    "telegram": ("TELEGRAM_BOT_TOKEN",),
+    "slack": ("SLACK_BOT_TOKEN",),
+}
+
+
+def _configured(var: str) -> bool:
+    import os
+    if os.environ.get(var):
+        return True
+    env_file = _hermes_home() / ".env"
+    try:
+        for line in env_file.read_text(encoding="utf-8").splitlines():
+            key, _, value = line.strip().partition("=")
+            if key == var and value.strip().strip("'\""):
+                return True
+    except OSError:
+        pass
+    return False
+
+
+def _deliver_target(name: str, deliver) -> object:
+    platform = str(deliver).strip().lower() if isinstance(deliver, str) else ""
+    needs = _PLATFORM_CREDENTIALS.get(platform)
+    if not needs or any(_configured(v) for v in needs):
+        return deliver
+    logger.warning(
+        "seed: job '%s' delivers to %s but no %s is configured; delivering locally instead",
+        name, platform, " / ".join(needs),
+    )
+    return "local"
+
+
+def _config_inference() -> tuple:
+    """The model and provider hermes/config.yaml names: what every seeded job is pinned to."""
+    try:
+        from hermes_cli.config import load_config_readonly
+        cfg = load_config_readonly() or {}
+    except Exception as e:  # pragma: no cover - import path depends on runtime
+        logger.warning("seed: cannot read config.yaml for the model pin: %s", e)
+        return None, None
+    model = cfg.get("model")
+    if isinstance(model, dict):
+        return (str(model.get("default") or "").strip() or None, str(model.get("provider") or "").strip() or None)
+    if isinstance(model, str):
+        return (model.strip() or None, None)
+    return None, None
+
+
+def _seed_jobs() -> list:
+    seed_file = _hermes_home() / "cron" / "jobs.seed.json"
+    if not seed_file.exists():
+        return []
+    try:
+        data = json.loads(seed_file.read_text(encoding="utf-8"))
+    except (OSError, ValueError) as e:
+        logger.error("seed: failed to read %s: %s", seed_file, e)
+        return []
+    jobs = data.get("jobs", []) if isinstance(data, dict) else data
+    return [j for j in jobs if isinstance(j, dict)]
+
+
+# ---- the board -------------------------------------------------------------------------------------------------
+
+def _seed_tasks() -> tuple:
+    seed_file = _hermes_home() / "kanban.seed.json"
+    if not seed_file.exists():
+        return "dir:/work/project", []
+    try:
+        data = json.loads(seed_file.read_text(encoding="utf-8"))
+    except (OSError, ValueError) as e:
+        logger.error("seed: failed to read %s: %s", seed_file, e)
+        return "dir:/work/project", []
+    workspace = str(data.get("workspace") or "dir:/work/project")
+    tasks = [t for t in data.get("tasks", []) if isinstance(t, dict) and t.get("key") and t.get("title")]
+    return workspace, tasks
+
+
+def _seed_board() -> None:
+    """File every seed task that is not on the board yet, each a child of the one before it, so the dispatcher
+    pulls them down one at a time in the seed's order. `hermes kanban create --idempotency-key` returns the
+    existing task for a key it has seen, so a second boot changes nothing."""
+    import subprocess
+    workspace, tasks = _seed_tasks()
+    if not tasks:
+        return
+    subprocess.run(["hermes", "kanban", "init"], capture_output=True, text=True)
+    previous = None
+    for spec in tasks:
+        body = "\n".join(f"- {line}" for line in spec.get("acceptance", []) if isinstance(line, str))
+        cmd = ["hermes", "kanban", "create", str(spec["title"]), "--body", body, "--assignee", "default",
+               "--workspace", workspace, "--idempotency-key", f"seed:{spec['key']}", "--created-by", "seed",
+               "--skill", "develop", "--json"]
+        if previous:
+            cmd += ["--parent", previous]
+
+        r = subprocess.run(cmd, capture_output=True, text=True)
+        if r.returncode != 0:
+            logger.error("seed: cannot file task '%s': %s", spec["key"], (r.stderr or r.stdout).strip()[-400:])
+            return
+        m = re.search(r'"id":\s*"([^"]+)"', r.stdout)
+        if not m:
+            logger.error("seed: no task id in the board's answer for '%s'", spec["key"])
+            return
+        previous = m.group(1)
+        # A task the seed holds (`"held": "<why>"`) is filed and parked in the board's Scheduled lane at once, for the
+        # owner to release with `hermes kanban unblock`; only at filing, so a release is never undone by the next
+        # boot. Parked, not blocked: the board escalates repeated blocks into triage and decomposition, and the
+        # PM never touches Scheduled.
+        held = spec.get("held")
+        created_at = re.search(r'"created_at":\s*(\d+)', r.stdout)
+        if held and created_at and time.time() - int(created_at.group(1)) < 120:
+            subprocess.run(["hermes", "kanban", "schedule", previous, str(held)], capture_output=True, text=True)
+    logger.info("seed: the board holds the %d seed task(s)", len(tasks))
+
+
+async def handle(event_type: str, context: dict) -> None:
+    _seed_board()
+    try:
+        from cron.jobs import create_job, load_jobs, update_job
+    except Exception as e:  # pragma: no cover - import path depends on runtime
+        logger.error("seed: cannot import cron.jobs: %s", e)
+        return
+
+    seed = _seed_jobs()
+    if not seed:
+        logger.info("seed: no jobs.seed.json present; nothing to seed")
+        return
+
+    try:
+        live = load_jobs()
+    except Exception as e:
+        logger.error("seed: cannot load live jobs: %s", e)
+        return
+
+    model, provider = _config_inference()
+    live_by_name = {j.get("name"): j for j in live if j.get("name")}
+    created = 0
+    repinned = 0
+    for spec in seed:
+        name = spec.get("name")
+        if not name:
+            continue
+        job = live_by_name.get(name)
+        if job is not None:
+            if bool(spec.get("no_agent")) or ((job.get("model") or None) == model and (job.get("provider") or None) == provider):
+                continue
+            try:
+                update_job(job["id"], {"model": model, "provider": provider})
+                repinned += 1
+                logger.info("seed: re-pinned job '%s' to %s / %s (config.yaml moved)", name, provider, model)
+            except Exception as e:
+                logger.error("seed: failed to re-pin job '%s': %s", name, e)
+            continue
+        try:
+            create_job(
+                prompt=spec.get("prompt"),
+                schedule=spec.get("schedule"),
+                name=name,
+                deliver=_deliver_target(name, spec.get("deliver")),
+                skills=spec.get("skills") or None,
+                skill=spec.get("skill"),
+                workdir=spec.get("workdir"),
+                script=spec.get("script"),
+                no_agent=bool(spec.get("no_agent")),
+                model=None if spec.get("no_agent") else model,
+                provider=None if spec.get("no_agent") else provider,
+            )
+            created += 1
+            logger.info("seed: created job '%s' from seed, pinned to %s / %s", name, provider, model)
+        except Exception as e:
+            logger.error("seed: failed to create job '%s': %s", name, e)
+
+    if created or repinned:
+        logger.info("seed: seeded %d job(s) from jobs.seed.json, re-pinned %d", created, repinned)

package/template/hermes/kanban.seed.json

@@ -0,0 +1,13 @@
+{
+  "workspace": "dir:/work/project",
+  "tasks": [
+    {
+      "key": "hello",
+      "title": "The project says hello",
+      "acceptance": [
+        "`bun run check` passes on a fresh clone.",
+        "README.md describes what this project is for in one paragraph."
+      ]
+    }
+  ]
+}

package/template/hermes/profiles/treasurer/SOUL.md

@@ -0,0 +1,13 @@
+You are this project's treasurer: the one profile whose key can pay. The developer builds; you buy. A task assigned to you is a purchase request the developer filed: what to buy, at which merchant, for at most how much, why, and which of the developer's tasks is waiting on it (`for task:`).
+
+For each request, in order:
+
+1. `kanban_show` it and read the owner's bounds in `.open-autonomy/config.yaml` (`rails:`). A request over the bound, or at a merchant outside the owner's categories, is refused: `kanban_block` it with the reason, and never widen a bound; that is the owner's commit.
+2. Mint the card through your valve, naming the developer's task so the purchase shows on its page:
+   `curl -sf -X POST http://valve-pay:8787/v1/rails/card -H 'authorization: Bearer valve' -H 'content-type: application/json' -d '{"usd_cents": <ceiling>, "purpose": "<why>", "item": "<the developer's task id>"}'`.
+   The answer carries the card. It is single-use, bounded to that amount and the owner's categories, and retires on capture.
+3. Pay the merchant yourself, the way the request says. The card's number goes into the merchant's checkout and nowhere else: never into a comment, a file, a commit or a message.
+4. Record the receipt on the developer's task and release it: `HERMES_HOME=/opt/data /opt/hermes/bin/hermes kanban comment <developer task> "RECEIPT: <what> at <merchant>, $<amount> on card ····<last4>"`, then `HERMES_HOME=/opt/data /opt/hermes/bin/hermes kanban unblock <developer task>` (the terminal's shell has neither the home nor the binary on its path; both are named in full).
+5. `kanban_complete` your task with the receipt in one line.
+
+You never write code, never touch the developer's branch, and never buy what no request asked for. Every cent you spend is on the project's public books, under the task it served.

package/template/hermes/profiles/treasurer/config.yaml

@@ -0,0 +1,33 @@
+# The treasurer profile's config: the same agent, pointed at its own valve. Everything else is the default's.
+# The project agent's Hermes configuration. The model is this project's choice (runtime config, seeded by
+# the kit, never checked by it). Secrets live in hermes/.env (git-ignored):
+#   OPEN_AUTONOMY_BASE_URL / OPEN_AUTONOMY_KEY  — inside the stack, the key valve's address and a dummy
+#   DISCORD_BOT_TOKEN / DISCORD_HOME_CHANNEL    — optional Discord delivery
+model:
+  default: zai/glm-5.3-flash
+  provider: custom
+  base_url: http://valve-pay:8787/v1 # the treasurer's valve: the only key that pays
+  api_key: valve
+  api_mode: chat_completions
+
+terminal:
+  backend: local
+  timeout: 300
+
+# Everything the agent is must be readable in the repository, so it carries no private memory between runs.
+memory:
+  memory_enabled: false
+  user_profile_enabled: false
+
+compression:
+  enabled: true
+  threshold: 0.50
+
+agent:
+  max_turns: 80
+
+# The board (Hermes Kanban) the schedule files roadmap items on. Its dispatcher runs inside the gateway and
+# the review lane verifies every handoff; the interval is how soon a filed task is picked up.
+kanban:
+  dispatch_interval_seconds: 15
+  review_dispatch: true