autonomous-sdlc-harness 0.6.1 → 0.6.3

package/templates/github/workflows/harness-trigger.yml

@@ -33,7 +33,8 @@
 #     the authority.
 #
 # WHO CAN START A RUN. `remote-run.sh`'s `trigger` paragraph owns the check —
-# the labeller, bots and HARNESS_TRIGGER_ALLOWED_BOTS, the permission call —
+# the labeller, bots and HARNESS_TRIGGER_ALLOWED_BOTS, the permission call, the
+# allow-list HARNESS_RUN_ACTORS, and the `repository_dispatch` sender check —
 # and the order its refusals are made in. Nothing here pre-filters on it.
 #
 # THE PERMISSIONS, declared because the default token may be read-only
@@ -69,6 +70,7 @@
 #                                     HARNESS_REMOTE_STOP, HARNESS_TRIGGER_LABEL,
 #                                     DEFAULT_TRIGGER_LABEL (`sdlc-harness`),
 #                                     HARNESS_TRIGGER_ALLOWED_BOTS,
+#                                     HARNESS_RUN_ACTORS,
 #                                     TRIGGER_DISPATCH_EVENT_TYPE (`harness-task`)
 #   cli/src/config/model.ts           DEFAULTS.scriptsDir
 #
@@ -112,6 +114,7 @@ jobs:
       HARNESS_REMOTE_SLUG: ${{ github.repository }}
       HARNESS_TRIGGER_LABEL: ${{ vars.HARNESS_TRIGGER_LABEL || 'sdlc-harness' }}
       HARNESS_TRIGGER_ALLOWED_BOTS: ${{ vars.HARNESS_TRIGGER_ALLOWED_BOTS }}
+      HARNESS_RUN_ACTORS: ${{ vars.HARNESS_RUN_ACTORS }}
     steps:
       - name: Check out the default branch
         uses: actions/checkout@v5

package/templates/scripts/autonomous-watcher.sh

@@ -357,9 +357,21 @@
 #     restored bundle's under HARNESS_INPUT_CHAIN above 0, else at this run's own
 #     `createdAt` (`remote-run.sh run-created-at "$GITHUB_RUN_ID"`), else at
 #     HARNESS_JOB_STARTED_EPOCH — NEVER at the job's own start alone, which
-#     would lose a pause sent while the job was queued. Each successful poll
-#     advances it to the epoch taken just before its query; a failed poll
-#     advances nothing and pauses nothing.
+#     would lose a pause sent while the job was queued. That starting bound is
+#     the job's FLOOR. The verb's exit decides: `0` a pause, `5` none — each
+#     advances the bound to the larger of the floor and the epoch taken just
+#     before the query less CONTROL_POLL_OVERLAP_SECS, so a run the listing
+#     shows late is still read; anything else, `1` included, is a failed poll,
+#     which advances nothing and pauses nothing. Every poll logs one line,
+#     `job: control poll of '<branch>' since <since> (exit <rc>): <last line>`.
+#   * THE RUNNER WAIT: the job logs HARNESS_JOB_STARTED_EPOCH less this run's
+#     `createdAt` — read once per job, the same read the control poll's
+#     starting bound takes. On a re-run attempt (`GITHUB_RUN_ATTEMPT` above 1)
+#     that `createdAt` is the first attempt's, so the wait is not measured and
+#     no note is added. A wait of at least RUNNER_WAIT_NOTE_SECS is noted on
+#     the `resumed` comment the job posts as it starts, never on a later
+#     automatic resume's. The budget already starts at
+#     HARNESS_JOB_STARTED_EPOCH, so a wait costs no budget.
 #   * THE DECISION, when the run leaves `running`: `paused` for `budget` ->
 #     `continue`; for `user` -> `stop`; by the usage gate (`usage`) -> a lost
 #     `usage_resume_at` is first given the gate's fallback and reported as
@@ -396,6 +408,19 @@
 #     issue and moves its state label when `forge` is `github`; `autonomous-notify.sh`
 #     is unchanged, and `completed` is reported by the workflow's `deliver` step
 #     after the push.
+#   * THE PROGRESS PASS (job_progress_pass): every `running` pass reads the
+#     flow-progress ledger the flow pushes in this checkout through
+#     lib/harness-run-lib.sh's `hr_ledger_phases`, and calls `remote-run.sh
+#     report progress <branch>` when that reading differs from the last one
+#     this job reported, and once more when the job ends, so a tick landing
+#     after the last poll is still reported. It reads nothing from GitHub to
+#     decide and keeps no state across jobs: the render is deterministic and
+#     `report progress` edits the comment only when its body differs, so a
+#     job's first pass syncs once and a budget continuation posts nothing new
+#     unless a phase moved — consistent with `docs/github-run-control.md` ->
+#     §5's *The budget is silent*, because what is posted is a phase, not the
+#     continuation. What is posted, where, and whether at all is `report
+#     progress`'s to decide; the watcher decides only when to call it.
 #   * THE INTERACTIVE-TEST PHASE IS SKIPPED, not run: a runner has no browser
 #     wiring, application dependencies or QA credentials for it. With
 #     `phases.qa` true, the task and user_review launch prompts gain one clause
@@ -686,8 +711,14 @@
 #                    A stub writing PAUSE_ACK unrequested, then exiting 0 ->
 #                    one auto-resume, `job: completed stop`; a stub ending
 #                    `exit 2` with REMOTE_AUTO_RESUME_DELAY_SECS=0 -> launched
-#                    1 + REMOTE_AUTO_RESUME_MAX times, `job: failed stop`
-#   remote drop   `a drop`'s fixture, with "$d"'s own files committed and pushed
+#                    1 + REMOTE_AUTO_RESUME_MAX times, `job: failed stop`. A
+#                    stub writing a task ledger at
+#                    "$d/sdlc-harness/flow_progress/feat_x_progress.md" and
+#                    sleeping past a few polls, the ledger never ticked ->
+#                    the watcher log carries one `remote-run.sh: report:` line
+#                    from the first pass and one from the job's end, none
+#                    between
+#   remote drop  `a drop`'s fixture, with "$d"'s own files committed and pushed
 #                 to origin's default branch, `"execution":{"target":
 #                 "github-actions"}` in its harness.config.json, and
 #                 HARNESS_GH_CLI pointed at a recorder (see remote-run.sh's
@@ -1111,6 +1142,11 @@ USAGE_WARNING_STREAK=0
 # none of them. How often the control poll asks GitHub for a `harness pause
 # <branch>` run — each poll is one `gh run list`.
 REMOTE_CONTROL_POLL_SECS="${REMOTE_CONTROL_POLL_SECS:-60}"
+# Not a tunable. How far each control poll's next lower bound reaches back:
+# GitHub's run listing is eventually consistent, so the window re-reads the last
+# five minutes. A marker seen twice is harmless — JOB_USER_PAUSE_DROPPED drops
+# PAUSE once per job.
+CONTROL_POLL_OVERLAP_SECS=300
 # The longest usage-reset wait a HOSTED job sits through rather than handing
 # the run to the resume poller, since a hosted job bills for the minutes it
 # waits. A self-hosted job waits for any reset before its deadline.
@@ -1121,6 +1157,9 @@ REMOTE_AUTO_RESUME_MAX="${REMOTE_AUTO_RESUME_MAX:-2}"
 # How long job mode waits before each of those resumes, so a transient outage
 # has time to clear.
 REMOTE_AUTO_RESUME_DELAY_SECS="${REMOTE_AUTO_RESUME_DELAY_SECS:-300}"
+# The runner wait at or above which the job's `resumed` comment says so (see
+# THE RUNNER WAIT in the header).
+RUNNER_WAIT_NOTE_SECS=300
 
 # JOB MODE (see the header). Assigned HERE, after the override channel and every
 # tunable default, so neither the file nor an inherited value can turn a
@@ -1129,9 +1168,18 @@ REMOTE_AUTO_RESUME_DELAY_SECS="${REMOTE_AUTO_RESUME_DELAY_SECS:-300}"
 JOB_MODE=0
 # Job mode's pass state, for the same reason: when the control poll last ran,
 # whether each pass has already dropped its one PAUSE, and the job's start
-# (HARNESS_JOB_STARTED_EPOCH, else when run_job began).
+# (HARNESS_JOB_STARTED_EPOCH, else when run_job began), and the control poll's
+# starting bound, below which no later bound falls.
 JOB_START_EPOCH=0
+JOB_CONTROL_FLOOR=0
+# This run's `createdAt`, read once per job (empty when unread), and the note
+# job_report adds to a `resumed` report when the runner wait was long.
+JOB_RUN_CREATED_AT=""
+JOB_RUNNER_WAIT_NOTE=""
 LAST_CONTROL_POLL=0
+# The ledger reading the progress pass last reported; empty, so a job's first
+# pass always reports once.
+JOB_PROGRESS_LAST=""
 JOB_USER_PAUSE_DROPPED=0
 JOB_BUDGET_PAUSE_DROPPED=0
 if [ "${1:-}" = "job" ]; then
@@ -1185,16 +1233,21 @@ notify() {
 
 # job_report <event> <branch> [<log>] — the only route to GitHub. The detail is
 # withheld: it names local slash commands, and `report` words its comment from
-# the registry record itself.
+# the registry record itself. A `resumed` report carries JOB_RUNNER_WAIT_NOTE
+# when it is set.
 job_report() {
+  local note=()
   if [ ! -r "$REMOTE_RUN" ]; then
     log "notify: '$REMOTE_RUN' is not readable — '${1:-?}' event for '${2:-?}' not reported on GitHub"
     return 0
   fi
+  if [ "$1" = "resumed" ] && [ -n "$JOB_RUNNER_WAIT_NOTE" ]; then
+    note=(--note "$JOB_RUNNER_WAIT_NOTE")
+  fi
   if [ -n "${3:-}" ]; then
-    bash "$REMOTE_RUN" report "$1" "$2" --repo "$MAIN_REPO" >>"$3" 2>&1 || true
+    bash "$REMOTE_RUN" report "$1" "$2" ${note[@]+"${note[@]}"} --repo "$MAIN_REPO" >>"$3" 2>&1 || true
   else
-    bash "$REMOTE_RUN" report "$1" "$2" --repo "$MAIN_REPO" >/dev/null 2>&1 || true
+    bash "$REMOTE_RUN" report "$1" "$2" ${note[@]+"${note[@]}"} --repo "$MAIN_REPO" >/dev/null 2>&1 || true
   fi
 }
 
@@ -1330,11 +1383,11 @@ job_report() {
 #                       0, else `0` — so ANY USER ACTION (a drop, an answer, a
 #                       resume: each a chain-0 dispatch) resets it and restores
 #                       the full allowance
-#   control_polled_at   job mode only: the epoch second up to which the job has
-#                       checked for a `harness pause <branch>` run — the lower
-#                       bound of the next control poll, this job's or the next
-#                       chained one's. Set at start (see JOB MODE) and advanced
-#                       by every successful poll
+#   control_polled_at   job mode only: the lower bound of the next control poll,
+#                       this job's or the next chained one's — set at start (see
+#                       JOB MODE), and after each successful poll the larger of
+#                       that starting bound and the epoch before the query less
+#                       CONTROL_POLL_OVERLAP_SECS
 #   pause_note_stale    job mode only: `1` when a `pause` job's restored
 #                       `status.json` was not `paused` or named another engine,
 #                       so spawn_engine's pause-resume prompt says there is no
@@ -4022,6 +4075,30 @@ job_int() {
   printf '%s\n' "$((10#$1))"
 }
 
+# job_runner_wait — the job's one `run-created-at` read, into JOB_RUN_CREATED_AT,
+# then THE RUNNER WAIT's log line and JOB_RUNNER_WAIT_NOTE (the header).
+job_runner_wait() {
+  local wait mins
+  if [ -n "${GITHUB_RUN_ID:-}" ]; then
+    JOB_RUN_CREATED_AT="$(job_int "$(bash "$REMOTE_RUN" run-created-at "$GITHUB_RUN_ID" --repo "$MAIN_REPO" 2>>"$WATCHER_LOG")")" || JOB_RUN_CREATED_AT=""
+  fi
+  if [ -z "$JOB_RUN_CREATED_AT" ]; then
+    log "job: this run's createdAt could not be read — the runner wait is unknown"
+    return 0
+  fi
+  if [ "${GITHUB_RUN_ATTEMPT:-1}" != 1 ]; then
+    log "job: run attempt ${GITHUB_RUN_ATTEMPT} — this run's createdAt is its first attempt's, so the runner wait is not measured"
+    return 0
+  fi
+  wait=$((JOB_START_EPOCH - JOB_RUN_CREATED_AT))
+  [ "$wait" -ge 0 ] || wait=0
+  log "job: waited ${wait}s for a runner (run created $JOB_RUN_CREATED_AT, job started $JOB_START_EPOCH)"
+  if [ "$wait" -ge "$RUNNER_WAIT_NOTE_SECS" ]; then
+    mins=$(((wait + 59) / 60))
+    JOB_RUNNER_WAIT_NOTE="GitHub took $mins minutes to start this job, so nothing moved until then."
+  fi
+}
+
 # job_start_control_bound <branch> <remote_status> — the control poll's first
 # lower bound, in the order the header's JOB MODE block states.
 job_start_control_bound() {
@@ -4029,35 +4106,40 @@ job_start_control_bound() {
   if [ "$HARNESS_INPUT_CHAIN" -gt 0 ] && [ -f "$remote_status" ]; then
     bound="$(job_int "$(hr_remote_status_get "$remote_status" control_polled_at)")" || bound=""
   fi
-  if [ -z "$bound" ] && [ -n "${GITHUB_RUN_ID:-}" ]; then
-    bound="$(job_int "$(bash "$REMOTE_RUN" run-created-at "$GITHUB_RUN_ID" --repo "$MAIN_REPO" 2>>"$WATCHER_LOG")")" || bound=""
-  fi
+  [ -n "$bound" ] || bound="$JOB_RUN_CREATED_AT"
   if [ -z "$bound" ]; then
     bound="$JOB_START_EPOCH"
     log "job: could not read this run's createdAt — the control poll starts from the job's start ($bound)"
   fi
+  JOB_CONTROL_FLOOR="$bound"
   registry_set "$branch" control_polled_at "$bound"
 }
 
 # job_control_poll <branch> <state_abs> <remote_status> — the `user` pass.
+# Exit map of `pause-requested`: 0 a pause, 5 none, anything else a failed poll
+# that neither moves the bound nor pauses.
 job_control_poll() {
-  local branch="$1" state_abs="$2" remote_status="$3" now since before rc
+  local branch="$1" state_abs="$2" remote_status="$3" now since before rc out next
   [ "$JOB_USER_PAUSE_DROPPED" = "0" ] || return 0
   now="$(date +%s)"
   [ $((now - LAST_CONTROL_POLL)) -ge "$REMOTE_CONTROL_POLL_SECS" ] || return 0
   LAST_CONTROL_POLL="$now"
   since="$(job_int "$(registry_get "$branch" control_polled_at)")" || since="$JOB_START_EPOCH"
   before="$(date +%s)"
-  bash "$REMOTE_RUN" pause-requested "$branch" "$since" --repo "$MAIN_REPO" >>"$WATCHER_LOG" 2>&1
+  out="$(bash "$REMOTE_RUN" pause-requested "$branch" "$since" --repo "$MAIN_REPO" 2>&1)"
   rc=$?
+  [ -z "$out" ] || printf '%s\n' "$out" >>"$WATCHER_LOG"
+  log "job: control poll of '$branch' since $since (exit $rc): $(printf '%s\n' "$out" | awk 'NF { l = $0 } END { print l }')"
   case "$rc" in
-    0 | 1) ;;
+    0 | 5) ;;
     *)
       log "job: the control poll for '$branch' failed (exit $rc) — not pausing; control_polled_at stays $since"
       return 0
       ;;
   esac
-  registry_set "$branch" control_polled_at "$before"
+  next=$((before - CONTROL_POLL_OVERLAP_SECS))
+  [ "$next" -ge "$JOB_CONTROL_FLOOR" ] || next="$JOB_CONTROL_FLOOR"
+  registry_set "$branch" control_polled_at "$next"
   if [ "$rc" = "0" ]; then
     JOB_USER_PAUSE_DROPPED=1
     registry_set "$branch" pause_reason user
@@ -4080,6 +4162,17 @@ job_budget_pass() {
   log "job: ${after}s of the hosted time budget have passed — dropped PAUSE (reason budget)"
 }
 
+# job_progress_pass <branch> <state_abs> [final] — THE PROGRESS PASS (the
+# header's JOB MODE block). `final` reports even an unchanged reading.
+job_progress_pass() {
+  local branch="$1" state_abs="$2" line
+  [ "$JOB_MODE" = "1" ] || return 0
+  line="$(hr_ledger_phases "$state_abs/flow_progress/${branch}_progress.md")" || return 0
+  [ "$line" != "$JOB_PROGRESS_LAST" ] || [ "${3:-}" = "final" ] || return 0
+  JOB_PROGRESS_LAST="$line"
+  bash "$REMOTE_RUN" report progress "$branch" --repo "$MAIN_REPO" >>"$WATCHER_LOG" 2>&1 || true
+}
+
 # job_usage_wait_ok <branch> — 0 when a usage pause is waited out in the job;
 # leaves usage_resume_at_var's USAGE_RESUME_AT and USAGE_RESUME_REPAIRED set.
 # With no usable usage_resume_at: `paused_by=usage` still set means the value was
@@ -4145,6 +4238,7 @@ run_job() {
   local prev_status="" prev_engine="" aside_rc
 
   JOB_START_EPOCH="$(job_int "${HARNESS_JOB_STARTED_EPOCH:-}")" || JOB_START_EPOCH="$(date +%s)"
+  job_runner_wait
   state_rel="$(run_state_dir "$worktree")" || fatal "job: the state directory in '$worktree' is unresolvable"
   state_abs="$worktree/$state_rel"
   clar_dir="$state_abs/clarifications/$branch"
@@ -4248,6 +4342,10 @@ run_job() {
       ;;
   esac || registry_set "$branch" status failed
 
+  # The runner-wait note belongs to the job's own start: a later automatic
+  # resume's `resumed` comment never carries it (THE RUNNER WAIT in the header).
+  JOB_RUNNER_WAIT_NOTE=""
+
   # The supervision loop: the header's JOB MODE block states each decision.
   local status reason ra when decision="stop" detail="" usage_waiting=0 restarts
   local wait_ok=1 usage_wait_start=0 usage_wait_ra=0
@@ -4263,6 +4361,7 @@ run_job() {
         [ "$(registry_get "$branch" status)" = "running" ] || continue
         job_control_poll "$branch" "$state_abs" "$remote_status"
         job_budget_pass "$branch" "$state_abs"
+        job_progress_pass "$branch" "$state_abs"
         ;;
       paused)
         reason="$(registry_get "$branch" pause_reason)"
@@ -4354,6 +4453,7 @@ run_job() {
   [ "$final" = "paused" ] || registry_set "$branch" pause_reason ""
   [ -n "$detail" ] || detail="the run ended $final in this job"
   [ "$final" != "failed" ] || job_report failed "$branch" "$log_path"
+  job_progress_pass "$branch" "$state_abs" final
   job_write_status "$branch" "$remote_status" "$decision" "$detail"
   echo "job: $final $decision"
   exit 0

package/templates/scripts/lib/harness-run-lib.sh

@@ -5,7 +5,9 @@
 # routes an inbox filename to its engine and branch (`hr_inbox_route_var`),
 # derives a branch name from a title (`hr_derive_branch`), judges whether a
 # path lies strictly inside the state directory's scratch directory
-# (`hr_scratch_path_var`), places a dropped
+# (`hr_scratch_path_var`), answers whether the progress comment is on
+# (`hr_progress_comments`) and which main phases a flow-progress ledger records
+# as through (`hr_ledger_phases`), places a dropped
 # artifact in a working copy and commits and pushes it, and derives the
 # anchors (main checkout, work root, worktree directory, repo slug,
 # state-dir paths) the scripts would otherwise each re-derive slightly
@@ -87,7 +89,10 @@
 #      file is ever removed.
 #   4. THE ARTIFACT PLACEMENT writes one artifact into a working copy. Fence:
 #      the caller-named `<worktree>/<rel>`, its parent directories and that
-#      path's index entry, plus whatever the two caller-named wrappers do.
+#      path's index entry, plus whatever the two caller-named wrappers do, plus
+#      one write of its own: `hr_push_landed`'s fetch, which force-writes
+#      `refs/remotes/origin/<branch>` in `<worktree>`, made only after a failed
+#      landing, to name the commit the remote moved to.
 #      Written only by `hr_place_artifact`, `hr_commit_placed` and
 #      `hr_push_landed`.
 #
@@ -96,6 +101,11 @@
 #   HR_REMOTE_WORKFLOW_RUN_FILE mirrors  WORKFLOW_RUN_FILE
 #   HR_REMOTE_STATE_ARTIFACT    mirrors  STATE_ARTIFACT_NAME
 #
+# MIRROR OF `plugin/instructions/autonomous_pause_and_ledger.md` →
+# `### 1.3 Templates`, which owns the flow-progress ledger's two header forms
+# and its entry ids; `hr_ledger_phases` codes both, so renaming an id or a
+# header form there is an edit here.
+#
 # A caller that calls no `hr_lane_*`, `hr_registry_init`, `hr_registry_set`,
 # `hr_remote_record_init`, `hr_registry_lock`, `hr_registry_unlock`, `hr_remote_status_write`,
 # `hr_remote_bundle_write`, `hr_remote_bundle_restore`, `hr_remote_move_aside`, `hr_place_artifact`,
@@ -600,10 +610,11 @@ hr_config_load() {
   # which is what lets an explicitly EMPTY list read as a configured set rather
   # than as an absent one.
   #
-  # A `phases.*` or `docs.retrieval` value that is not a boolean is emitted as
-  # `invalid`, so the string `"true"` — which `tostring` would otherwise make
-  # indistinguishable from `true` — reaches `hr_phase_enabled` or
-  # `hr_docs_retrieval_applies` as a value it refuses (2).
+  # A `phases.*`, `docs.retrieval` or `execution.progressComments` value that is
+  # not a boolean is emitted as `invalid`, so the string `"true"` — which
+  # `tostring` would otherwise make indistinguishable from `true` — reaches
+  # `hr_phase_enabled`, `hr_docs_retrieval_applies` or `hr_progress_comments` as
+  # a value it refuses (2).
   out=$(jq -n -r '
     def s($k; $v):
       if $v == null then empty
@@ -638,6 +649,8 @@ hr_config_load() {
       s("phases.qa";             try (.phases.qa     | if type == "boolean" or . == null then . else "invalid" end) catch null),
       s("phases.docs";           try (.phases.docs   | if type == "boolean" or . == null then . else "invalid" end) catch null),
       s("execution.target";      try .execution.target     catch null),
+      s("execution.progressComments";
+        try (.execution.progressComments | if type == "boolean" or . == null then . else "invalid" end) catch null),
       s("docs.retrievalBackend"; try .docs.retrievalBackend catch null),
       s("docs.retrieval";        try (.docs.retrieval | if type == "boolean" or . == null then . else "invalid" end) catch null),
       s("forge";                 try .forge                catch null),
@@ -927,6 +940,107 @@ hr_forge() {
   return 2
 }
 
+# `execution.progressComments` — whether a remote run keeps its progress
+# comment on the pull request. THE ONE READER OF THE KEY IN THIS FAMILY; a
+# script that needs it calls this. PRINTS NOTHING: the answer is the status, as
+# `hr_phase_enabled`'s is, except that an absent key is the schema default
+# `true`. 0 = `true` or absent; 1 = `false`; 2 = the configuration is
+# unresolvable or the value is not a boolean — refused rather than guessed about.
+hr_progress_comments() {
+  local root="${1-}"
+  hr_config_load "$root" || return 2
+  hr_cfg_scalar_var "execution.progressComments" || return 0
+  case "$HR_CFG_VALUE" in
+    true) return 0 ;;
+    false) return 1 ;;
+  esac
+  return 2
+}
+
+# ---------------------------------------------------------------------------
+# The flow-progress ledger — which of a run's four main phases it records as
+# through. A mirror of the plugin's ledger templates; see the header.
+# ---------------------------------------------------------------------------
+
+# 0 when every id after <settled> appears in <settled>, a space-delimited list
+# with a leading and trailing space; 1 otherwise.
+hr_ledger_all_settled() {
+  local settled="${1-}" id
+  shift
+  for id in "$@"; do
+    case "$settled" in
+      *" $id "*) ;;
+      *) return 1 ;;
+    esac
+  done
+  return 0
+}
+
+# Print `<engine> <round> <phase1> <phase2> <phase3> <phase4>` for the ledger at
+# <ledger_file> and return 0 — `<engine>` is `task` or `user_review`, `<round>`
+# the header's round or `-` for the task engine, each phase `done` or `pending`.
+# Return 1, printing nothing, when the file is missing or unreadable or its first
+# line is not a task-engine or user-review-engine header: any other ledger has
+# no phases to report.
+#
+# A phase is `done` when every id of its set is `[x]` or `[-]` (skipped before
+# the run began). An id absent from the file is NOT settled, so a malformed
+# ledger reads as `pending`, never as `done`. Phase 3 groups every end-of-branch
+# review with its fixes, QA and the run gates.
+hr_ledger_phases() {
+  local file="${1-}" line first=1 engine="" round="-" settled=" " rest id
+  local p1 p2 p3 p4 s1 s2 s3 s4
+  [ -n "$file" ] && [ -f "$file" ] && [ -r "$file" ] || return 1
+  while IFS= read -r line || [ -n "$line" ]; do
+    if [ "$first" -eq 1 ]; then
+      first=0
+      case "$line" in
+        *"(engine: task)"*)
+          engine="task"
+          ;;
+        *"(engine: user_review, round "*")"*)
+          engine="user_review"
+          round=${line#*"(engine: user_review, round "}
+          round=${round%%")"*}
+          case "$round" in
+            ''|*[!0-9]*) return 1 ;;
+          esac
+          ;;
+        *) return 1 ;;
+      esac
+      continue
+    fi
+    case "$line" in
+      "- [x] "*|"- [-] "*) ;;
+      *) continue ;;
+    esac
+    rest=${line#"- ["?"] "}
+    id=${rest%% *}
+    id=${id%.}
+    if [ -n "$id" ]; then settled="$settled$id "; fi
+  done < "$file"
+  [ -n "$engine" ] || return 1
+
+  if [ "$engine" = "task" ]; then
+    p1="P1 P2 P3"
+    p2="A"
+    p3="A1.5g A1.5f A2g A2f Bg Bm C C2g C2m C2f E G"
+    p4="D"
+  else
+    p1="R1 R2"
+    p2="R3"
+    p3="R4 RG"
+    p4="R5"
+  fi
+  # Unquoted on purpose: each set is a fixed list of space-free ids.
+  if hr_ledger_all_settled "$settled" $p1; then s1="done"; else s1="pending"; fi
+  if hr_ledger_all_settled "$settled" $p2; then s2="done"; else s2="pending"; fi
+  if hr_ledger_all_settled "$settled" $p3; then s3="done"; else s3="pending"; fi
+  if hr_ledger_all_settled "$settled" $p4; then s4="done"; else s4="pending"; fi
+  printf '%s %s %s %s %s %s\n' "$engine" "$round" "$s1" "$s2" "$s3" "$s4"
+  return 0
+}
+
 # Whether the docs phase's retrieval step runs: `phases.docs` and
 # `docs.retrieval` both `true`. The shell mirror of `cli/src/config/model.ts` →
 # `retrievalApplies`: change the predicate there and here together. PRINTS
@@ -1865,17 +1979,31 @@ hr_commit_placed() {
   return 0
 }
 
-# hr_push_landed <push_wrapper> <worktree> <branch> — run <push_wrapper>, then 0
-# only when `HEAD` and `refs/remotes/origin/<branch>` both resolve and are
-# equal; 1 otherwise. `push-branch.sh` exits 0 on every path, so its status is
-# never the answer.
+# hr_push_landed <push_wrapper> <worktree> <branch> — run <push_wrapper>, then
+# answer from refs alone, because `push-branch.sh` exits 0 on every path:
+#   0  landed: `HEAD` and `refs/remotes/origin/<branch>` resolve and are equal,
+#      before or after that fetch;
+#   2  the remote moved: after the failed landing, a fetch of
+#      `refs/remotes/origin/<branch>` succeeds and it names a commit that is not
+#      an ancestor of `HEAD`. `HR_PUSH_REMOTE_TIP` is set to its short id;
+#   1  anything else — the push was refused, the fetch failed, or a ref did not
+#      resolve.
+# It never retries and never rebases; the retry is `push-branch.sh`'s.
 hr_push_landed() {
   local wrapper="${1-}" worktree="${2-}" branch="${3-}" head upstream
+  HR_PUSH_REMOTE_TIP=""
   [ -n "$wrapper" ] && [ -n "$worktree" ] && [ -n "$branch" ] || return 1
   "$wrapper" "$worktree"
   head=$(git -C "$worktree" rev-parse --verify --quiet HEAD) || return 1
+  [ -n "$head" ] || return 1
+  upstream=$(git -C "$worktree" rev-parse --verify --quiet "refs/remotes/origin/$branch") \
+    && [ "$head" = "$upstream" ] && return 0
+  git -C "$worktree" fetch --quiet origin "+refs/heads/$branch:refs/remotes/origin/$branch" || return 1
   upstream=$(git -C "$worktree" rev-parse --verify --quiet "refs/remotes/origin/$branch") || return 1
-  [ -n "$head" ] && [ "$head" = "$upstream" ]
+  [ "$head" != "$upstream" ] || return 0
+  git -C "$worktree" merge-base --is-ancestor "$upstream" "$head" && return 1
+  HR_PUSH_REMOTE_TIP=$(git -C "$worktree" rev-parse --short "$upstream") || return 1
+  return 2
 }
 
 # ---------------------------------------------------------------------------
@@ -1946,8 +2074,7 @@ hr_push_landed() {
 #                           the counters that must survive a job boundary
 #   chain                   the writing job's OWN input `HARNESS_INPUT_CHAIN`, never
 #                           a value carried from an earlier bundle
-#   control_polled_at       the epoch second up to which the job checked for a
-#                           `harness pause <branch>` run, or empty
+#   control_polled_at       the lower bound of the next control poll, or empty
 #   decision                `continue` | `wait-poller` | `stop`
 #   detail                  one human-readable line
 #   run_id, run_url, written_at

package/templates/scripts/push-branch.sh

@@ -28,7 +28,13 @@
 # must NEVER abort the calling run — a stale remote is recoverable and a halted
 # run is not. That is why this script uses `set -uo pipefail` deliberately
 # WITHOUT `set -e`, and why even the fail-closed arm below exits 0: it refuses
-# to push, which is the closed outcome here, and says so.
+# to push, which is the closed outcome here, and says so. A push the remote
+# refused for any reason but a `[rejected]` ref is attempted up to
+# PUSH_ATTEMPTS times in all — waiting PUSH_RETRY_DELAY_SECS before the second
+# attempt and three times that before the third — and is still never fatal once
+# given up. PUSH_RETRY_DELAY_SECS is read from the environment as a test and
+# tuning seam: default 5, and anything but a non-negative integer falls back to
+# 5 with one line.
 #
 # DEFENCE IN DEPTH, NOT THE SOLE GUARD. The caller-agnostic backstop is the
 # committed pre-push hook `init` writes into the configured `githooksDir`, which
@@ -52,7 +58,11 @@
 #
 # WHAT IT NEVER DOES. It performs only a fast-forward push of already-committed
 # work: no `--force`, no `--force-with-lease`, no history-rewriting flag, no
-# commit of its own, and no non-zero exit.
+# commit of its own, and no non-zero exit. It never retries a push git reports
+# as `! [rejected]` (non-fast-forward, fetch first), and never fetches or
+# rebases: a push that lost a race fails loudly, which is the run-control rule
+# of record (docs/github-run-control.md -> "A push that loses a race fails
+# loudly, and is never fetched, rebased or retried").
 #
 # Usage: push-branch.sh [<repo-dir>]
 #   <repo-dir>  worktree/repository to operate in (default: $PWD)
@@ -73,9 +83,35 @@
 #                     -> exit 0, refusal message, nothing pushed
 #   push fails        git -C "$d" remote set-url origin /nonexistent.git
 #                     -> exit 0 with a visible failure line
+#   refused once      printf '%s\n' '#!/bin/sh' 'c="$GIT_DIR/refusals"' \
+#                       '[ -e "$c" ] && exit 0' ': > "$c"; exit 1' > "$b/hooks/pre-receive"
+#                     chmod +x "$b/hooks/pre-receive"
+#                     git -C "$d" commit -qm x --allow-empty
+#                     PUSH_RETRY_DELAY_SECS=0 push-branch.sh "$d"
+#                     -> exit 0, one "retrying" line, and `git -C "$b" rev-parse
+#                     feat_x` equals `git -C "$d" rev-parse HEAD`
+#   remote moved      c=$(mktemp -d); git clone -q -b feat_x "$b" "$c"
+#                     git -C "$c" commit -qm other --allow-empty; git -C "$c" push -q
+#                     git -C "$d" commit -qm mine --allow-empty; push-branch.sh "$d"
+#                     -> exit 0, a "(not retried)" line, one push attempt
 
 set -uo pipefail
 
+# Attempts in all, and the wait before the second; the third waits three times
+# that (EVERY FAILURE PATH IS NON-FATAL above).
+PUSH_ATTEMPTS=3
+PUSH_RETRY_DELAY_SECS="${PUSH_RETRY_DELAY_SECS:-5}"
+case "$PUSH_RETRY_DELAY_SECS" in
+  '' | *[!0-9]*)
+    echo "push-branch.sh: PUSH_RETRY_DELAY_SECS='$PUSH_RETRY_DELAY_SECS' is not a non-negative integer — using 5"
+    PUSH_RETRY_DELAY_SECS=5
+    ;;
+  *)
+    # Base 10, so a leading zero is not read as octal.
+    PUSH_RETRY_DELAY_SECS=$((10#$PUSH_RETRY_DELAY_SECS))
+    ;;
+esac
+
 # The library is reached by a path computed from this script's own location — no
 # session root, and no runtime-substituted token, is assumed. Not finding it is
 # non-fatal like everything else here.
@@ -125,16 +161,38 @@ esac
 # set it on the fly, so a branch with no upstream is still pushed. Fast-forward
 # only.
 if git -C "$top" rev-parse --abbrev-ref --symbolic-full-name '@{u}' >/dev/null 2>&1; then
-  git -C "$top" push
+  push_cmd=(git -C "$top" push)
 else
-  git -C "$top" push --set-upstream origin "$branch"
+  push_cmd=(git -C "$top" push --set-upstream origin "$branch")
 fi
-push_status=$?
 
-if [ "$push_status" -eq 0 ]; then
-  echo "push-branch.sh: pushed $branch to origin"
-else
-  # Visible but non-blocking: a push problem must never abort the calling run.
-  echo "push-branch.sh: push failed for $branch (see output above)"
-fi
+# Every failure line keeps the `push failed for <branch>` prefix: logs and
+# Gate 12 records quote it.
+attempt=1
+delay="$PUSH_RETRY_DELAY_SECS"
+while :; do
+  push_out="$("${push_cmd[@]}" 2>&1)"
+  push_status=$?
+  # git writes its ref-status lines to stderr; keep them there.
+  [ -n "$push_out" ] && printf '%s\n' "$push_out" >&2
+
+  if [ "$push_status" -eq 0 ]; then
+    echo "push-branch.sh: pushed $branch to origin"
+    break
+  fi
+  # A here-string, not a pipe: `grep -q` exiting early would fail a pipeline
+  # under pipefail.
+  if grep -q '^ ! \[rejected\]' <<<"$push_out"; then
+    echo "push-branch.sh: push failed for $branch: origin has commits this branch does not (not retried)"
+    break
+  fi
+  if [ "$attempt" -ge "$PUSH_ATTEMPTS" ]; then
+    echo "push-branch.sh: push failed for $branch after $PUSH_ATTEMPTS attempts (see output above)"
+    break
+  fi
+  echo "push-branch.sh: push failed for $branch (attempt $attempt of $PUSH_ATTEMPTS); retrying in ${delay}s"
+  sleep "$delay"
+  attempt=$((attempt + 1))
+  delay=$((delay * 3))
+done
 exit 0