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

package/templates/.harness/model-flags.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# Prints the Claude Code flags for a task type, from .harness/models.conf
+# (ADR 0020). For anything that starts sessions outside the harness scripts,
+# e.g. a spec-authoring session started by another tool (ADR 0020):
+#
+#   claude $(.harness/model-flags.sh spec_author) -p "..."
+#
+# Usage: .harness/model-flags.sh <task-type> [<level override>]
+#        .harness/model-flags.sh --level <task-type> [<level override>]
+#        .harness/model-flags.sh --list
+#
+# Prints nothing while HARNESS_MODEL_ROUTING is not "on" (measure mode): the
+# session then keeps the account's default model. Reads the machine env file
+# (HARNESS_ENV_FILE, default ~/.config/harness/env) for HARNESS_MODEL_ROUTING
+# and HARNESS_MODELS_FILE. Exit 1 on an unknown task type or level.
+set -euo pipefail
+
+usage() { sed -n '2,15p' "$0" | sed 's/^# \{0,1\}//'; exit "${1:-0}"; }
+# shellcheck source-path=SCRIPTDIR source=lib.sh
+. "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+harness_load_env
+
+case "${1:-}" in
+  ""|-h|--help) usage 0 ;;
+  --level) shift; harness_task_level "$@" ;;
+  --list)
+    (
+      harness_models
+      echo "routing: ${HARNESS_MODEL_ROUTING:-measure}"
+      for l in R4 R3 R2 R1; do echo "$l: ${!l}"; done
+      compgen -v TASK_ | while read -r v; do echo "${v#TASK_}: ${!v}"; done
+    ) ;;
+  *) harness_claude_flags "$@" ;;
+esac

package/templates/.harness/models.conf

@@ -0,0 +1,30 @@
+# Reasoning level → Claude Code flags, and task type → default level (ADR 0020).
+# The only place model choices live; scripts call harness_claude_flags
+# (.harness/lib.sh) or .harness/model-flags.sh. Aliases by default, so a model
+# release is picked up without editing this file; pin a full model id on a
+# level once the ledger has calibrated it.
+#
+# Overrides, applied in this order after this file:
+#   .harness/models.local.conf   per project (project-owned, never synced)
+#   $HARNESS_MODELS_FILE         per machine (e.g. no Fable: R4="--model opus --effort xhigh")
+#
+# Rollout (decision 7): with HARNESS_MODEL_ROUTING=measure (the default) the
+# levels are computed and recorded but no flags are passed, so sessions keep
+# the account's default model; set HARNESS_MODEL_ROUTING=on (env file) to switch.
+# shellcheck shell=bash disable=SC2034
+
+R4="--model fable --effort high"   # design: specs, decisions no gate checks
+R3="--model opus --effort high"    # hard: ambiguous work, unclear diagnosis
+R2="--model sonnet --effort medium" # build: a well-specified, gate-verified task
+R1="--model haiku --effort medium"  # routine: a mechanical, local edit
+
+TASK_spec_author=R4      # /opsx:propose in an interactive or channel session
+TASK_spec_adjust=R4      # spec PR review comments (watcher, ADR 0017)
+TASK_impl=R2             # task loop (run-tasks.sh); tasks.md may override
+TASK_conflict=R3         # merge conflicts on a PR (watcher, ADR 0019)
+TASK_ci_fix=R2           # failing checks, clear cause (watcher, ADR 0019)
+TASK_ci_fix_retry=R3     # failing checks after a failed fix (watcher, ADR 0019)
+TASK_review_comments=R2  # owner comments on implementation/sync PRs (ADR 0019, 1b)
+TASK_diagnosis=R3        # explaining an escalation
+TASK_review=R3           # PR review
+TASK_routine=R1          # hand edits around sync and archive

package/templates/.harness/notify.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# Sends a harness notification: always to .harness/logs/notifications.log, and to
+# Telegram when HARNESS_TELEGRAM_BOT_TOKEN and HARNESS_TELEGRAM_CHAT_ID are set
+# (in the environment or in HARNESS_ENV_FILE, default ~/.config/harness/env).
+#
+# Usage: .harness/notify.sh <event> <message>
+#   event: started | task-passed | escalated | paused | resumed | done | error
+#
+# Never fails the caller: a notification problem is logged, not raised.
+set -uo pipefail
+
+event="${1:-info}"
+message="${2:-}"
+root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+project="$(basename "$root")"
+
+# HARNESS_NOTIFY_LOG: another log file, for events that belong to no project
+# (the watcher's runtime, ADR 0019).
+log_file="${HARNESS_NOTIFY_LOG:-$root/.harness/logs/notifications.log}"
+mkdir -p "$(dirname "$log_file")"
+printf '%s\t%s\t%s\n' "$(date -Iseconds)" "$event" "$message" >>"$log_file"
+
+env_file="${HARNESS_ENV_FILE:-$HOME/.config/harness/env}"
+if [[ -z "${HARNESS_TELEGRAM_BOT_TOKEN:-}" && -f "$env_file" ]]; then
+  # shellcheck source=/dev/null
+  . "$env_file"
+fi
+token="${HARNESS_TELEGRAM_BOT_TOKEN:-}"
+chat="${HARNESS_TELEGRAM_CHAT_ID:-}"
+[[ -n "$token" && -n "$chat" ]] || exit 0
+
+case "$event" in
+  started) icon="▶️" ;;
+  task-passed) icon="✅" ;;
+  done) icon="🎉" ;;
+  escalated) icon="🛑" ;;
+  paused) icon="⏸️" ;;
+  resumed) icon="🔁" ;;
+  error) icon="❌" ;;
+  *) icon="ℹ️" ;;
+esac
+
+if ! curl -fsS --max-time 15 "https://api.telegram.org/bot${token}/sendMessage" \
+  --data-urlencode "chat_id=${chat}" \
+  --data-urlencode "text=${icon} [${project}] ${message}" \
+  --data-urlencode "disable_web_page_preview=true" >/dev/null 2>&1; then
+  printf '%s\t%s\t%s\n' "$(date -Iseconds)" "notify-failed" "telegram sendMessage failed" >>"$log_file"
+fi
+exit 0

package/templates/.harness/openspec.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# Runs the project's pinned OpenSpec CLI (ADR 0013). Same arguments as `openspec`.
+#
+# Usage: .harness/openspec.sh <openspec args...>   e.g. validate my-change --strict
+#
+# OpenSpec is a devDependency with an exact version, so every machine and CI
+# run use the same CLI. There is no global install and no npx fallback: when
+# the package is missing or not pinned exactly, this fails and says how to fix it.
+set -euo pipefail
+
+# The version the harness was validated against. Projects may pin another one
+# deliberately; this only warns.
+validated="1.14.1"
+pkg="@fission-ai/openspec"
+
+die() { echo "openspec: $*" >&2; exit 1; }
+
+root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+[[ -f "$root/package.json" ]] || die "no package.json in $root"
+pin="$(grep -oE "\"$pkg\"[[:space:]]*:[[:space:]]*\"[^\"]*\"" "$root/package.json" | head -n1 | sed -E 's/.*"([^"]*)"$/\1/' || true)"
+[[ -n "$pin" ]] || die "$pkg is not a devDependency; add it with: pnpm add -D -E $pkg@$validated"
+[[ "$pin" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]] || die "$pkg must be pinned to an exact version, not '$pin': pnpm add -D -E $pkg@$validated"
+[[ "$pin" == "$validated" ]] || echo "openspec: note: $pkg $pin is pinned; the harness was validated with $validated" >&2
+
+bin="$root/node_modules/.bin/openspec"
+[[ -x "$bin" ]] || die "$bin not found; install dependencies first (pnpm install)"
+export OPENSPEC_TELEMETRY="${OPENSPEC_TELEMETRY:-0}"
+exec "$bin" "$@"

package/templates/.harness/pr-scope.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# Classifies a pull request for CI (ADR 0011, ADR 0013). Prints `spec_only=true`
+# or `spec_only=false`, ready to append to $GITHUB_OUTPUT.
+#
+# Usage: .harness/pr-scope.sh >>"$GITHUB_OUTPUT"
+#
+# spec_only=true when the event is a pull request and every changed file is under
+# openspec/: CI then validates the specs instead of running the DoD gates and the
+# heavy jobs. Pushes, and anything else, are never spec-only.
+#
+# A spec PR (head branch spec/<change-id>) may only change
+# openspec/changes/<change-id>/; otherwise this fails, which fails the job.
+#
+# Environment (set by GitHub Actions):
+#   GITHUB_EVENT_NAME  pull_request → classify; anything else → spec_only=false
+#   GITHUB_HEAD_REF    head branch of the pull request
+#   PR_SCOPE_BASE      commit to diff against (default HEAD^1: on a pull_request
+#                      run HEAD is the merge commit and HEAD^1 its base, so the
+#                      checkout needs fetch-depth: 2)
+set -euo pipefail
+
+if [[ "${GITHUB_EVENT_NAME:-}" != pull_request ]]; then
+  echo "spec_only=false"
+  exit 0
+fi
+
+changed="$(git diff --name-only "${PR_SCOPE_BASE:-HEAD^1}" HEAD)"
+head_ref="${GITHUB_HEAD_REF:-}"
+
+if [[ "$head_ref" == spec/* ]]; then
+  allowed="openspec/changes/${head_ref#spec/}/"
+  outside="$(grep -v "^$allowed" <<<"$changed" || true)"
+  if [[ -n "$outside" ]]; then
+    echo "::error::A spec PR ($head_ref) may only change $allowed. Changed outside it:" >&2
+    printf '%s\n' "$outside" >&2
+    exit 1
+  fi
+fi
+
+if [[ -n "$changed" ]] && ! grep -qv '^openspec/' <<<"$changed"; then
+  echo "spec_only=true"
+else
+  echo "spec_only=false"
+fi

package/templates/.harness/run-tasks.sh

@@ -0,0 +1,422 @@
+#!/usr/bin/env bash
+# Autonomous task loop for one OpenSpec change.
+#
+# For each pending task (`- [ ] ...`) in openspec/changes/<change-id>/tasks.md:
+#   1. run Claude Code headless in a fresh session, scoped to that task;
+#   2. run .harness/gates.sh independently of the agent;
+#   3. pass → mark the task done and make one commit;
+#      fail → retry with the gate output as feedback, up to N attempts;
+#      still failing → stop and escalate to a human.
+# Each attempt runs at a reasoning level (ADR 0020): the task's level (impl in
+# .harness/models.conf, or a <!-- level: Rn --> marker on the task line), twice,
+# then one level up per attempt (R2, R2, R3, R4). Attempts that changed nothing
+# climb only once. The level's --model/--effort are passed when
+# HARNESS_MODEL_ROUTING=on (measure mode only records the level).
+# Before the first task it installs the dependencies the spec declares
+# (.harness/deps.sh, ADR 0015) in their own commit; an agent that changes
+# dependency files escalates the run.
+#
+# Usage: .harness/run-tasks.sh <change-id> [--max-attempts N] [--open-pr] [--force] [--check]
+#
+# Only approved changes run: the change must be on the base branch, merged there
+# through its spec PR (ADR 0011), and the change files on the work branch must
+# match the approved ones (tasks.md checkboxes aside). Work happens on
+# change/<id>, created from the base branch; --open-pr links the spec PR.
+# --check runs the preconditions only (approval, autonomy, clean worktree) and exits.
+#
+# The loop runs in a git worktree of its own (ADR 0012), never in the checkout it
+# is started from: see harness_worktree in .harness/lib.sh for the location.
+# Dependencies are installed there on first use. State and logs stay in the main
+# checkout (.harness/state, .harness/logs). The worktree is removed once every
+# task is done; on escalation or pause it is kept for a human or the next run.
+#
+# Exit codes: 0 all tasks done, 2 a task escalated after N attempts,
+#             3 paused because the agent hit the account usage limit.
+#
+# Environment:
+#   HARNESS_BASE_BRANCH      branch holding approved specs (default main)
+#   HARNESS_WORKTREES_DIR    parent directory of the loop worktrees
+#   HARNESS_WORKTREE_SETUP   command run once in a new worktree (default: install
+#                            dependencies from the lockfile); HARNESS_MAIN_CHECKOUT
+#                            points at the main checkout, e.g. to copy a .env
+#   HARNESS_MAX_ATTEMPTS     attempts per task (default 4: the level ladder, ADR 0020)
+#   HARNESS_TASK_TIMEOUT     max seconds per agent session (default 1800)
+#   HARNESS_PERMISSION_MODE  claude --permission-mode (default acceptEdits)
+#   HARNESS_CLAUDE_ARGS      extra args for claude (experiments; models come from models.conf)
+#   HARNESS_COMMIT_TYPE      conventional commit type (default feat)
+set -euo pipefail
+
+usage() { sed -n '2,46p' "$0" | sed 's/^# \{0,1\}//'; exit "${1:-0}"; }
+die() { echo "run-tasks: $*" >&2; exit 1; }
+
+[[ $# -ge 1 ]] || usage 1
+[[ "$1" == "-h" || "$1" == "--help" ]] && usage 0
+change="$1"; shift
+
+max_attempts="${HARNESS_MAX_ATTEMPTS:-4}"
+timeout_s="${HARNESS_TASK_TIMEOUT:-1800}"
+permission_mode="${HARNESS_PERMISSION_MODE:-acceptEdits}"
+commit_type="${HARNESS_COMMIT_TYPE:-feat}"
+open_pr=0
+force=0
+check_only=0
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --max-attempts) max_attempts="$2"; shift 2 ;;
+    --open-pr) open_pr=1; shift ;;
+    --force) force=1; shift ;;
+    --check) check_only=1; shift ;;
+    *) die "unknown option: $1" ;;
+  esac
+done
+
+git rev-parse --git-dir >/dev/null 2>&1 || die "not inside a git repository"
+# shellcheck source-path=SCRIPTDIR source=lib.sh
+. "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+root="$(harness_root)"
+cd "$root"
+wt="$(harness_worktree "$change")"
+# Machine settings (skipped gates, TELEGRAM_STATE_DIR for the agent sessions)
+# also when run-tasks.sh is started directly instead of through loop.sh.
+harness_load_env
+
+change_dir="openspec/changes/$change"
+tasks="$change_dir/tasks.md"
+[[ -x .harness/gates.sh ]] || die ".harness/gates.sh missing or not executable"
+command -v claude >/dev/null || die "claude CLI not found"
+
+autonomy="$(cat .harness/autonomy 2>/dev/null || echo disabled)"
+if [[ "$autonomy" != "enabled" && $force -eq 0 ]]; then
+  die "autonomy is '$autonomy' (.harness/autonomy). Add characterization tests first, or pass --force."
+fi
+
+# The spec is approved when its spec PR is merged: the change is on the base
+# branch. Compare against the remote copy when there is one, so a stale local
+# branch neither hides an approval nor fakes one.
+base_branch="${HARNESS_BASE_BRANCH:-main}"
+base_ref="$base_branch"
+if git remote get-url origin >/dev/null 2>&1; then
+  git fetch -q origin "$base_branch" || die "cannot fetch origin/$base_branch"
+  base_ref="origin/$base_branch"
+fi
+git rev-parse -q --verify "$base_ref^{commit}" >/dev/null || die "base branch $base_ref not found"
+if ! git cat-file -e "$base_ref:$tasks" 2>/dev/null; then
+  die "change $change is not on $base_ref, so its spec is not approved. Open the spec PR from spec/$change and merge it first (ADR 0011)."
+fi
+
+branch="change/$change"
+if git rev-parse -q --verify "refs/heads/$branch" >/dev/null; then
+  start_ref="$branch"
+else
+  start_ref="$base_ref"
+fi
+if [[ -d "$wt" ]]; then
+  [[ "$(git -C "$wt" branch --show-current 2>/dev/null)" == "$branch" ]] \
+    || die "$wt exists but is not a worktree on $branch; remove it (git worktree remove) and re-run"
+  [[ -z "$(git -C "$wt" status --porcelain)" ]] \
+    || die "worktree $wt has uncommitted work (left by an escalation?). Finish or discard it there first."
+fi
+
+# The work branch implements exactly the approved spec: every change file
+# matches the base branch, except for the checkboxes the loop ticks in tasks.md.
+unchecked() { sed -E 's/^([[:space:]]*- )\[x\] /\1[ ] /'; }
+if ! git diff --quiet "$base_ref" "$start_ref" -- "$change_dir" ":(exclude)$tasks" \
+  || ! cmp -s <(git show "$base_ref:$tasks" | unchecked) <(git show "$start_ref:$tasks" 2>/dev/null | unchecked); then
+  die "$change_dir on $branch differs from the approved spec on $base_ref. Spec changes go through a new spec PR; then rebase $branch on $base_branch."
+fi
+
+if [[ $check_only -eq 1 ]]; then
+  echo "run-tasks: change $change is approved and ready to run on $branch in $wt."
+  exit 0
+fi
+
+# Work in the change's own worktree, so the checkout the loop was started from
+# (where specs are written) is never switched or cleaned under anyone's feet.
+if [[ ! -d "$wt" ]]; then
+  mkdir -p "$(dirname "$wt")"
+  if [[ "$start_ref" == "$branch" ]]; then
+    git worktree add -q "$wt" "$branch" \
+      || die "cannot check out $branch in $wt; if it is checked out elsewhere (git worktree list), switch that checkout away"
+  else
+    git worktree add -q --no-track -b "$branch" "$wt" "$base_ref" || die "cannot create worktree $wt"
+  fi
+  setup="${HARNESS_WORKTREE_SETUP:-}"
+  if [[ -z "$setup" ]]; then
+    if [[ -f "$wt/pnpm-lock.yaml" ]]; then setup="pnpm install --frozen-lockfile"
+    elif [[ -f "$wt/package-lock.json" ]]; then setup="npm ci"
+    fi
+  fi
+  if [[ -n "$setup" ]]; then
+    mkdir -p ".harness/logs/$change"
+    echo "==> worktree setup: $setup"
+    if ! (cd "$wt" && HARNESS_MAIN_CHECKOUT="$root" bash -c "$setup") >".harness/logs/$change/worktree-setup.log" 2>&1; then
+      # Without its dependencies the worktree is useless; the next run starts over.
+      git worktree remove --force "$wt"
+      die "worktree setup failed ($setup); see .harness/logs/$change/worktree-setup.log"
+    fi
+  fi
+  # A harness installed from the package (ADR 0021): the worktree gets the
+  # version its own lockfile pins, even when the install skipped "prepare".
+  if [[ -x "$wt/node_modules/.bin/harness" ]]; then
+    mkdir -p ".harness/logs/$change"
+    if ! (cd "$wt" && node_modules/.bin/harness install) >>".harness/logs/$change/worktree-setup.log" 2>&1; then
+      git worktree remove --force "$wt"
+      die "harness install failed in the worktree; see .harness/logs/$change/worktree-setup.log"
+    fi
+  fi
+fi
+
+log_dir="$root/.harness/logs/$change"
+mkdir -p "$log_dir" "$root/.harness/state"
+
+# Runner state for .harness/status.sh: key=value lines, rewritten on every step.
+state_file="$root/.harness/state/run-$change"
+run_status="running"
+cur_task_id=""
+cur_task=""
+cur_attempt=0
+attempt_started=""
+write_state() {
+  {
+    echo "status=$run_status"
+    echo "pid=$$"
+    echo "started=$run_started"
+    echo "task_id=$cur_task_id"
+    echo "task=$cur_task"
+    echo "attempt=$cur_attempt"
+    echo "max_attempts=$max_attempts"
+    echo "attempt_started=$attempt_started"
+    echo "updated=$(date +%s)"
+  } >"$state_file"
+}
+run_started="$(date +%s)"
+# Anything that ends the run without setting a final status was interrupted.
+trap '[[ "$run_status" == running ]] && run_status=interrupted; write_state' EXIT
+write_state
+cd "$wt"
+summary="$log_dir/summary.tsv"
+summary_header=$'timestamp\ttask\tattempt\tduration_s\tresult\tlevel\tmodel\teffort\tcost_usd\toutput_tokens\tcache_read_tokens'
+if [[ ! -f "$summary" ]]; then
+  printf '%s\n' "$summary_header" >"$summary"
+elif [[ "$(head -n1 "$summary")" == $'timestamp\ttask\tattempt\tduration_s\tresult' ]]; then
+  sed -i "1s/.*/$summary_header/" "$summary"   # older runs: same first columns, new ones empty
+fi
+
+next_task() { grep -n -m1 -E '^[[:space:]]*- \[ \] ' "$tasks" || true; }
+
+# Dependencies the approved spec declares (design.md "## Dependencies", ADR 0015)
+# are installed by the loop, never by the agent, in one commit before the tasks.
+# Anything deps.sh refuses (an undeclared change, a version conflict) escalates.
+dep_files=(package.json pnpm-lock.yaml pnpm-workspace.yaml)
+if [[ -x .harness/deps.sh && -f package.json ]]; then
+  if ! .harness/deps.sh install "$change_dir" >"$log_dir/deps.log" 2>&1; then
+    run_status="escalated"
+    echo "run-tasks: the declared dependencies could not be installed; escalating." >&2
+    tail -n 20 "$log_dir/deps.log" >&2
+    exit 2
+  fi
+  if [[ -n "$(git status --porcelain -- "${dep_files[@]}")" ]]; then
+    git add -- "${dep_files[@]}"
+    printf 'chore(%s): add the dependencies declared by the spec\n\nInstalled by the task loop from the "## Dependencies" section of\n%s/design.md (exact versions, no other dependency changed):\n\n%s\n' \
+      "$change" "$change_dir" "$(grep '^deps: added' "$log_dir/deps.log" | sed 's/^deps: added //')" | git commit -q -F -
+    echo "==> dependencies declared by the spec installed and committed"
+  fi
+fi
+
+build_prompt() {
+  local task="$1" feedback="$2"
+  cat <<EOF
+You are running inside the autonomous task loop of agent-harness.
+
+Change: $change (files in $change_dir/: proposal.md, design.md if present, specs/, tasks.md)
+Your task (exactly one):
+  $task
+
+Instructions:
+- Read the proposal, design and delta specs relevant to this task before coding.
+- Implement ONLY this task, following CLAUDE.md and .harness/standards/.
+- Add or update tests that prove the task's behaviour; write the failing test first.
+- Run .harness/gates.sh and iterate until it exits 0.
+- Do NOT edit files in $change_dir/: it is the approved spec. If it is wrong, stop and say so.
+- Do NOT edit tasks.md, do NOT commit, do NOT push. The loop does that.
+- Do NOT add, remove or update packages, and do NOT edit package.json, pnpm-lock.yaml or
+  pnpm-workspace.yaml: the loop already installed the dependencies the spec declares. If the
+  task needs a package the spec does not declare, stop and name it in your final message.
+- Never change what an existing test asserts to make it match the code. If an existing
+  test conflicts with the code, stop and explain the conflict in your final message.
+- If the task cannot be done as specified, stop and explain why in your final message.
+- All artifacts in English.
+EOF
+  if [[ -n "$feedback" ]]; then
+    cat <<EOF
+
+A previous attempt left work in the tree but the gates failed with:
+--------
+$feedback
+--------
+Continue from the current state and fix these failures.
+EOF
+  fi
+}
+
+# Conventional-commit summary from a task line: drop the task id and backticks,
+# keep the first sentence, and cut at a word boundary to fit 72 chars with the prefix.
+commit_summary() {
+  local text max
+  text="$(sed -E -e 's/^[0-9]+(\.[0-9]+)*[[:space:]]+//' -e 's/`//g' -e 's/\. .*$//' -e 's/\.$//' <<<"$1")"
+  max=$(( 72 - ${#commit_type} - ${#change} - 4 ))
+  if (( ${#text} > max )); then
+    text="${text:0:max-3}"
+    text="${text% *}..."
+  fi
+  printf '%s' "$text"
+}
+
+untrusted_warned=0
+warn_if_untrusted() {
+  if [[ $untrusted_warned -eq 0 ]] && grep -q "workspace has not been trusted" "$1" 2>/dev/null; then
+    echo "    warning: Claude Code ignores .claude/settings.json permissions in this untrusted" >&2
+    echo "             workspace; the agent cannot run gates itself. Trust it once interactively." >&2
+    untrusted_warned=1
+  fi
+}
+
+# record <task> <attempt> <duration> <result>: one summary row for the attempt,
+# with its level, model, effort, cost and tokens (ADR 0020); the same session
+# also goes to the machine-wide ledger.
+record() {
+  local usage effort model cost out cache
+  effort="$(harness_flag_value "${level_flags:-}" --effort)"
+  usage="$(harness_record_usage "$(basename "$root")" "$change" impl "${level:-}" "${effort:-default}" "$2" "$4" \
+    "$log_dir/task-$1-attempt-$2.json")"
+  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\n' "$(date -Iseconds)" "$1" "$2" "$3" "$4" \
+    "${level:-}" "$model" "${effort:-default}" "$cost" "$out" "$cache" >>"$summary"
+}
+
+while line="$(next_task)"; [[ -n "$line" ]]; do
+  ln="${line%%:*}"
+  task="$(sed -E 's/^[[:space:]]*- \[ \] //' <<<"${line#*:}")"
+  # The spec author's level for this task (ADR 0020), stripped from the text
+  # that becomes the prompt and the commit.
+  level_override="$(grep -oE '<!--[[:space:]]*level:[[:space:]]*R[1-4][[:space:]]*-->' <<<"$task" | grep -oE 'R[1-4]' || true)"
+  task="$(sed -E 's/[[:space:]]*<!--[[:space:]]*level:[^>]*-->//g' <<<"$task")"
+  base_level="$(harness_task_level impl "$level_override")" || base_level="R2"
+  gate_fails=0 nochange=0 levels_tried=""
+  task_id="$(grep -oE '^[0-9]+(\.[0-9]+)*' <<<"$task" || echo "L$ln")"
+  summary_line="$(commit_summary "$task")"
+  feedback=""
+  echo "==> task $task_id: $task (level $base_level${level_override:+, set by the spec})"
+
+  done_ok=0
+  for (( attempt = 1; attempt <= max_attempts; attempt++ )); do
+    # Two attempts at the task's level, then one level up per failure; attempts
+    # that changed nothing climb only once (they count as at most two failures).
+    fails=$(( gate_fails + (nochange > 2 ? 2 : nochange) ))
+    level="$(harness_level_climb "$base_level" $(( fails > 1 ? fails - 1 : 0 )))"
+    level_flags="$(harness_level_flags "$level")"
+    [[ " $levels_tried " == *" $level "* ]] || levels_tried="${levels_tried:+$levels_tried }$level"
+    echo "    attempt $attempt/$max_attempts at $level${level_flags:+ ($level_flags)}"
+    cur_task_id="$task_id"; cur_task="$summary_line"; cur_attempt="$attempt"; attempt_started="$(date +%s)"
+    write_state
+    start=$(date +%s)
+    # shellcheck disable=SC2086
+    build_prompt "$task" "$feedback" | timeout "$timeout_s" "${HARNESS_CLAUDE[@]}" -p \
+      --output-format json \
+      --permission-mode "$permission_mode" \
+      --disallowedTools "Bash(git commit:*)" "Bash(git push:*)" "Bash(.harness/spec-pr.sh:*)" \
+        "Bash(pnpm add:*)" "Bash(pnpm remove:*)" "Bash(pnpm update:*)" "Bash(npm install:*)" \
+      ${level_flags} ${HARNESS_CLAUDE_ARGS:-} \
+      >"$log_dir/task-$task_id-attempt-$attempt.json" 2>&1 || true
+
+    warn_if_untrusted "$log_dir/task-$task_id-attempt-$attempt.json"
+
+    # An account usage limit ends the session early; retrying only burns the
+    # remaining attempts on the same error. Pause and let a human resume.
+    if grep -qiE "hit your (session|usage) limit|usage limit reached" "$log_dir/task-$task_id-attempt-$attempt.json"; then
+      record "$task_id" "$attempt" "$(( $(date +%s) - start ))" paused
+      run_status="paused"
+      # The interrupted attempt left partial, unverified work: discard it.
+      git checkout -- . && git clean -fdq
+      echo "run-tasks: the agent session hit the account usage limit; pausing." >&2
+      echo "  Task $task_id is not done; its partial attempt was discarded. Re-run after the limit resets." >&2
+      exit 3
+    fi
+
+    # The agent must not touch the approved spec; restoring tasks.md also keeps
+    # its line numbers valid.
+    git checkout -- "$change_dir"
+    git clean -fdq -- "$change_dir"
+
+    # Only the spec declares dependencies: an agent that changed them needs a
+    # package the spec does not have. Retrying cannot fix that; a human decides.
+    if [[ -n "$(git status --porcelain -- "${dep_files[@]}")" ]]; then
+      record "$task_id" "$attempt" "$(( $(date +%s) - start ))" deps
+      run_status="escalated"
+      echo "run-tasks: task $task_id changed dependency files; undeclared dependencies need a spec change." >&2
+      echo "  Work in progress is left uncommitted on branch $branch in $wt." >&2
+      exit 2
+    fi
+
+    # A task that changed nothing is not done, even if the gates pass on the old code.
+    if [[ -z "$(git status --porcelain -- . ":(exclude)$tasks")" ]]; then
+      record "$task_id" "$attempt" "$(( $(date +%s) - start ))" fail
+      feedback="The previous attempt changed no files, so the task was not implemented. Implement it."
+      nochange=$(( nochange + 1 ))
+      echo "    FAIL (no changes)"
+      continue
+    fi
+
+    if gate_out="$(.harness/gates.sh 2>&1)"; then
+      record "$task_id" "$attempt" "$(( $(date +%s) - start ))" pass
+      sed -i "${ln}s/- \[ \]/- [x]/" "$tasks"
+      git add -A
+      printf '%s(%s): %s\n\nTask %s of OpenSpec change %s, completed by the task loop:\n\n%s\n' \
+        "$commit_type" "$change" "$summary_line" "$task_id" "$change" "$task" | fold -s -w 72 | git commit -q -F -
+      echo "    PASS → committed"
+      if [[ -x .harness/notify.sh ]]; then
+        .harness/notify.sh task-passed "$change: task $task_id passed — $summary_line"
+      fi
+      done_ok=1
+      break
+    fi
+
+    record "$task_id" "$attempt" "$(( $(date +%s) - start ))" fail
+    printf '%s\n' "$gate_out" >"$log_dir/task-$task_id-attempt-$attempt.gates.log"
+    feedback="$(tail -n 120 <<<"$gate_out")"
+    gate_fails=$(( gate_fails + 1 ))
+    echo "    FAIL"
+  done
+
+  if [[ $done_ok -eq 0 ]]; then
+    run_status="escalated"
+    echo "run-tasks: task $task_id failed $max_attempts attempts (levels $levels_tried); escalating." >&2
+    echo "  Work in progress is left uncommitted on branch $branch in $wt." >&2
+    echo "  Logs: $log_dir/task-$task_id-attempt-*" >&2
+    exit 2
+  fi
+done
+
+run_status="done"
+cur_task_id=""; cur_task=""; cur_attempt=0; attempt_started=""
+echo "run-tasks: all tasks in $tasks are done."
+
+if [[ $open_pr -eq 1 ]]; then
+  command -v gh >/dev/null || die "gh CLI not found; cannot open PR"
+  git push -u origin "$branch"
+  spec_pr="$(gh pr list --state merged --head "spec/$change" --json url --jq '.[0].url // empty' 2>/dev/null || true)"
+  body="$(mktemp)"
+  {
+    echo "Implements OpenSpec change \`$change\`, approved in ${spec_pr:-its spec PR (branch spec/$change; not found)}."
+    echo
+    cat "$change_dir/proposal.md"
+  } >"$body"
+  gh pr create --head "$branch" --base "$base_branch" --title "change: $change" --body-file "$body"
+  rm -f "$body"
+fi
+
+# Everything is committed on $branch: the worktree is no longer needed.
+cd "$root"
+git worktree remove --force "$wt"
+echo "run-tasks: removed worktree $wt (branch $branch keeps the work)."
+