@data-matters.io/agent-harness 0.0.0-stage → 0.1.0

package/templates/.harness/db-smoke.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+# Database smoke gate (ADR 0016): applies the migrations and runs the seed on an
+# empty PostgreSQL, through the same Prisma setup the app uses. Unit tests mock
+# the database, so this is the gate that sees a broken migration, seed or driver.
+#
+# Usage: .harness/db-smoke.sh <migrate-command> <seed-command> [<check-command>]
+#   e.g. in gates.conf:
+#   GATE_EXTRA=("db:.harness/db-smoke.sh '$bin/prisma migrate deploy' '$bin/prisma db seed'")
+#
+# A seed that does not run fails too: `prisma db seed` exits 0 when no seed is
+# configured, so its output must show that the seed command was executed.
+#
+# Database: HARNESS_DB_SMOKE_URL when set (CI: the postgres service of gates.yml),
+# otherwise a throwaway container (docker or podman) removed afterwards. Without
+# a container runtime it fails; skip it on such a machine with
+# HARNESS_SKIP_GATES=db (CI still runs it). The commands get DATABASE_URL.
+#
+# Environment:
+#   HARNESS_DB_SMOKE_URL    use this database instead of a container
+#   HARNESS_DB_SMOKE_IMAGE  container image (default postgres:16-alpine)
+set -euo pipefail
+
+usage() { sed -n '2,20p' "$0" | sed 's/^# \{0,1\}//'; exit "${1:-0}"; }
+die() { echo "db-smoke: $*" >&2; exit 1; }
+
+[[ "${1:-}" == "-h" || "${1:-}" == "--help" ]] && usage 0
+[[ $# -ge 2 ]] || usage 1
+
+url="${HARNESS_DB_SMOKE_URL:-}"
+runtime="" container=""
+cleanup() { if [[ -n "$container" ]]; then "$runtime" rm -f "$container" >/dev/null 2>&1 || true; fi; }
+trap cleanup EXIT
+
+if [[ -z "$url" ]]; then
+  for candidate in docker podman; do
+    if command -v "$candidate" >/dev/null 2>&1 && "$candidate" info >/dev/null 2>&1; then runtime="$candidate"; break; fi
+  done
+  [[ -n "$runtime" ]] || die "no usable container runtime; set HARNESS_SKIP_GATES=db on this machine (CI still runs it)"
+  password="smoke$RANDOM$RANDOM"
+  container="$("$runtime" run -d --rm -e POSTGRES_USER=smoke -e POSTGRES_PASSWORD="$password" -e POSTGRES_DB=smoke \
+    -p 127.0.0.1::5432 "${HARNESS_DB_SMOKE_IMAGE:-postgres:16-alpine}")" || die "could not start a PostgreSQL container"
+  port="$("$runtime" port "$container" 5432/tcp | head -n1 | sed 's/.*://')"
+  # TCP only answers once the image's init server is gone and the real one is up.
+  for (( i = 0; i < 60; i++ )); do
+    "$runtime" exec "$container" pg_isready -q -h 127.0.0.1 -U smoke -d smoke 2>/dev/null && break
+    sleep 1
+  done
+  "$runtime" exec "$container" pg_isready -q -h 127.0.0.1 -U smoke -d smoke || die "PostgreSQL did not become ready"
+  url="postgresql://smoke:$password@127.0.0.1:$port/smoke"
+fi
+
+export DATABASE_URL="$url"
+# Prisma runs the seed command from its config (e.g. `tsx db/seed.ts`) the way
+# pnpm scripts do: with the project's binaries on PATH.
+export PATH="$PWD/node_modules/.bin:$PATH"
+echo "db-smoke: migrate: $1"
+bash -c "$1" || die "migrations failed"
+echo "db-smoke: seed: $2"
+seed_log="$(mktemp)"
+trap 'rm -f "$seed_log"; cleanup' EXIT
+bash -c "$2" 2>&1 | tee "$seed_log"
+[[ "${PIPESTATUS[0]}" -eq 0 ]] || die "seed failed"
+# `prisma db seed` exits 0 when no seed is configured (Prisma 7 reads only
+# migrations.seed in prisma.config.ts): that is a seed that never ran.
+if grep -qi 'No seed command configured' "$seed_log"; then
+  die "no seed ran: Prisma found no seed command (Prisma 7 reads migrations.seed in prisma.config.ts)"
+fi
+if [[ "$2" == *"prisma db seed"* ]] && ! grep -q 'seed command has been executed' "$seed_log"; then
+  die "no seed ran: Prisma did not report executing the seed command"
+fi
+if [[ -n "${3:-}" ]]; then
+  echo "db-smoke: check: $3"
+  bash -c "$3" || die "check failed"
+fi
+echo "db-smoke: migrations and seed passed"

package/templates/.harness/deps.sh

@@ -0,0 +1,219 @@
+#!/usr/bin/env bash
+# Dependencies an approved spec declares (ADR 0015): checks the declaration and
+# installs exactly those packages, touching nothing else.
+#
+# Usage: .harness/deps.sh check <change-dir>     validate the declaration (spec-pr.sh)
+#        .harness/deps.sh list <change-dir>      print it, one "kind name version" per line
+#        .harness/deps.sh install <change-dir>   add what package.json lacks (run-tasks.sh)
+#
+# The declaration is the "## Dependencies" section of <change-dir>/design.md.
+# Every bullet in it is one of:
+#   - dependency: <name>@<x.y.z>
+#   - devDependency: <name>@<x.y.z>
+#   - allow-build: <name>        (lets an installed package run its install script)
+# Values may be in backticks; other text in the section is prose.
+#
+# install runs `pnpm add --save-exact` without a terminal. A package with an
+# install script that is not declared as allow-build is denied in
+# pnpm-workspace.yaml (`allowBuilds: <name>: false`). Afterwards it verifies that
+# only the declared entries were added to package.json, that no locked package
+# was removed or changed version, and that pnpm-workspace.yaml only gained
+# allowBuilds entries. On any surprise it restores the files and exits 2.
+#
+# Exit codes: 0 ok, 1 usage or invalid declaration, 2 install refused.
+#
+# Environment:
+#   HARNESS_DEPS_TIMEOUT   seconds per pnpm call (default 600)
+#   HARNESS_DEPS_OFFLINE   1 = check skips the registry lookup
+set -euo pipefail
+
+usage() { sed -n '2,27p' "$0" | sed 's/^# \{0,1\}//'; exit "${1:-0}"; }
+die() { echo "deps: $*" >&2; exit 1; }
+refuse() { echo "deps: $*" >&2; exit 2; }
+
+[[ $# -eq 2 ]] || usage 1
+cmd="$1"
+change_dir="${2%/}"
+design="$change_dir/design.md"
+
+name_re='(@[a-z0-9][a-z0-9._-]*/)?[a-z0-9][a-z0-9._-]*'
+version_re='[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?'
+
+# section: the lines of "## Dependencies" in design.md (empty when absent).
+section() {
+  [[ -f "$design" ]] || return 0
+  awk '/^## /{ on = ($0 ~ /^## Dependencies[[:space:]]*$/); next } on' "$design"
+}
+
+# parse: prints "kind name version" per declared entry (version "-" for
+# allow-build); fails on a bullet that does not follow the grammar.
+parse() {
+  local line body kind value bad=0
+  while IFS= read -r line; do
+    [[ "$line" =~ ^[[:space:]]*[-*][[:space:]]+(.*)$ ]] || continue
+    body="${BASH_REMATCH[1]//\`/}"
+    if [[ "$body" =~ ^(dependency|devDependency|allow-build):[[:space:]]*([^[:space:]]+)[[:space:]]*$ ]]; then
+      kind="${BASH_REMATCH[1]}"
+      value="${BASH_REMATCH[2]}"
+      if [[ "$kind" == allow-build ]]; then
+        if [[ "$value" =~ ^${name_re}$ ]]; then echo "$kind $value -"; continue; fi
+      elif [[ "$value" =~ ^(${name_re})@(${version_re})$ ]]; then
+        echo "$kind ${BASH_REMATCH[1]} ${BASH_REMATCH[3]}"
+        continue
+      fi
+    fi
+    echo "deps: $design: '${line#"${line%%[![:space:]]*}"}' is not '- dependency|devDependency: <name>@<x.y.z>' or '- allow-build: <name>'" >&2
+    bad=1
+  done < <(section)
+  return "$bad"
+}
+
+declared="$(parse)" || die "invalid ## Dependencies section in $design"
+
+case "$cmd" in
+  list)
+    [[ -z "$declared" ]] || echo "$declared"
+    exit 0 ;;
+  check)
+    if [[ -n "$declared" && "${HARNESS_DEPS_OFFLINE:-0}" != 1 ]]; then
+      while read -r kind name version; do
+        [[ "$kind" == allow-build ]] && continue
+        found="$(pnpm view "$name@$version" version 2>/dev/null </dev/null || true)"
+        [[ "$found" == "$version" ]] || die "$name@$version is not published in the registry"
+      done <<<"$declared"
+    fi
+    echo "deps: $(grep -c . <<<"$declared" || true) declared entr(y/ies) in $design are valid"
+    exit 0 ;;
+  install) ;;
+  *) usage 1 ;;
+esac
+
+# ---------------------------------------------------------------- install --
+
+[[ -f package.json ]] || die "run it from the project root (no package.json here)"
+[[ -n "$declared" ]] || { echo "deps: nothing declared"; exit 0; }
+
+# current <section> <name>: the specifier package.json has for it, if any.
+current() {
+  node -e 'const p = require("./package.json"); process.stdout.write((p[process.argv[1]] || {})[process.argv[2]] || "")' "$1" "$2"
+}
+
+prod=() dev=() allow=() wanted=()
+while read -r kind name version; do
+  case "$kind" in
+    allow-build) allow+=("$name"); continue ;;
+    dependency) section_name=dependencies other=devDependencies ;;
+    devDependency) section_name=devDependencies other=dependencies ;;
+  esac
+  have="$(current "$section_name" "$name")"
+  [[ -z "$(current "$other" "$name")" ]] || refuse "$name is in $other, the spec declares it as $kind"
+  if [[ "$have" == "$version" ]]; then continue; fi
+  [[ -z "$have" ]] || refuse "package.json has $name $have, the spec declares $version; changing it needs a spec change"
+  wanted+=("$section_name $name $version")
+  if [[ "$kind" == dependency ]]; then prod+=("$name@$version"); else dev+=("$name@$version"); fi
+done <<<"$declared"
+if [[ ${#wanted[@]} -eq 0 ]]; then
+  echo "deps: every declared dependency is already in package.json"
+  exit 0
+fi
+
+dep_files=(package.json pnpm-lock.yaml pnpm-workspace.yaml)
+[[ -z "$(git status --porcelain -- "${dep_files[@]}")" ]] || refuse "dependency files have uncommitted changes"
+status_before="$(git status --porcelain --untracked-files=all | grep -vE ' (package.json|pnpm-lock.yaml|pnpm-workspace.yaml)$' || true)"
+before="$(mktemp -d)"
+trap 'rm -rf "$before"' EXIT
+cp package.json "$before/package.json"
+[[ -f pnpm-lock.yaml ]] && cp pnpm-lock.yaml "$before/pnpm-lock.yaml"
+[[ -f pnpm-workspace.yaml ]] && cp pnpm-workspace.yaml "$before/pnpm-workspace.yaml"
+
+restore() {
+  local f
+  for f in "${dep_files[@]}"; do
+    if git ls-files --error-unmatch "$f" >/dev/null 2>&1; then git checkout -q -- "$f"; else rm -f "$f"; fi
+  done
+  refuse "$1"
+}
+
+# pnpm_add <flags...> -- <specs...>: one non-interactive pnpm add. A package with
+# an undeclared install script is denied and the add is repeated once.
+pnpm_add() {
+  local flags=() specs=() out denied=() name a
+  while [[ "$1" != -- ]]; do flags+=("$1"); shift; done
+  shift
+  specs=("$@")
+  for a in "${allow[@]}"; do flags+=(--allow-build "$a"); done
+  if out="$(CI=1 timeout "${HARNESS_DEPS_TIMEOUT:-600}" pnpm add --save-exact "${flags[@]}" "${specs[@]}" </dev/null 2>&1)"; then
+    printf '%s\n' "$out"
+    return 0
+  fi
+  printf '%s\n' "$out"
+  grep -q ERR_PNPM_IGNORED_BUILDS <<<"$out" || return 1
+  while read -r name; do
+    [[ -n "$name" ]] && denied+=(--allow-build "!$name")
+  done < <(grep -oE 'Ignored build scripts: .*' <<<"$out" | sed 's/^Ignored build scripts: //' | tr ',' '\n' \
+    | sed -E 's/^[[:space:]]+//; s/[[:space:]]+$//; s/@[^@]+$//')
+  [[ ${#denied[@]} -gt 0 ]] || return 1
+  echo "deps: denying install scripts not declared as allow-build:$(printf ' %s' "${denied[@]}" | sed 's/ --allow-build !/ /g')"
+  CI=1 timeout "${HARNESS_DEPS_TIMEOUT:-600}" pnpm add --save-exact "${flags[@]}" "${denied[@]}" "${specs[@]}" </dev/null 2>&1
+}
+
+if [[ ${#prod[@]} -gt 0 ]]; then pnpm_add -- "${prod[@]}" || restore "pnpm add ${prod[*]} failed"; fi
+if [[ ${#dev[@]} -gt 0 ]]; then pnpm_add --save-dev -- "${dev[@]}" || restore "pnpm add -D ${dev[*]} failed"; fi
+
+# ----------------------------------------------------------------- verify --
+
+# package.json: exactly the declared entries were added, nothing else changed.
+if ! node -e '
+  const fs = require("fs");
+  const [beforeFile, ...wanted] = process.argv.slice(1);
+  const a = JSON.parse(fs.readFileSync(beforeFile, "utf8")), b = JSON.parse(fs.readFileSync("package.json", "utf8"));
+  for (const w of wanted) { const [s, n, v] = w.split(" "); a[s] = { ...(a[s] || {}), [n]: v }; }
+  const norm = (o) => JSON.stringify(o, Object.keys(o).sort());
+  for (const k of new Set([...Object.keys(a), ...Object.keys(b)])) {
+    const x = a[k], y = b[k];
+    const same = (x && typeof x === "object" && y && typeof y === "object") ? norm(x) === norm(y) : JSON.stringify(x) === JSON.stringify(y);
+    if (!same) { console.error("deps: package.json field " + k + " differs from the declaration"); process.exit(1); }
+  }' "$before/package.json" "${wanted[@]}"; then
+  restore "package.json changed beyond the declared dependencies"
+fi
+
+# lock_keys <file>: locked packages and snapshots.
+lock_keys() {
+  [[ -f "$1" ]] || return 0
+  awk '/^---/{ sec = ""; next } /^[A-Za-z]/{ sec = $0; next }
+       (sec == "packages:" || sec == "snapshots:") && /^  [^ ]/ { k = $0; sub(/^ +/, "", k); gsub(/'\''/, "", k); print sec k }' "$1" | sort -u
+}
+# importer_versions <file>: "name version" of every direct dependency.
+importer_versions() {
+  [[ -f "$1" ]] || return 0
+  awk '/^---/{ sec = ""; next } /^[A-Za-z]/{ sec = $0; next }
+       sec == "importers:" && /^      [^ ].*:$/ { n = $0; sub(/^ +/, "", n); sub(/:$/, "", n); gsub(/'\''/, "", n); next }
+       sec == "importers:" && /^        version: / { v = $0; sub(/^ +version: /, "", v); print n " " v }' "$1" | sort -u
+}
+
+removed="$(comm -23 <(lock_keys "$before/pnpm-lock.yaml") <(lock_keys pnpm-lock.yaml))"
+[[ -z "$removed" ]] || restore "the lockfile lost or changed locked packages (other dependencies would move):
+$(head -n 20 <<<"$removed")"
+
+added_names=" $(printf '%s\n' "${wanted[@]}" | awk '{ print $2 }' | tr '\n' ' ')"
+moved="$(comm -3 <(importer_versions "$before/pnpm-lock.yaml") <(importer_versions pnpm-lock.yaml) \
+  | sed 's/^[[:space:]]*//' | while read -r n v; do [[ "$added_names" == *" $n "* ]] || echo "$n $v"; done)"
+[[ -z "$moved" ]] || restore "direct dependencies outside the declaration changed:
+$moved"
+
+if [[ -f pnpm-workspace.yaml ]]; then
+  unexpected="$(diff "$before/pnpm-workspace.yaml" pnpm-workspace.yaml 2>/dev/null | grep -E '^[<>]' \
+    | grep -vE "^> +'?${name_re}'?: (true|false)$" | grep -vE '^> allowBuilds:$' || true)"
+  if [[ ! -f "$before/pnpm-workspace.yaml" ]]; then
+    unexpected="$(grep -vE "^ +'?${name_re}'?: (true|false)$|^allowBuilds:$|^$" pnpm-workspace.yaml || true)"
+  fi
+  [[ -z "$unexpected" ]] || restore "pnpm-workspace.yaml changed beyond allowBuilds entries:
+$unexpected"
+fi
+
+others="$(comm -13 <(sort <<<"$status_before") \
+  <(git status --porcelain --untracked-files=all | grep -vE ' (package.json|pnpm-lock.yaml|pnpm-workspace.yaml)$' | sort) || true)"
+[[ -z "$others" ]] || restore "pnpm add changed other files:
+$others"
+
+echo "deps: added ${wanted[*]}"

package/templates/.harness/gates.conf.example

@@ -0,0 +1,26 @@
+# Gate commands for this project. Sourced by .harness/gates.sh.
+# Each command runs with `bash -c` from the repo root; exit 0 = pass.
+#
+# Required gates: test, lint, typecheck, build.
+# An empty/unset required gate FAILS. To skip one deliberately, use
+#   GATE_X="skip:<reason>"
+# and revisit it: the reason is printed on every run.
+
+GATE_TEST=""
+GATE_LINT=""        # must include architecture rules (see .harness/standards/stack/architecture.md)
+GATE_TYPECHECK=""
+GATE_BUILD=""
+
+# Optional: command run once before the gates (code generation, etc.).
+# Its failure fails the whole run.
+GATE_SETUP=""
+
+# Gates run by the Claude Code Stop hook (fast profile). Empty = all gates.
+# The task loop and CI always run every gate.
+STOP_GATES=()
+
+# Optional extra gates, run after the required ones, in order: "name:command".
+GATE_EXTRA=(
+  # "coverage:npm run test:coverage -- --coverage.thresholds.lines=80"
+  # "security:npm audit --audit-level=high"
+)

package/templates/.harness/gates.sh

@@ -0,0 +1,108 @@
+#!/usr/bin/env bash
+# Runs every Definition-of-Done gate declared in .harness/gates.conf.
+# Exit 0 only if all gates pass. Used by the Stop hook, the task loop and CI.
+#
+# Usage: .harness/gates.sh [--stop] [gate ...]
+#   no args   run every gate (task loop, CI)
+#   --stop    run only STOP_GATES from gates.conf (fast profile for the Stop hook)
+#   gate ...  run only the named gates
+#
+# HARNESS_SKIP_GATES="name ..." skips the named gates on this machine (e.g.
+# integration where no container runtime exists). Skips are printed on every
+# run; CI never sets it.
+set -uo pipefail
+
+root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$root" || exit 1
+
+conf="$root/.harness/gates.conf"
+if [[ ! -f "$conf" ]]; then
+  echo "gates: missing $conf (copy gates.conf.example and fill it in)" >&2
+  exit 1
+fi
+
+REQUIRED_GATES=(test lint typecheck build)
+GATE_EXTRA=()
+GATE_SETUP=""
+STOP_GATES=()
+# shellcheck source=/dev/null
+source "$conf"
+
+selected=("$@")
+if [[ "${1-}" == "--stop" ]]; then
+  selected=("${STOP_GATES[@]}")
+fi
+
+log_dir="$root/.harness/state/gates"
+mkdir -p "$log_dir"
+tail_lines="${HARNESS_GATE_TAIL:-60}"
+
+# Build the ordered list of (name, command) pairs.
+names=()
+cmds=()
+for gate in "${REQUIRED_GATES[@]}"; do
+  var="GATE_${gate^^}"
+  names+=("$gate")
+  cmds+=("${!var-}")
+done
+for entry in "${GATE_EXTRA[@]}"; do
+  names+=("${entry%%:*}")
+  cmds+=("${entry#*:}")
+done
+
+is_selected() {
+  [[ ${#selected[@]} -eq 0 ]] && return 0
+  local s
+  for s in "${selected[@]}"; do [[ "$s" == "$1" ]] && return 0; done
+  return 1
+}
+
+# Setup runs before any gate (e.g. code generation); its failure fails everything.
+if [[ -n "$GATE_SETUP" ]]; then
+  if ! bash -c "$GATE_SETUP" >"$log_dir/setup.log" 2>&1; then
+    echo "FAIL  setup  \$ $GATE_SETUP"
+    tail -n "$tail_lines" "$log_dir/setup.log"
+    echo "gates: FAILED (setup)"
+    exit 1
+  fi
+fi
+
+failed=()
+for i in "${!names[@]}"; do
+  name="${names[$i]}"
+  cmd="${cmds[$i]}"
+  is_selected "$name" || continue
+
+  if [[ " ${HARNESS_SKIP_GATES:-} " == *" $name "* ]]; then
+    echo "SKIP  $name  (HARNESS_SKIP_GATES on this machine)"
+    continue
+  fi
+
+  if [[ -z "$cmd" ]]; then
+    echo "FAIL  $name  (not configured; set GATE_${name^^} or 'skip:<reason>')"
+    failed+=("$name")
+    continue
+  fi
+  if [[ "$cmd" == skip:* ]]; then
+    echo "SKIP  $name  (${cmd#skip:})"
+    continue
+  fi
+
+  log="$log_dir/$name.log"
+  start=$(date +%s)
+  if bash -c "$cmd" >"$log" 2>&1; then
+    echo "PASS  $name  ($(( $(date +%s) - start ))s)"
+  else
+    echo "FAIL  $name  ($(( $(date +%s) - start ))s)  \$ $cmd"
+    echo "----- last $tail_lines lines of $name output -----"
+    tail -n "$tail_lines" "$log"
+    echo "-----"
+    failed+=("$name")
+  fi
+done
+
+if [[ ${#failed[@]} -gt 0 ]]; then
+  echo "gates: FAILED (${failed[*]})"
+  exit 1
+fi
+echo "gates: all passed"

package/templates/.harness/lib.sh

@@ -0,0 +1,129 @@
+# Shared helpers for the .harness scripts. Source it; do not run it.
+# shellcheck shell=bash
+
+# Main checkout of the repository, also when called from one of its worktrees:
+# loop state and logs always live there.
+harness_root() {
+  local common
+  common="$(git rev-parse --path-format=absolute --git-common-dir)" || return 1
+  dirname "$common"
+}
+
+# Loads the machine-level harness settings (HARNESS_ENV_FILE, default
+# ~/.config/harness/env) and exports every variable in them, so they reach the
+# gates and every Claude Code session the harness starts, also when it is started
+# by a timer with an empty environment. TELEGRAM_STATE_DIR there keeps those
+# sessions away from the operator's Telegram channel (see env.example).
+harness_load_env() {
+  local env_file="${HARNESS_ENV_FILE:-$HOME/.config/harness/env}"
+  [[ -f "$env_file" ]] || return 0
+  set -a
+  # shellcheck source=/dev/null
+  . "$env_file"
+  set +a
+}
+
+# HARNESS_CLAUDE: the command that starts Claude Code for an agent session (an
+# array, so it works after `timeout`). The bot token and chat id are left out of
+# the session's environment: only notify.sh needs them, and it reads the env file
+# itself. TELEGRAM_STATE_DIR from the env file is kept.
+# shellcheck disable=SC2034  # used by the scripts that source this file
+HARNESS_CLAUDE=(env -u HARNESS_TELEGRAM_BOT_TOKEN -u HARNESS_TELEGRAM_CHAT_ID claude)
+
+# Worktree where the task loop runs a change (ADR 0012), outside the checkout so
+# lint, tests and type-checks of the main checkout never see it:
+#   ${HARNESS_WORKTREES_DIR:-<parent of the checkout>/.harness-worktrees/<repo>}/<change-id>
+harness_worktree() {
+  local root
+  root="$(harness_root)" || return 1
+  echo "${HARNESS_WORKTREES_DIR:-$(dirname "$root")/.harness-worktrees/$(basename "$root")}/$1"
+}
+
+# ------------------------------------------------- model routing (ADR 0020) --
+# harness_models: loads models.conf next to this file (or in HARNESS_MODELS_DIR), then the project's
+# models.local.conf and $HARNESS_MODELS_FILE, in a subshell-safe way (callers
+# use the functions below, which run it in a subshell).
+harness_models() {
+  # HARNESS_MODELS_DIR: read another project's mapping with this code (the
+  # watcher runs the harness's newest lib.sh against each project's models.conf).
+  local base="${HARNESS_MODELS_DIR:-$(dirname "${BASH_SOURCE[0]}")}"
+  # shellcheck source=/dev/null
+  . "$base/models.conf" || return 1
+  # shellcheck source=/dev/null
+  [[ -f "$base/models.local.conf" ]] && . "$base/models.local.conf"
+  # shellcheck source=/dev/null
+  [[ -n "${HARNESS_MODELS_FILE:-}" && -f "$HARNESS_MODELS_FILE" ]] && . "$HARNESS_MODELS_FILE"
+  return 0
+}
+
+# harness_task_level <task-type> [<level override>]: the level (R1-R4).
+harness_task_level() {
+  (
+    harness_models || exit 1
+    local level="${2:-}" var="TASK_$1"
+    [[ -n "$level" ]] || level="${!var:-}"
+    [[ "$level" =~ ^R[1-4]$ ]] || { echo "harness: unknown task type or level '$1${2:+/$2}'" >&2; exit 1; }
+    echo "$level"
+  )
+}
+
+# harness_level_climb <level> <steps>: the level <steps> above, capped at R4.
+harness_level_climb() {
+  local n="${1#R}"; n=$(( n + $2 )); (( n > 4 )) && n=4; (( n < 1 )) && n=1
+  echo "R$n"
+}
+
+# harness_level_flags <level>: the claude flags for a level; empty while
+# HARNESS_MODEL_ROUTING is not "on" (measure mode, decision 7).
+harness_level_flags() {
+  (
+    harness_models || exit 1
+    [[ "$1" =~ ^R[1-4]$ ]] || { echo "harness: unknown level '$1'" >&2; exit 1; }
+    [[ "${HARNESS_MODEL_ROUTING:-measure}" == on ]] || exit 0
+    echo "${!1}"
+  )
+}
+
+# harness_claude_flags <task-type> [<level override>]: the claude flags for a
+# task. The single entry point from task to model and effort.
+harness_claude_flags() {
+  local level; level="$(harness_task_level "$@")" || return 1
+  harness_level_flags "$level"
+}
+
+# harness_flag_value <flags> <--flag>: e.g. the --effort of a level's flags.
+harness_flag_value() {
+  # shellcheck disable=SC2206
+  local words=($1) i
+  for (( i = 0; i < ${#words[@]}; i++ )); do
+    [[ "${words[$i]}" == "$2" ]] && { echo "${words[$((i + 1))]:-}"; return 0; }
+  done
+}
+
+# ------------------------------------------------- usage ledger (ADR 0020) --
+# harness_session_usage <session.json>: "model<TAB>cost_usd<TAB>output_tokens<TAB>cache_read_tokens"
+# from a claude -p --output-format json result (models joined by "+").
+harness_session_usage() {
+  node -e '
+    let d = {}; try { d = JSON.parse(require("fs").readFileSync(process.argv[1], "utf8")); } catch {}
+    const mu = d.modelUsage || {};
+    const sum = (k) => Object.values(mu).reduce((a, m) => a + (m[k] || 0), 0);
+    const cost = typeof d.total_cost_usd === "number" ? d.total_cost_usd : sum("costUSD");
+    process.stdout.write([Object.keys(mu).join("+") || "unknown", cost.toFixed(4),
+      sum("outputTokens"), sum("cacheReadInputTokens")].join("\t"));' "$1" 2>/dev/null \
+    || printf 'unknown\t0.0000\t0\t0'
+}
+
+# harness_record_usage <project> <ref> <task-type> <level> <effort> <attempt> <result> <session.json>:
+# one line in the machine-wide ledger (HARNESS_USAGE_LEDGER, default
+# ~/.local/state/harness/usage.tsv); prints the session's usage columns.
+harness_record_usage() {
+  local ledger="${HARNESS_USAGE_LEDGER:-$HOME/.local/state/harness/usage.tsv}" usage
+  usage="$(harness_session_usage "$8")"
+  mkdir -p "$(dirname "$ledger")"
+  [[ -s "$ledger" ]] || printf 'timestamp\tproject\tref\ttask_type\tlevel\tmodel\teffort\tcost_usd\toutput_tokens\tcache_read_tokens\tresult\tattempt\n' >"$ledger"
+  IFS=$'\t' read -r model cost out cache <<<"$usage"
+  printf '%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\n' "$(date -Iseconds)" "$1" "$2" "$3" "$4" \
+    "$model" "${5:-default}" "$cost" "$out" "$cache" "$7" "$6" >>"$ledger"
+  printf '%s' "$usage"
+}

package/templates/.harness/loop.sh

@@ -0,0 +1,101 @@
+#!/usr/bin/env bash
+# Runs the task loop for an approved OpenSpec change (spec PR merged) in the
+# background, detached from the calling session (a Claude Code session, SSH, ...),
+# and keeps it going.
+#
+# Usage: .harness/loop.sh start <change-id> [run-tasks options]
+#        .harness/loop.sh status [change-id]
+#        .harness/loop.sh stop <change-id>
+#        .harness/loop.sh logs <change-id>
+#
+# The supervisor runs run-tasks.sh --open-pr and reacts to its exit code:
+#   0  done        → notify with the PR link
+#   2  escalated   → notify; a human takes over
+#   3  paused (account usage limit; run-tasks discarded the partial attempt)
+#      → notify, wait HARNESS_RESUME_INTERVAL seconds (default 900), try again
+# run-tasks works in the change's own git worktree (ADR 0012): the checkout this
+# runs from is never switched or cleaned, so specs can be written meanwhile.
+# Notifications go through .harness/notify.sh (Telegram when configured).
+set -euo pipefail
+
+# shellcheck source-path=SCRIPTDIR source=lib.sh
+. "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+root="$(harness_root)"
+cd "$root"
+
+# Machine-level harness settings (Telegram, skipped gates, resume interval),
+# kept outside the repository: HARNESS_ENV_FILE or ~/.config/harness/env.
+harness_load_env
+state_dir=".harness/state"
+mkdir -p "$state_dir" .harness/logs
+
+die() { echo "loop: $*" >&2; exit 1; }
+pid_file() { echo "$state_dir/loop-$1.pid"; }
+running() { local f; f="$(pid_file "$1")"; [[ -f "$f" ]] && kill -0 "$(cat "$f")" 2>/dev/null; }
+
+supervise() {
+  local change="$1"; shift
+  local interval="${HARNESS_RESUME_INTERVAL:-900}" log=".harness/logs/$change/runner.log" rc pr every reason
+  mkdir -p ".harness/logs/$change"
+  .harness/notify.sh started "Loop started for change $change"
+  while true; do
+    set +e
+    .harness/run-tasks.sh "$change" --open-pr "$@" >>"$log" 2>&1
+    rc=$?
+    set -e
+    case "$rc" in
+      0)
+        pr="$(grep -oE 'https://github.com/[^ ]+/pull/[0-9]+' "$log" | tail -n1 || true)"
+        .harness/notify.sh "done" "Change $change is done${pr:+: $pr}"
+        break ;;
+      2)
+        reason="$(grep -E '^run-tasks: ' "$log" | tail -n1 | sed 's/^run-tasks: //')"
+        .harness/notify.sh escalated "Change $change escalated: ${reason:-see the runner log}. See .harness/status.sh $change"
+        break ;;
+      3)
+        if (( interval >= 60 )); then every="$((interval / 60)) min"; else every="${interval}s"; fi
+        .harness/notify.sh paused "Change $change paused by the account usage limit; retrying every $every"
+        sleep "$interval"
+        .harness/notify.sh resumed "Resuming change $change" ;;
+      *)
+        .harness/notify.sh error "Change $change stopped with exit code $rc. See .harness/logs/$change/runner.log"
+        break ;;
+    esac
+  done
+  rm -f "$(pid_file "$change")"
+}
+
+cmd="${1:-}"; shift || true
+case "$cmd" in
+  start)
+    change="${1:-}"; [[ -n "$change" ]] || die "usage: loop.sh start <change-id>"; shift
+    running "$change" && die "a loop for $change is already running (pid $(cat "$(pid_file "$change")"))"
+    # Fail here, not in the background: the spec must be approved (merged into
+    # the base branch through its spec PR, ADR 0011) and its worktree clean.
+    .harness/run-tasks.sh "$change" --check "$@" >/dev/null || die "change $change cannot start (see above)"
+    setsid nohup "$0" __supervise "$change" "$@" >/dev/null 2>&1 </dev/null &
+    echo $! >"$(pid_file "$change")"
+    echo "loop: started $change in the background (pid $!). Follow it with .harness/loop.sh status $change"
+    ;;
+  __supervise)
+    supervise "$@" ;;
+  status)
+    if [[ -n "${1:-}" ]]; then
+      running "$1" && echo "supervisor: running (pid $(cat "$(pid_file "$1")"))" || echo "supervisor: not running"
+      .harness/status.sh "$1"
+    else
+      .harness/status.sh
+    fi ;;
+  stop)
+    change="${1:-}"; [[ -n "$change" ]] || die "usage: loop.sh stop <change-id>"
+    running "$change" || die "no loop running for $change"
+    pkill -TERM -s "$(ps -o sid= -p "$(cat "$(pid_file "$change")")" | tr -d ' ')" || true
+    rm -f "$(pid_file "$change")"
+    .harness/notify.sh error "Loop for change $change stopped by request"
+    echo "loop: stopped $change" ;;
+  logs)
+    change="${1:-}"; [[ -n "$change" ]] || die "usage: loop.sh logs <change-id>"
+    tail -n 40 ".harness/logs/$change/runner.log" ;;
+  *)
+    sed -n '2,18p' "$0" | sed 's/^# \{0,1\}//'; exit 1 ;;
+esac