@giamme/forge 0.10.0 → 0.11.0

package/scripts/forge-lib-review.sh

@@ -34,6 +34,7 @@
 # forge_pp_flag, SKILL_DIR and DISPATCH.
 
 REVIEW_REQ_BUDGET=81920       # bytes of task requirements put in front of the reviewer
+REVIEW_SINCE_LIMIT=204800     # largest "changes since the previous review" placed inline
 REVIEW_DIFF_LIMIT=409600      # largest combined diff placed inline in the prompt
 
 # --- small helpers ---------------------------------------------------------------------
@@ -259,6 +260,80 @@ PY
   return 0
 }
 
+# --- the previous final review -----------------------------------------------------------
+# review_previous <plan> <current-out>: the newest earlier review dir of this plan that
+# reached a verdict (PASS, FAIL or ACCEPTED) and left a report; prints its absolute path, or
+# nothing. Candidates are final-review-*/ and integrate-*/final-review/, ordered by the epoch
+# in the directory name. `final-review-*` never matches the published `final-review` link,
+# and paths are resolved so a link and its target are one candidate, not two.
+review_previous() {
+  python3 - "$1" "$2" <<'PY' 2>/dev/null || true
+import glob, os, re, sys
+
+plan, cur = os.path.realpath(sys.argv[1]), os.path.realpath(sys.argv[2])
+found = {}
+for pat, rx in (('final-review-*', r'^final-review-(\d+)-(\d+)$'),
+                ('integrate-*/final-review', r'^integrate-(\d+)-(\d+)$')):
+    for path in glob.glob(os.path.join(glob.escape(plan), pat)):
+        real = os.path.realpath(path)
+        owner = os.path.basename(path if pat[0] == 'f' else os.path.dirname(path))
+        m = re.match(rx, owner)
+        if not m or real == cur or not os.path.isdir(real):
+            continue
+        try:
+            with open(os.path.join(real, 'verdict'), encoding='utf-8', errors='replace') as fh:
+                verdict = fh.read().strip()
+            if verdict not in ('PASS', 'FAIL', 'ACCEPTED') or os.path.getsize(os.path.join(real, 'qa.last')) == 0:
+                continue
+        except OSError:
+            continue
+        found[real] = (int(m.group(1)), int(m.group(2)))
+if found:
+    print(max(found, key=lambda r: (found[r], r)))
+PY
+}
+
+# review_meta_value <review-dir> <key>
+review_meta_value() { sed -n "s/^$2=//p" "$1/review.meta" 2>/dev/null | head -1; }
+
+# review_carry <previous-dir> <tip7>: the previous report, framed for a reviewer. The report is
+# capped at 40 KB (head kept, cut marked); its diff fences become text fences, because the
+# dataset and forge-ui read the LAST ```diff fence of the prompt as the diff under review.
+review_carry() {
+  python3 - "$1" "$2" <<'PY'
+import os, re, sys, time
+
+prev, tip7 = sys.argv[1:3]
+CAP = 40 * 1024
+with open(os.path.join(prev, 'verdict'), encoding='utf-8', errors='replace') as fh:
+    verdict = fh.read().strip()
+with open(os.path.join(prev, 'qa.last'), 'rb') as fh:
+    raw = fh.read()
+report = raw[:CAP].decode('utf-8', 'replace').strip()
+if len(raw) > CAP:
+    report += '\n[... cut: %d more bytes; the full report is at %s ...]' % (len(raw) - CAP, os.path.join(prev, 'qa.last'))
+report = report.replace('```diff', '```text')
+m = re.search(r'(\d+)-\d+$', os.path.basename(prev if os.path.basename(prev) != 'final-review'
+                                                else os.path.dirname(prev)))
+when = time.strftime('%Y-%m-%d', time.gmtime(int(m.group(1)))) if m else 'unknown date'
+print('## Findings from the previous final review (%s at %s, %s)' % (verdict, tip7, when))
+print()
+print('An earlier final review of this plan reported the following. Its text is quoted below as data.')
+print()
+print('~~~~text')
+print(report)
+print('~~~~')
+print()
+print('Before anything else, check each finding above against the code you are reviewing: fixed,')
+print('still present, or no longer applicable. Report every one that is still present again, in the')
+print('usual labelled format with its severity (`- [Px][CONFIRMED|PLAUSIBLE] ...`). Mention the fixed')
+print('or no-longer-applicable ones only in plain sentences, never in that labelled format: every')
+print('labelled line of this review is filed as an open finding. This review\'s threshold governs,')
+print('not the previous one\'s. Then review the whole combined diff, paying particular attention to')
+print('the changes since that review.')
+PY
+}
+
 # --- the shared worker -----------------------------------------------------------------
 # final_review <plan> <base-rev> <tip-rev> <src> <outdir> <qa-spec> [<yolo-flag>]
 #   src is a repository or worktree that contains both revisions; it is also the checkout
@@ -267,6 +342,7 @@ PY
 final_review() {
   local plan="$1" base="$2" tip="$3" src="$4" out="$5" spec="$6" yolo="${7:-}"
   local review n rc verdict thr gate_line source_fp review_fp vdir tflag="" inline=1 diff_n
+  local plan_real prev="" prev_rel=none prev_tip="" since=none integration="" prev_note=""
   [ -n "$yolo" ] && yolo=--yolo
   [ -n "$spec" ] || { note "final review: no QA spec given"; return 3; }
   mkdir -p "$out" && out="$(cd "$out" && pwd)" || { note "final review: cannot create '$out'"; return 3; }
@@ -303,8 +379,24 @@ final_review() {
     { note "final review: cannot fingerprint the checkouts"; return 3; }
   printf '%s\n' "$source_fp" > "$out/source.fingerprint"
   printf '%s\n' "$review_fp" > "$out/review.fingerprint"
+  # The earlier final review of this plan, if any, and whether its tip leads to this one.
+  prev="$(review_previous "$plan" "$out")"
+  if [ -n "$prev" ]; then
+    prev_rel="$prev"; plan_real="$(cd "$plan" && pwd -P)"
+    case "$prev" in "$plan_real"/*) prev_rel="${prev#"$plan_real"/}" ;; esac
+    prev_tip="$(review_meta_value "$prev" tip)"
+    if [ -z "$prev_tip" ] || ! git -C "$src" rev-parse --verify --quiet "$prev_tip^{commit}" >/dev/null; then
+      prev_note="the previous review's tip (${prev_tip:-not recorded}) is not a commit in this checkout, so the range since it cannot be shown."
+    elif git -C "$src" merge-base --is-ancestor "$prev_tip" "$tip" 2>/dev/null; then
+      prev_tip="$(git -C "$src" rev-parse "$prev_tip^{commit}")"; since="$prev_tip"
+    else
+      prev_note="the previous review's tip ($(printf '%.7s' "$prev_tip")) is not an ancestor of this one (it judged a different line of history, for example an integrate candidate that included your branch), so the range since it cannot be shown."
+    fi
+  fi
+  [ -s "$plan/accepted.integration" ] && integration="$(head -1 "$plan/accepted.integration" | tr -d ' \r')"
   {
     echo "base=$base"; echo "tip=$tip"; echo "source=$src"; echo "spec=$spec"; echo "threshold=${thr:-none}"
+    echo "integration=${integration:-none}"; echo "previous=$prev_rel"; echo "since=$since"
   } > "$out/review.meta"
 
   review_task_table "$plan" > "$out/tasks.summary"
@@ -318,11 +410,44 @@ final_review() {
   diff_n="$(wc -c < "$out/combined.diff" | tr -d ' ')"
   if [ "$diff_n" -gt "$REVIEW_DIFF_LIMIT" ]; then inline=0; rm -f "$out/combined.diff"; fi
 
+  # What the earlier review said, and the change since it. Nothing here may open a ```diff
+  # fence: when the combined diff is not inlined, the prompt must hold none.
+  rm -f "$out/previous.md"
+  if [ -n "$prev" ]; then
+    {
+      review_carry "$prev" "$(printf '%.7s' "${prev_tip:-unknown}")"
+      echo
+      if [ -n "$prev_note" ]; then
+        echo "Note: $prev_note"
+      elif [ "$since" = "$tip" ]; then
+        echo "### Changes since that review ($(printf '%.7s' "$since")..$(printf '%.7s' "$tip"))"
+        echo "There are no changes since that review: it judged this same commit."
+      else
+        echo "### Changes since that review ($(printf '%.7s' "$since")..$(printf '%.7s' "$tip"))"
+        git -C "$src" diff --binary "$since" "$tip" -- . ':(exclude).forge' 2>/dev/null |
+          head -c $((REVIEW_SINCE_LIMIT + 1)) > "$out/since.diff"
+        if [ "$inline" = 1 ] && [ "$(wc -c < "$out/since.diff" | tr -d ' ')" -le "$REVIEW_SINCE_LIMIT" ] &&
+           ! grep -q '```diff' "$out/since.diff"; then
+          echo '```patch'; cat "$out/since.diff"; echo '```'
+        else
+          echo "Too large (or quoting a diff fence) to inline here; the files changed since that review:"
+          echo '```text'
+          git -C "$src" diff --stat "$since" "$tip" -- . ':(exclude).forge' 2>/dev/null
+          echo '```'
+          echo "(The previous tip is not in your checkout; use the combined diff to look at those files.)"
+        fi
+        rm -f "$out/since.diff"
+      fi
+      echo
+    } > "$out/previous.md"
+  fi
+
   {
     cat "$out/context.md"
     python3 "$SKILL_DIR/scripts/forge-contract.py" qa --part head --kind final
     echo
     cat "$out/notes.md"
+    [ -s "$out/previous.md" ] && cat "$out/previous.md"
     python3 "$SKILL_DIR/scripts/forge-contract.py" qa --part tail --kind final ${thr:+--threshold "$thr"}
     echo
     if [ "$inline" = 1 ]; then
@@ -338,11 +463,41 @@ final_review() {
 
   [ -s "$plan/timeout" ] && tflag="--timeout $(cat "$plan/timeout")"
   note "final review: $spec on $(git -C "$src" diff --shortstat "$base" "$tip" -- . ':(exclude).forge' 2>/dev/null | sed 's/^ *//')"
+  # Opt-in (plan --reviewer-session): continue the previous final review's session when it ran
+  # as this one does, by the same rule as per-task QA. Anything else is a fresh dispatch.
+  local rs_mode=fresh rs_reason="" rs_id="" rs_cont=()
+  if [ -f "$plan/reviewer_session" ]; then
+    if [ -n "${FORGE_FRACTAL_RUN:-}" ] || forge_plan_is_fractal "$plan"; then
+      rs_reason=fractal
+    elif [ -z "$prev" ]; then
+      rs_reason=first-round
+    else
+      IFS=$'\t' read -r rs_mode rs_reason rs_id < <(review_session_decide \
+        "$prev/qa.session" "$prev/qa.resolved" "$out/doctor.out")
+      [ "$rs_mode" = continued ] && rs_cont=(--continue-session "$rs_id")
+    fi
+  fi
+  local qa_cmd=(/bin/bash "$DISPATCH" qa "$spec" --repo "$review" --run-dir "$out"
+      --review-base "$(cat "$out/review.base")" --ripwire-query-file "$out/context.md"
+      --prompt-file "$out/qa.input" ${yolo:+"$yolo"} $tflag --output "${FORGE_OUTPUT:-summary}")
   FORGE_CAPABILITY_CACHE="${FORGE_CAPABILITY_CACHE:-$plan/capabilities}" \
-    /bin/bash "$DISPATCH" qa "$spec" --repo "$review" --run-dir "$out" \
-      --review-base "$(cat "$out/review.base")" --ripwire-query-file "$out/context.md" \
-      --prompt-file "$out/qa.input" $yolo $tflag --output "${FORGE_OUTPUT:-summary}" > "$out/qa.out" 2>&1
+    "${qa_cmd[@]}" ${rs_cont[@]+"${rs_cont[@]}"} > "$out/qa.out" 2>&1
   rc=$?
+  if [ "$rc" = 9 ] && [ "$rs_mode" = continued ]; then
+    # Not continued (unsupported, or it failed): the same input again, fresh. The record of why
+    # is the first dispatch's, which the second one clears.
+    if [ "$(sed -n 's/^reason=//p' "$out/qa.continue" 2>/dev/null | head -1)" = unsupported ]; then
+      rs_reason=continue-unsupported
+    else
+      rs_reason=continue-failed
+    fi
+    rs_mode=fresh
+    mv "$out/qa.out" "$out/qa.continue.out" 2>/dev/null || true
+    FORGE_CAPABILITY_CACHE="${FORGE_CAPABILITY_CACHE:-$plan/capabilities}" \
+      "${qa_cmd[@]}" > "$out/qa.out" 2>&1
+    rc=$?
+  fi
+  [ ! -f "$plan/reviewer_session" ] || { echo "session=$rs_mode"; echo "session_reason=$rs_reason"; } >> "$out/review.meta"
   if [ "${FORGE_OUTPUT:-summary}" = full ]; then cat "$out/qa.out"; fi
   case "$rc" in
     0) ;;

package/scripts/forge-lib-task.sh

@@ -40,17 +40,24 @@ infra_stop() { # infra_stop <tdir> <id> <role> <attempt>
   note "$id: $role dispatch hit an infrastructure failure (${cls:-unknown}) — no attempt spent; re-run to resume"
 }
 
-# A QA-only resume is trusted only while the worktree is still exactly what was
-# reviewed. Anything else clears the marker and the full path runs.
-resume_valid() { # resume_valid <tdir> <wt>
+# True when the worktree is still exactly what was reviewed. Reads and deletes nothing:
+# the reviewed commit, the fingerprint and changes.diff are present, and the worktree's
+# HEAD and fingerprint equal them.
+reviewed_state_matches() { # reviewed_state_matches <tdir> <wt>
   local tdir="$1" wt="$2"
-  [ "$(cat "$tdir/resume" 2>/dev/null)" = qa ] || return 1
   [ -s "$tdir/reviewed.commit" ] && [ -s "$tdir/source.fingerprint" ] && [ -s "$tdir/changes.diff" ] || return 1
   [ -e "$wt/.git" ] || return 1
   [ "$(git -C "$wt" rev-parse HEAD 2>/dev/null)" = "$(cat "$tdir/reviewed.commit")" ] || return 1
   [ "$(forge_fingerprint "$wt")" = "$(cat "$tdir/source.fingerprint")" ]
 }
 
+# A QA-only resume is trusted only while the worktree is still exactly what was
+# reviewed. Anything else clears the marker and the full path runs.
+resume_valid() { # resume_valid <tdir> <wt>
+  [ "$(cat "$1/resume" 2>/dev/null)" = qa ] || return 1
+  reviewed_state_matches "$1" "$2"
+}
+
 # The next entry's kind, decided before it starts with the test do_task_body applies
 # (resume_valid): true when it only re-runs QA. A marker the worktree no longer matches is
 # cleared here, so whoever prepares the entry and do_task_body agree that it is a full one.
@@ -128,10 +135,37 @@ settle_pin() {
 # True when the task's next retry only re-runs QA: a `resume` marker (a QA-stage infrastructure
 # stop), or a verdict-less review of committed work, which prepare_retry turns into the marker
 # but has not yet when the run summary is printed. Such a retry leaves a pin in place.
+# Both are believed only while the worktree is still what was reviewed — the comparison
+# resume_valid uses, and the marker prepare_retry is about to write gets the same test.
+# This never deletes the marker; resume_check owns that.
 qa_only_next() { # qa_only_next <plan> <id>
-  local tdir="$1/tasks/$2"
-  [ "$(cat "$tdir/resume" 2>/dev/null)" = qa ] && return 0
-  [ "$(task_status "$1" "$2")" = UNKNOWN ] && [ -s "$tdir/reviewed.commit" ]
+  local tdir="$1/tasks/$2" root="" wt=""
+  root="$(cat "$1/wt_root" 2>/dev/null)"
+  [ -n "$root" ] && wt="$root/$2"
+  if [ "$(cat "$tdir/resume" 2>/dev/null)" = qa ]; then
+    [ -n "$wt" ] && reviewed_state_matches "$tdir" "$wt"
+    return
+  fi
+  if [ "$(task_status "$1" "$2")" = UNKNOWN ] && [ -s "$tdir/reviewed.commit" ]; then
+    [ -n "$wt" ] && reviewed_state_matches "$tdir" "$wt"
+    return
+  fi
+  return 1
+}
+
+qa_only_next_flag() { # qa_only_next_flag <plan> <id> -> yes | no, for `escalation --check`
+  if qa_only_next "$1" "$2"; then printf 'yes\n'; else printf 'no\n'; fi
+}
+
+# tasks/<id>/escalations.tsv, probed and appended the way forge-control writes a plan file
+# (forge-route.py record loads that code): every component below the plan is a real
+# directory, and the file is absent or a regular file. A symlink at any level is a refusal.
+escalation_record_ok() { # escalation_record_ok <plan> <id>
+  python3 "$SKILL_DIR/scripts/forge-route.py" record --plan "$1" --task "$2" --probe
+}
+
+escalation_record_line() { # escalation_record_line <plan> <id> <line>
+  python3 "$SKILL_DIR/scripts/forge-route.py" record --plan "$1" --task "$2" --line "$3"
 }
 
 # Writes the task's implementer column in tasks.tsv: a temp file, then a rename.
@@ -142,6 +176,80 @@ set_dwarf() { # set_dwarf <plan> <id> <spec>
 }
 
 # --- retry preparation ----------------------------------------------------------
+# Carries the last review's report forward as the findings of the next attempt, and records
+# which commit that report judged (what reviewed.commit holds now, since qa.last is that
+# review's). The two are written together: the commit first, so a report never sits beside a
+# commit that belongs to an older one. Repeating the call writes the same bytes.
+carry_findings() { # carry_findings <tdir>
+  local tdir="$1"
+  if [ -s "$tdir/reviewed.commit" ]; then
+    cp "$tdir/reviewed.commit" "$tdir/.retry_findings.commit.tmp" \
+      && mv "$tdir/.retry_findings.commit.tmp" "$tdir/retry_findings.commit"
+  else
+    rm -f "$tdir/retry_findings.commit"
+  fi
+  # The reviewer session that wrote these findings, and what it ran as, kept beside them for a
+  # plan with --reviewer-session. Removed first, so an older session never sits next to newer
+  # findings; a review that left no session leaves none here.
+  rm -f "$tdir/retry_findings.session" "$tdir/retry_findings.resolved"
+  cp "$tdir/qa.last" "$tdir/retry_findings.md"
+  [ ! -f "$tdir/qa.session" ] || cp "$tdir/qa.session" "$tdir/retry_findings.session" 2>/dev/null || true
+  [ ! -f "$tdir/qa.resolved" ] || cp "$tdir/qa.resolved" "$tdir/retry_findings.resolved" 2>/dev/null || true
+}
+
+# --- reviewer-session continuation (plan --reviewer-session, an opt-in experiment) ------------
+# review_session_decide <session-file> <resolved-file> <resolution-file>: whether this review
+# round continues the earlier reviewer's session. Prints `mode<TAB>reason<TAB>session`; the
+# session is the id to continue, and empty for every fresh answer.
+#   session-file     the id the earlier review ran under (retry_findings.session / qa.session)
+#   resolved-file    that review's resolution (retry_findings.resolved / qa.resolved)
+#   resolution-file  this dispatch's resolution (doctor output): harness=, model=, effort=
+# The caller has already handled the cases that need no files (first round, Fractal). Anything
+# that cannot be checked is fresh; nothing here aborts.
+review_session_decide() {
+  local sf="$1" rf="$2" cf="$3" id="" k a b h
+  [ -f "$sf" ] && id="$(head -1 "$sf" 2>/dev/null | tr -d '\r')"
+  if [ -z "$id" ]; then printf 'fresh\tno-session\t\n'; return 0; fi
+  case "$id" in *[!A-Za-z0-9-]*) printf 'fresh\tinvalid-session\t\n'; return 0 ;; esac
+  if [ "${#id}" -lt 8 ] || [ "${#id}" -gt 128 ]; then printf 'fresh\tinvalid-session\t\n'; return 0; fi
+  h="$(sed -n 's/^harness=//p' "$cf" 2>/dev/null | head -1)"
+  if [ -z "$h" ]; then printf 'fresh\tharness-unsupported\t\n'; return 0; fi
+  for k in harness model effort; do
+    a="$(sed -n "s/^$k=//p" "$rf" 2>/dev/null | head -1)"
+    b="$(sed -n "s/^$k=//p" "$cf" 2>/dev/null | head -1)"
+    if [ -z "$a" ] || [ "$a" != "$b" ]; then printf 'fresh\tspec-changed\t\n'; return 0; fi
+  done
+  case "$h" in
+    claude|openclaude|codex) printf 'continued\tsame-spec\t%s\n' "$id" ;;
+    *) printf 'fresh\tharness-unsupported\t\n' ;;
+  esac
+  return 0
+}
+
+# The diff between the attempt the carried findings judged and the one under review now, as
+# files a later gate can reuse (tasks/<id>/changes.since.{diff,range,stat}). All three go
+# when there is no valid range: no findings, no recorded commit, a commit that is unknown or
+# no ancestor of the reviewed one, or nothing changed.
+attempt_delta() { # attempt_delta <tdir> <worktree> <reviewed-commit>
+  local tdir="$1" wt="$2" reviewed="$3" from="" to=""
+  rm -f "$tdir/.changes.since.diff" "$tdir/.changes.since.stat"
+  if [ -s "$tdir/retry_findings.md" ] && [ -s "$tdir/retry_findings.commit" ] \
+     && from="$(git -C "$wt" rev-parse --verify -q "$(cat "$tdir/retry_findings.commit")^{commit}")" \
+     && to="$(git -C "$wt" rev-parse --verify -q "$reviewed^{commit}")" \
+     && git -C "$wt" merge-base --is-ancestor "$from" "$to" \
+     && git -C "$wt" diff --binary "$from" "$to" -- . ':(exclude).forge' > "$tdir/.changes.since.diff" 2>/dev/null \
+     && [ -s "$tdir/.changes.since.diff" ] \
+     && git -C "$wt" diff --stat "$from" "$to" -- . ':(exclude).forge' > "$tdir/.changes.since.stat" 2>/dev/null; then
+    printf '%s %s\n' "$from" "$to" > "$tdir/changes.since.range"
+    mv "$tdir/.changes.since.diff" "$tdir/changes.since.diff"
+    mv "$tdir/.changes.since.stat" "$tdir/changes.since.stat"
+    return 0
+  fi
+  rm -f "$tdir/.changes.since.diff" "$tdir/.changes.since.stat" \
+        "$tdir/changes.since.diff" "$tdir/changes.since.range" "$tdir/changes.since.stat"
+  return 0
+}
+
 # Shared by `retry` (a human asked) and the scheduler's automatic retries. The findings
 # are the whole point of retrying rather than re-running: the dwarf is told what was
 # wrong with its own previous attempt.
@@ -163,14 +271,15 @@ prepare_retry() { # prepare_retry <plan> <id> [new-dwarf]
   # all"), and copying that over would throw away the actual findings the previous
   # reviewer gave — the one thing a retry exists to carry forward.
   elif [ "$verdict" = PASS ] || [ "$verdict" = FAIL ]; then
-    cp "$tdir/qa.last" "$tdir/retry_findings.md"
+    carry_findings "$tdir"
   elif grep -q 'FORGE_VERDICT' "$tdir/qa.last" 2>/dev/null; then
-    cp "$tdir/qa.last" "$tdir/retry_findings.md"
+    carry_findings "$tdir"
   elif [ -s "$tdir/retry_findings.md" ]; then
     note "$id: no new review since the last retry — reusing the previous findings"
   else
     note "$id: no previous QA findings to pass on (last status was $st)"
     : > "$tdir/retry_findings.md"
+    rm -f "$tdir/retry_findings.commit" "$tdir/retry_findings.session" "$tdir/retry_findings.resolved"
   fi
   # A QA-only resume (an unreviewed verdict, or a QA-stage infrastructure stop) re-asks the
   # reviewer about work that is already committed; the dwarf does not run, so it is no moment
@@ -197,6 +306,10 @@ prepare_retry() { # prepare_retry <plan> <id> [new-dwarf]
     note "$id: the escalation pin waits for the next full retry (this one only re-runs QA)"
   elif [ "$has_pin" = 1 ] && forge_plan_is_fractal "$PLAN"; then
     note "$id: an escalation pin is set, but Fractal plans never apply pins — leaving it in place"
+  elif [ "$has_pin" = 1 ] && ! escalation_record_ok "$PLAN" "$id"; then
+    # Before the claim: a refused record leaves the pin unclaimed and tasks.tsv as it was.
+    note "$id: could not record the escalation in escalations.tsv; nothing was retried"
+    return 1
   elif [ "$has_pin" = 1 ] && pinned="$(claim_pin "$tdir")"; then
     esc_source=pin
     newdwarf="$pinned"
@@ -225,10 +338,10 @@ prepare_retry() { # prepare_retry <plan> <id> [new-dwarf]
 # Puts the next implementer in place: tasks.tsv, the escalations.tsv record and the dataset
 # event. Returns 1, with tasks.tsv and a claimed pin given back, when nothing was changed.
 write_escalation() { # write_escalation <plan> <id> <from> <to> <retry|pin|policy>
-  local PLAN="$1" id="$2" cur="$3" newdwarf="$4" esc_source="$5" tdir="$1/tasks/$2"
+  local PLAN="$1" id="$2" cur="$3" newdwarf="$4" esc_source="$5" tdir="$1/tasks/$2" line
   # A pin is held to its record: whether the record can be written is learned before
   # anything is changed, so a failure there leaves tasks.tsv and the pin as they were.
-  if [ "$esc_source" = pin ] && ! : >> "$tdir/escalations.tsv" 2>/dev/null; then
+  if [ "$esc_source" = pin ] && ! escalation_record_ok "$PLAN" "$id"; then
     note "$id: could not record the escalation in escalations.tsv; nothing was retried"
     settle_pin "$tdir" restore
     return 1
@@ -247,8 +360,9 @@ write_escalation() { # write_escalation <plan> <id> <from> <to> <retry|pin|polic
   # The rewrite loses which model failed first, and an escalation is exactly the record
   # of "this tier was too weak for this task". The last column says who decided: forge's
   # policy, a human's `retry --dwarf`, or a pin.
-  if ! printf '%s\t%s\t%s\t%s\t%s\n' "$(date +%s)" "$(cat "$tdir/attempt" 2>/dev/null || echo 0)" \
-      "$cur" "$newdwarf" "$esc_source" >> "$tdir/escalations.tsv" && [ "$esc_source" = pin ]; then
+  line="$(printf '%s\t%s\t%s\t%s\t%s' "$(date +%s)" "$(cat "$tdir/attempt" 2>/dev/null || echo 0)" \
+      "$cur" "$newdwarf" "$esc_source")"
+  if ! escalation_record_line "$PLAN" "$id" "$line" && [ "$esc_source" = pin ]; then
     # The rewrite is undone with the record, so the pin given back is still a real
     # escalation next time, not a same-spec one that hides the model it replaced.
     if [ "$newdwarf" = "$cur" ] || set_dwarf "$PLAN" "$id" "$cur"; then
@@ -282,6 +396,9 @@ prepare_resume() { # prepare_resume <plan> <id>
     note "$id: the escalation pin waits for the next full retry (this resume only re-runs QA)"
   elif forge_plan_is_fractal "$PLAN"; then
     note "$id: an escalation pin is set, but Fractal plans never apply pins — leaving it in place"
+  elif ! escalation_record_ok "$PLAN" "$id"; then
+    note "$id: could not record the escalation in escalations.tsv; nothing was retried"
+    return 1
   elif pinned="$(claim_pin "$tdir")"; then
     note "$id: applying the pinned escalation to $pinned"
     write_escalation "$PLAN" "$id" "$(field "$PLAN/tasks.tsv" "$id" dwarf)" "$pinned" pin || return 1
@@ -466,7 +583,8 @@ report_escalations() { # report_escalations <plan>
       continue
     fi
     if [ -s "$plan/tasks/$id/escalation.next" ] && [ "$(task_status "$plan" "$id")" != MERGED ]; then
-      python3 "$SKILL_DIR/scripts/forge-route.py" escalation --plan "$plan" --task "$id" --check >/dev/null 2>&1 || true
+      python3 "$SKILL_DIR/scripts/forge-route.py" escalation --plan "$plan" --task "$id" --check \
+        --qa-only-next "$(qa_only_next_flag "$plan" "$id")" >/dev/null 2>&1 || true
     fi
     if [ -s "$plan/tasks/$id/split.suggested" ]; then
       [ "$n" = 0 ] && echo "$head"

package/scripts/forge-parallel.sh

@@ -9,7 +9,7 @@
 #   forge-parallel.sh run  <plan-dir> [--max-parallel N] [--yolo-dwarf] [--yolo-qa]
 #                                     [--verify <command>] [--setup <command>] [--dry-run]
 #                                     [--timeout S] [--retry-failed N] [--infra-retries M]
-#                                     [--qa-threshold P0|P1|P2|P3] [--verify-retries N]
+#                                     [--qa-threshold P0|P1|P2|P3] [--verify-retries N] [--no-forecast]
 #   forge-parallel.sh retry <plan-dir> <task-id> [--dwarf <spec>] [--setup <command>]
 #                                     [--timeout S] [--qa-threshold Pn] [--verify-retries N]
 #   forge-parallel.sh integrate <plan-dir> --approved [--verify-retries N] [--final-review <qa-spec>]
@@ -30,6 +30,11 @@
 #                           by a listed reviewer of another model family, recorded and
 #                           never read (measures reviewer agreement). `none` turns it off
 #   --shadow-rate R         that share, 0..1 (default 0.1)
+#   --reviewer-session      opt-in experiment: a later review round continues the reviewer's
+#                           earlier session (claude, openclaude, codex) when the QA spec is
+#                           unchanged, and starts fresh whenever it cannot; each round is
+#                           logged in tasks/<id>/review_sessions.tsv and tagged in the
+#                           dataset. `--no-reviewer-session` turns it off (the default)
 #   --explore E             on by default at 0.2 (0 turns it off, and is kept): a row left
 #                           to forge gets, with probability E/2, its neighbouring model
 #                           (one tier away in the given pools) instead of its pool's turn;
@@ -129,7 +134,7 @@ pool_pick() { # pool_pick <comma-list> <index>
 do_plan() {
   local PLAN="${1:?plan needs a plan dir}"; shift
   local REPO="" D_ANY="" D_HI="" D_MD="" D_LO="" Q_ANY="" Q_HI="" Q_MD="" Q_LO=""
-  local PLANNER="" NOMEM=0 jev_rc=0 DLEVEL="" SHADOW_QA="" SHADOW_RATE="" EXPLORE="" FAIL_FIRST=""
+  local PLANNER="" NOMEM=0 jev_rc=0 DLEVEL="" SHADOW_QA="" SHADOW_RATE="" EXPLORE="" FAIL_FIRST="" REVIEWER_SESSION=""
   while [ $# -gt 0 ]; do
     case "$1" in
       --repo)         REPO="${2:?}"; shift 2 ;;
@@ -157,6 +162,8 @@ do_plan() {
       --ui|--no-ui)   forge_ui_flag "$1"; shift ;;
       --fail-first)   FAIL_FIRST=on; shift ;;
       --no-fail-first) FAIL_FIRST=off; shift ;;
+      --reviewer-session)    REVIEWER_SESSION=on; shift ;;
+      --no-reviewer-session) REVIEWER_SESSION=off; shift ;;
       *)
         # `case` is not a loop, so `continue` here belongs to the enclosing while.
         if [ "$JEV_OPTS" = 1 ]; then
@@ -192,6 +199,9 @@ do_plan() {
     || printf '%s\n' "$SHADOW_RATE" > "$PLAN/shadow_rate"
   # Fail-first evidence (opt-in, advisory) is part of the plan too: every task's review gets it.
   case "$FAIL_FIRST" in on) : > "$PLAN/fail_first" ;; off) rm -f "$PLAN/fail_first" ;; esac
+  # Reviewer-session continuation (opt-in experiment): the file holds `on`. Readers only
+  # test that it exists; the dataset records its content.
+  case "$REVIEWER_SESSION" in on) printf '%s\n' on > "$PLAN/reviewer_session" ;; off) rm -f "$PLAN/reviewer_session" ;; esac
   # Exploration is decided here and only here, so the table and preflight see what will run.
   # On by default: choosing models from measured pass rates needs some randomized picks, and
   # history had almost none (9 tasks ever ran on more than one spec). The flag wins, then
@@ -480,6 +490,9 @@ render_table() {
       echo "fail-first: on, but $(cat "$PLAN/repo")/.forge/verify-subset (a test command with {files}) is missing, so nothing will run"
     fi
   fi
+  if [ -f "$PLAN/reviewer_session" ]; then
+    echo "reviewer-session: a later review round continues the reviewer's earlier session when its QA spec is unchanged (experiment; falls back to a fresh session)"
+  fi
   echo
   local w id dws starred=0
   for w in $(awk -F'\t' '{print $1}' "$W" | sort -un); do
@@ -868,8 +881,11 @@ do_task_body() (
   echo "$review_fp" > "$tdir/review.fingerprint"
 
   forge_metric_phase preparation
-  local jev_loaded_qa=0 subset_cmd="" qa_thr
+  local jev_loaded_qa=0 subset_cmd="" qa_thr rs_on=0
   qa_thr="$(qa_threshold_for "$PLAN" "$id")"
+  # Read once per round, like the threshold: continuing the earlier reviewer's session is an
+  # opt-in experiment (plan --reviewer-session), and a round never changes its mind midway.
+  [ -f "$PLAN/reviewer_session" ] && rs_on=1
 
   # A SEPARATE file from .forge/verify, and opt-in. It must contain {files}, because
   # only the project knows how its runner takes a file list -- `pytest -q {files}` works,
@@ -895,11 +911,29 @@ do_task_body() (
   # on the review snapshot, like the subset run above; the reviewer gets the evidence.
   rm -f "$tdir/failfirst.json" "$tdir/failfirst.txt"
   [ ! -f "$PLAN/fail_first" ] || forge_fail_first "$review" "$tdir" "$REPO"
+  # What changed since the review whose findings this reviewer is handed. Fractal keeps
+  # today's prompt unless it retries, as changes.prev.diff does. dwarf.last is the reply of
+  # the attempt under review: a dwarf run just rewrote it, or $resume (the validated QA-only
+  # path, never the raw marker) guarantees the reviewed commit is the one it describes.
+  local prompt_extra=()
+  if [ -z "${FORGE_FRACTAL_RUN:-}" ] || [ "${FORGE_FRACTAL_RETRY:-}" = 1 ]; then
+    prompt_extra+=(--role qa)
+    attempt_delta "$tdir" "$wt" "$reviewed"
+    if [ -s "$tdir/changes.since.diff" ]; then
+      prompt_extra+=(--retry-diff "$tdir/changes.since.diff" --retry-stat "$tdir/changes.since.stat"
+        --retry-range "$(awk '{ print substr($1, 1, 7) ".." substr($2, 1, 7) }' "$tdir/changes.since.range")")
+    fi
+    if [ -s "$tdir/retry_findings.md" ] && [ -s "$tdir/dwarf.last" ]; then
+      prompt_extra+=(--reply "$tdir/dwarf.last")
+    fi
+  else
+    rm -f "$tdir/changes.since.diff" "$tdir/changes.since.range" "$tdir/changes.since.stat"
+  fi
   # QA uses the dispatch-time ownership and baseline, never later merge state.
   /bin/bash "$MEMORY" inject "$REPO" qa --task "$tdir/prompt.md" \
       --run-dir "$tdir" > "$tdir/qa.memory"
   {
-    python3 "$SKILL_DIR/scripts/forge-prompt.py" --requirements "$tdir/prompt.md" --capsule "$tdir/baseline.capsule" --approach "$tdir/approach.md" --retry "$tdir/retry_findings.md" --memory "$tdir/dwarf.memory" --memory "$tdir/qa.memory"
+    python3 "$SKILL_DIR/scripts/forge-prompt.py" --requirements "$tdir/prompt.md" --capsule "$tdir/baseline.capsule" --approach "$tdir/approach.md" --retry "$tdir/retry_findings.md" ${prompt_extra[@]+"${prompt_extra[@]}"} --memory "$tdir/dwarf.memory" --memory "$tdir/qa.memory"
     python3 "$SKILL_DIR/scripts/forge-contract.py" qa --part head --kind task
     echo
     if [ -s "$tdir/failfirst.txt" ]; then cat "$tdir/failfirst.txt"; echo; fi
@@ -915,9 +949,10 @@ do_task_body() (
       echo
     fi
     if [ -s "$tdir/guard.txt" ]; then
-      # Facts forge observed about how the implementer worked. The reviewer never sees the
-      # implementer's own report, so this is the only way an unfinished measurement or a
-      # stray process reaches the review.
+      # Facts forge observed about how the implementer worked. On a first attempt the reviewer
+      # never sees the implementer's own report (a retry's reviewer gets the reply, to check
+      # against the code), so this is how an unfinished measurement or a stray process
+      # reaches the review.
       echo "Implementer guard notes (observed by forge, not claimed by the implementer):"
       sed 's/^/  - /' "$tdir/guard.txt"
       echo "A promise of later work means a check may never have run; judge the diff on its own merits."
@@ -949,9 +984,45 @@ do_task_body() (
     shadow_pid=$!
   fi
   forge_metric_phase dispatch
-  /bin/bash "$DISPATCH" qa "$qa" --repo "$review" --run-dir "$tdir" \
-        --review-base "$(cat "$tdir/review.base")" --ripwire-query-file "$tdir/prompt.md" --prompt-file "$tdir/qa.input" $yq --output "${FORGE_OUTPUT:-summary}" >"$tdir/qa.out" 2>&1
+  # Whether this round continues the reviewer's session. Every answer but "continued" is a
+  # fresh dispatch, and nothing here can abort the round: a doctor that fails means fresh.
+  local rs_mode=fresh rs_reason="" rs_id="" rs_row=1 rs_cont=()
+  if [ "$rs_on" = 1 ]; then
+    if [ -n "${FORGE_FRACTAL_RUN:-}" ] || forge_plan_is_fractal "$PLAN"; then
+      rs_reason=fractal
+    elif [ ! -s "$tdir/retry_findings.md" ]; then
+      rs_reason=first-round
+    else
+      FORGE_CAPABILITY_CACHE="${FORGE_CAPABILITY_CACHE:-$PLAN/capabilities}" \
+        /bin/bash "$DISPATCH" doctor --spec "$qa" --role qa $yq > "$tdir/qa.doctor" 2>&1 || : > "$tdir/qa.doctor"
+      IFS=$'\t' read -r rs_mode rs_reason rs_id < <(review_session_decide \
+        "$tdir/retry_findings.session" "$tdir/retry_findings.resolved" "$tdir/qa.doctor")
+      [ "$rs_mode" = continued ] && rs_cont=(--continue-session "$rs_id")
+    fi
+  fi
+  local qa_cmd=(/bin/bash "$DISPATCH" qa "$qa" --repo "$review" --run-dir "$tdir" \
+        --review-base "$(cat "$tdir/review.base")" --ripwire-query-file "$tdir/prompt.md" --prompt-file "$tdir/qa.input" ${yq:+"$yq"} --output "${FORGE_OUTPUT:-summary}")
+  "${qa_cmd[@]}" ${rs_cont[@]+"${rs_cont[@]}"} >"$tdir/qa.out" 2>&1
   rc=$?
+  if [ "$rc" = 9 ] && [ "$rs_mode" = continued ]; then
+    # The session was not continued (the harness cannot, or it failed). Same input, fresh: the
+    # fresh dispatch decides the task. Why comes from the first dispatch's record, which the
+    # second one clears.
+    if [ "$(sed -n 's/^reason=//p' "$tdir/qa.continue" 2>/dev/null | head -1)" = unsupported ]; then
+      rs_reason=continue-unsupported
+    else
+      rs_reason=continue-failed
+    fi
+    rs_mode=fresh
+    mv "$tdir/qa.out" "$tdir/qa.continue.out" 2>/dev/null || true
+    "${qa_cmd[@]}" >"$tdir/qa.out" 2>&1
+    rc=$?
+  fi
+  if [ "$rs_on" = 1 ]; then
+    # One row per round, describing the dispatch whose result counts.
+    [ ! -f "$tdir/review_sessions.tsv" ] || rs_row=$(( $(wc -l < "$tdir/review_sessions.tsv") + 1 ))
+    printf '%s\t%s\t%s\t%s\t%s\n' "$rs_row" "$attempt" "$rs_mode" "$rs_reason" "$rs_id" >> "$tdir/review_sessions.tsv"
+  fi
   if [ -n "$shadow_pid" ]; then
     # On every path below, before any status is written: the shadow learns the primary is
     # done (which bounds how much longer it may take), and no shadow outlives its task, so
@@ -1036,7 +1107,8 @@ do_task() {
   record_attempt "$1" "$2"
   # The retry policy's state (escalation.next or escalation.stop), decided now rather than
   # at the next retry so a spent retry budget still reports it and the scheduler sees it.
-  python3 "$SKILL_DIR/scripts/forge-route.py" escalation --plan "$1" --task "$2" --check >/dev/null 2>&1 || true
+  python3 "$SKILL_DIR/scripts/forge-route.py" escalation --plan "$1" --task "$2" --check \
+    --qa-only-next "$(qa_only_next_flag "$1" "$2")" >/dev/null 2>&1 || true
   return $rc
 }
 
@@ -1429,13 +1501,23 @@ write_results() { # write_results <plan>
   done
 }
 
+# forecast_report PLAN: `forge dataset forecast --run`, as note lines. Whatever it does
+# (no dataset, a broken store, a slow read), the run goes on and its exit code is its own.
+forecast_report() {
+  local line
+  python3 "$SKILL_DIR/scripts/forge-dataset.py" forecast "$1" --run 2>/dev/null \
+    | while IFS= read -r line; do note "$line"; done
+  return 0
+}
+
 # --- run ----------------------------------------------------------------------
 do_run() (
   local PLAN="${1:?run needs a plan dir}"; shift
   local fractal_pipeline_args=("$@")
-  local MAXP=3 DRY=0 jev_rc=0
+  local MAXP=3 DRY=0 jev_rc=0 FORECAST=1
   while [ $# -gt 0 ]; do
     case "$1" in
+      --no-forecast) FORECAST=0; shift ;;
       --fractal) forge_fractal_flag on || exit $?; shift ;;
       --fractal-auto-decompose) forge_fractal_flag on || exit $?; FRACTAL_ARGS+=("$1"); shift ;;
       --no-fractal) forge_fractal_flag off || exit $?; shift ;;
@@ -1538,6 +1620,9 @@ do_run() (
   fi
   git -C "$int_wt" rev-parse HEAD > "$PLAN/accepted.integration"
   local id failed=0
+  # Also before any model is paid for: what this plan is likely to cost, and which tasks
+  # history says may bounce. Advisory, budgeted and silent without history; it never stops a run.
+  [ "$FORECAST" = 1 ] && forecast_report "$PLAN"
   # Say now, before any model is paid for, which suites the verify command will not run.
   verify_coverage_report "$REPO" "$(verify_command_for "$PLAN" "$REPO")" "$PLAN/verification.coverage.txt"
   local sched_rc=0 paused=0 sched_args=()