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

package/templates/.harness/loop.sh

@@ -0,0 +1,169 @@
+#!/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> [--after-task]
+#        .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
+#   4  stopped between two tasks (`stop --after-task`) → notify; restart later
+# 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).
+#
+# Started from inside a systemd unit (the spec PR watcher's oneshot service, any
+# other service), the supervisor gets a transient scope of its own
+# (systemd-run --user --scope, unit harness-loop-<project>-<change>-<time>):
+# setsid alone keeps it in the unit's cgroup, and systemd kills the cgroup when
+# the unit ends. `status` reports a supervisor that died before finishing.
+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; }
+
+# scope_prefix <change>: the systemd-run prefix that puts the supervisor in a
+# scope of its own when this runs inside a systemd unit (INVOCATION_ID), unless
+# it already is in a harness-loop scope; nothing otherwise or without a user
+# manager to talk to. It runs in a subshell (mapfile < <(...)), so the caller
+# must have XDG_RUNTIME_DIR set already: an export here would never reach the
+# systemd-run of the parent ("Failed to connect to bus").
+scope_prefix() {
+  [[ -n "${INVOCATION_ID:-}" ]] || return 0
+  grep -q '/harness-loop-[^/]*\.scope$' /proc/self/cgroup 2>/dev/null && return 0
+  command -v systemd-run >/dev/null 2>&1 || return 0
+  systemd-run --user --scope --quiet true >/dev/null 2>&1 || return 0
+  printf '%s\n' systemd-run --user --scope --quiet --collect \
+    --unit "harness-loop-$(basename "$root" | tr -c 'A-Za-z0-9_.\n-' '-')-$1-$(date +%s)" --
+}
+
+# close_inherited_fds: the supervisor outlives whoever started it, and a lock
+# fd it inherited (the spec PR watcher's, a project lock) would stay locked for
+# as long as the loop runs. Everything above stderr is closed.
+close_inherited_fds() {
+  local f fd
+  for f in /proc/$$/fd/*; do
+    fd="${f##*/}"
+    [[ "$fd" =~ ^[0-9]+$ ]] && (( fd > 2 )) && eval "exec $fd>&-" 2>/dev/null
+  done
+  return 0
+}
+
+supervise() {
+  local change="$1"; shift
+  close_inherited_fds
+  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" ;;
+      4)
+        .harness/notify.sh info "Change $change stopped at the end of a task on request; restart with .harness/loop.sh start $change"
+        break ;;
+      *)
+        .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)"
+    rm -f "$state_dir/stop-$change"   # a stop requested for an earlier run
+    # A systemd unit (a service) has no XDG_RUNTIME_DIR; the user bus is there.
+    [[ -z "${INVOCATION_ID:-}" ]] || export XDG_RUNTIME_DIR="${XDG_RUNTIME_DIR:-/run/user/$(id -u)}"
+    mapfile -t scope < <(scope_prefix "$change")
+    setsid nohup "${scope[@]}" "$0" __supervise "$change" "$@" >/dev/null 2>&1 </dev/null &
+    echo $! >"$(pid_file "$change")"
+    # Do not return before the supervisor is in its scope: the unit that called
+    # this may end right after, and its cgroup is killed with whatever is left.
+    if (( ${#scope[@]} )); then
+      for (( i = 0; i < 100; i++ )); do
+        grep -q '/harness-loop-[^/]*\.scope$' "/proc/$!/cgroup" 2>/dev/null && break
+        kill -0 $! 2>/dev/null || break
+        sleep 0.1
+      done
+      grep -q '/harness-loop-[^/]*\.scope$' "/proc/$!/cgroup" 2>/dev/null \
+        || echo "loop: warning: the supervisor is not in its own systemd scope; it may stop with the calling unit" >&2
+    fi
+    echo "loop: started $change in the background (pid $!). Follow it with .harness/loop.sh status $change"
+    ;;
+  __supervise)
+    supervise "$@" ;;
+  status)
+    if [[ -n "${1:-}" ]]; then
+      if running "$1"; then
+        echo "supervisor: running (pid $(cat "$(pid_file "$1")"))"
+      elif [[ -f "$(pid_file "$1")" ]]; then
+        # The supervisor removes its pid file when it finishes, even on errors.
+        echo "supervisor: DIED before finishing (pid $(cat "$(pid_file "$1")"), no final notification)." \
+          "Last runner and worktree-setup logs are in .harness/logs/$1/; restart with .harness/loop.sh start $1"
+      else
+        echo "supervisor: not running"
+      fi
+      .harness/status.sh "$1"
+    else
+      .harness/status.sh
+    fi ;;
+  stop)
+    change="${1:-}"; [[ -n "$change" ]] || die "usage: loop.sh stop <change-id> [--after-task]"
+    running "$change" || die "no loop running for $change"
+    if [[ "${2:-}" == --after-task ]]; then
+      # Graceful: the task in progress finishes and is committed, then run-tasks
+      # exits between tasks and the supervisor ends (the worktree is kept).
+      touch "$state_dir/stop-$change"
+      echo "loop: $change will stop at the end of its current task"
+      exit 0
+    fi
+    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,24p' "$0" | sed 's/^# \{0,1\}//'; exit 1 ;;
+esac

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,31 @@
+# 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_archive_fix=R2      # editorial split of a merged requirement over 500 characters (ADR 0022)
+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