@giamme/forge 0.9.0 → 0.11.0

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
@@ -989,8 +1060,9 @@ do_task_body() (
     *)    echo UNKNOWN > "$tdir/status" ;;
   esac
   # With an explicit --qa-threshold a FAIL made only of tolerated findings becomes an
-  # accepted PASS-with-known-issues. No threshold, no change.
-  qa_gate "$PLAN" "$id" "$tdir" "$verdict"
+  # accepted PASS-with-known-issues. No threshold, no change. qa_thr is the value the review
+  # prompt was built with, so the prompt and the gate of one attempt agree.
+  qa_gate "$PLAN" "$id" "$tdir" "$verdict" "$qa_thr"
 
   # Annotate a FAIL that looks unsound. Note what this does NOT do: the status file is
   # already written above and nothing below rewrites it. A model that could talk a
@@ -1035,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
 }
 
@@ -1428,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 ;;
@@ -1537,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=()

package/scripts/forge-prompt.py

@@ -5,20 +5,72 @@ from __future__ import annotations
 import argparse
 from pathlib import Path
 
+DIFF_INLINE_CAP = 100 * 1024
+REPLY_CAP = 8 * 1024
+
+# What a reviewer is asked to do with the previous round's report. The labelled-line rule
+# matters: the severity gate, `forge issues` and forge-ui count every `- [Px][...]` line as open.
+QA_ROUND_NOTE = """\
+Check each finding above first: is it fixed, still present, or validly rejected by the
+implementer (see their reply below)? Report a finding that is still present again, in the
+usual labelled format with its severity. Mention a fixed or rejected finding only in a plain
+sentence, never as a `- [Px][CONFIRMED]` or `- [Px][PLAUSIBLE]` line: every labelled line is
+counted as an open finding. This round's threshold, in the contract below, governs; it may
+differ from the last round's. Then review the full task diff below: the changes since that
+round are where new problems are most likely."""
+
+
+def read(path: str | None, errors: str = 'strict') -> str:
+    if path and Path(path).is_file():
+        with Path(path).open(newline="", errors=errors) as source:
+            return source.read()
+    return ''
+
+
+def carried(text: str) -> str:
+    # The dataset and forge-ui take the LAST ```diff fence of a QA prompt as the reviewed
+    # diff, so nothing carried from an earlier round may open one.
+    return text.replace('```diff', '```text')
+
+
+def qa_round(findings: str, diff: str | None, span: str | None, stat: str | None, reply: str | None) -> str:
+    parts = ['## Findings from the previous review round\n' + carried(findings).rstrip('\n') + '\n\n' + QA_ROUND_NOTE]
+    # A git diff carries raw source bytes, so a file that is not UTF-8 must not abort the prompt.
+    patch = read(diff, 'replace')
+    if patch:
+        label = ' (' + span.strip() + ')' if span and span.strip() else ''
+        if len(patch.encode()) <= DIFF_INLINE_CAP:
+            body = '```patch\n' + patch.rstrip('\n') + '\n```'
+        else:
+            body = ('The diff since that review is too large to inline; its stat:\n\n```text\n'
+                    + read(stat, 'replace').rstrip('\n') + '\n```')
+        parts.append('### Changes since that review' + label + '\n' + body)
+    said = read(reply, 'replace')
+    if said.strip():
+        raw = said.encode()
+        if len(raw) > REPLY_CAP:
+            said = raw[:REPLY_CAP].decode(errors='ignore') + '\n[... the reply continues; cut here ...]\n'
+        parts.append("### The implementer's reply (its own account; verify every claim against the code)\n"
+                     + carried(said).rstrip('\n'))
+    return '\n\n'.join(parts) + '\n'
+
 
 def context(
     requirements: str, approach: str | None = None, capsule: str | None = None,
     retry: str | None = None, goal: str | None = None, memories: tuple[str, ...] = (),
+    role: str = 'dwarf', retry_diff: str | None = None, retry_range: str | None = None,
+    retry_stat: str | None = None, reply: str | None = None,
 ) -> str:
     chunks = []
     for title, path in [('Ownership and baseline', capsule), ('Overall goal', goal),
                         ('Complete implementation requirements', requirements),
                         ('Intended approach', approach),
                         ('Your previous attempt was reviewed and rejected', retry)]:
-        if path and Path(path).is_file():
-            with Path(path).open(newline="") as source:
-                data = source.read()
-            if data:
+        data = read(path) if path and Path(path).is_file() else ''
+        if data:
+            if role == 'qa' and path == retry:
+                chunks.append(qa_round(data, retry_diff, retry_range, retry_stat, reply).rstrip('\n'))
+            else:
                 chunks.append('## ' + title + '\n' + data)
     # Memory injection emits headings and prose around bullet facts. Union only
     # exact fact lines, preserving distinct facts even when they share a key.
@@ -40,6 +92,11 @@ if __name__ == '__main__':
     for key in ('requirements', 'approach', 'capsule', 'retry', 'goal'):
         parser.add_argument('--' + key, required=key == 'requirements')
     parser.add_argument('--memory', action='append', default=[])
+    parser.add_argument('--role', choices=('dwarf', 'qa'), default='dwarf')
+    parser.add_argument('--retry-diff')
+    parser.add_argument('--retry-range')
+    parser.add_argument('--retry-stat')
+    parser.add_argument('--reply')
     args = vars(parser.parse_args())
     args['memories'] = args.pop('memory')
     print(context(**args), end='')

package/scripts/forge-route.py

@@ -16,13 +16,30 @@ bias (inverse-propensity weighting needs the probability each choice had).
       rewritten) and marks a changed pick in tasks/<id>/route.explored for the table. A row
       with no neighbour is not explored and records nothing.
 
-  forge-route.py escalation --plan P --task ID [--check]
+  forge-route.py escalation --plan P --task ID [--check] [--qa-only-next yes|no]
       The retry policy: after <plan>/escalate_after (default 3; 0 = off) failed attempts on
       one spec, the next attempt goes to the next tier up of the user's pools instead of
       repeating the same dispatch. Prints that spec when one is due. When none exists, writes
       tasks/<id>/escalation.stop and split.suggested and exits 3. `--check` (run after every
       attempt) also records a due escalation in escalation.next, and clears the markers once
-      the streak no longer holds.
+      the streak no longer holds. A pending tasks/<id>/escalation.pin (a human's one-shot
+      choice, applied by prepare_retry) is what `--check` reports as the next model instead
+      (escalation.next = its spec), whatever escalate_after says, unless the next retry is a
+      QA-only resume or the plan is Fractal (pins never apply there). `--qa-only-next` is
+      that fact as the caller measured it; without the option, a resume marker or an
+      unreviewed commit is taken as QA-only. Nothing has applied the pin yet, so the policy's
+      own stop and split markers stay as the policy decided them beneath it: they are what
+      holds again if the pin is withdrawn. The marker writes take <plan>/control.lock and
+      re-read escalate_after inside it: a policy decision made before a human switched the
+      policy off writes nothing.
+
+  forge-route.py record --plan P --task ID (--probe | --line TEXT)
+      Internal. Probe or append tasks/<id>/escalations.tsv through forge-control.py, which
+      walks from the plan one directory at a time and refuses a symlink at any component.
+      `--probe` exits 0 when every component below the plan is a real directory and the file
+      is absent or a regular file. `--line` appends one record under those same conditions.
+      A missing parent exits 1 and writes nothing: the walk has no directory descriptor then,
+      and opening the leaf would create it in the process's current directory.
 
 The propensity of the chosen spec is (1-E)*[chosen == SPEC] + E/2. Forge never picks a
 model the user did not name: both helpers read only the pools `plan` stored in
@@ -34,12 +51,17 @@ the draws reproducible (tests only). Any failure prints SPEC (explore) or nothin
 from __future__ import annotations
 
 import argparse
+import contextlib
+import errno
+import fcntl
 import hashlib
 import json
 import os
 import random
 import secrets
+import stat
 import sys
+import tempfile
 import time
 from pathlib import Path
 
@@ -49,6 +71,7 @@ REGISTRY = SCRIPTS.parent / 'registry.tsv'
 FAILED = ('FAIL', 'TIMEOUT')                       # a judgment against the spec that ran
 NEUTRAL = ('INFRA', 'UNKNOWN', 'ERROR', 'RUNNING', 'INTERRUPTED')   # say nothing about it
 DEFAULT_ESCALATE_AFTER = 3
+LOCK_WAIT = 5.0                                    # seconds to wait for P/control.lock
 
 
 def rng_for(task: str):
@@ -275,46 +298,230 @@ def _fractal(plan: Path) -> bool:
         return False
 
 
+# --- live-control files ------------------------------------------------------------
+# Markers are shared with `forge control` and the scheduler, so they are written the way
+# every writer of the plan's control files writes: a task id the scheduler would accept, a
+# real directory chain under the canonical plan dir, a regular file as the target, a temp
+# file plus rename, and P/control.lock held around the check-and-write.
+
+class Busy(Exception):
+    """P/control.lock stayed held for LOCK_WAIT seconds."""
+
+
+def _task_dir(plan: Path, task: str):
+    """tasks/<task> under the canonical plan dir, or None when it is not a real directory."""
+    if not task or task in ('.', '..') or '/' in task or '\0' in task:
+        return None
+    tdir = plan / 'tasks' / task
+    try:
+        if not stat.S_ISDIR(os.lstat(tdir).st_mode) or os.path.realpath(tdir) != str(tdir):
+            return None
+    except OSError:
+        return None
+    return tdir
+
+
+@contextlib.contextmanager
+def _control_lock(plan: Path):
+    fd = os.open(str(plan / 'control.lock'), os.O_RDWR | os.O_CREAT | os.O_NOFOLLOW | os.O_CLOEXEC, 0o644)
+    try:
+        if not stat.S_ISREG(os.fstat(fd).st_mode):
+            raise OSError(errno.EINVAL, 'control.lock is not a regular file')
+        deadline = time.monotonic() + LOCK_WAIT
+        while True:
+            try:
+                fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+                break
+            except OSError as exc:
+                if exc.errno not in (errno.EAGAIN, errno.EACCES, errno.EWOULDBLOCK):
+                    raise
+                if time.monotonic() >= deadline:
+                    raise Busy('control.lock is held') from None
+                time.sleep(0.05)
+        try:
+            yield
+        finally:
+            fcntl.flock(fd, fcntl.LOCK_UN)
+    finally:
+        os.close(fd)
+
+
+def _regular(path: Path) -> bool:
+    try:
+        return stat.S_ISREG(os.lstat(path).st_mode)
+    except OSError:
+        return False
+
+
+MARKERS = ('escalation.stop', 'split.suggested', 'escalation.next')
+
+
 def _clear(tdir: Path, *names) -> None:
-    for name in names or ('escalation.stop', 'split.suggested', 'escalation.next'):
+    for name in names:
+        if _regular(tdir / name):
+            try:
+                (tdir / name).unlink()
+            except OSError:
+                pass
+
+
+def _write_marker(tdir: Path, name: str, text: str) -> None:
+    target = tdir / name
+    if os.path.lexists(target) and not _regular(target):
+        raise OSError(errno.EINVAL, '%s is not a regular file' % name)
+    fd, tmp = tempfile.mkstemp(dir=str(tdir), prefix='.%s.' % name)
+    try:
+        with os.fdopen(fd, 'w') as out:
+            out.write(text)
+        os.chmod(tmp, 0o644)
+        os.replace(tmp, target)
+    except BaseException:
         try:
-            (tdir / name).unlink()
+            os.unlink(tmp)
         except OSError:
             pass
+        raise
 
 
-def escalation(args) -> int:
-    plan = Path(args.plan)
-    tdir = plan / 'tasks' / args.task
-    after = _setting(plan)
-    # Fractal plans freeze their eligible set at selection; a QA-only resume spends no dwarf
-    # attempt, so neither is a moment to change the implementer.
-    if after <= 0 or _fractal(plan) or (tdir / 'resume').exists():
-        if after <= 0:
-            _clear(tdir)
-        return 0
+def _pin(tdir: Path):
+    """The pending pin's spec, or None. One line, one token: it goes into a TSV column."""
+    path = tdir / 'escalation.pin'
+    if not _regular(path):
+        return None
+    try:
+        lines = path.read_text().splitlines()
+    except (OSError, UnicodeDecodeError):
+        return None
+    spec = lines[0].strip() if lines else ''
+    if not spec or spec in ('-', 'UNASSIGNED') or any(c.isspace() or ord(c) < 32 for c in spec):
+        return None
+    return spec
+
+
+def _qa_next(tdir: Path) -> bool:
+    """Fallback when `--qa-only-next` is absent: a resume marker, or an unreviewed commit.
+
+    This does not look at the worktree. Callers that measured it (qa_only_next) pass
+    `--qa-only-next` instead, so a marker the worktree no longer matches is a full retry.
+    """
+    if (tdir / 'resume').exists():
+        return True
+    try:
+        return (tdir / 'status').read_text().strip() == 'UNKNOWN' and (tdir / 'reviewed.commit').stat().st_size > 0
+    except OSError:
+        return False
+
+
+def _apply(plan: Path, tdir: Path, clear=(), writes=(), policy=True, pin=None):
+    """Clear and write markers under the control lock. Returns (policy stood, pin reported).
+
+    The policy re-reads escalate_after inside the lock (a human may have switched it off since
+    the decision was made): it then writes nothing and its markers go, as `--escalate-after 0`
+    clears them. A pin is reported as escalation.next only while it is still pending; the stop
+    and split markers beneath it stay the policy's, because the pin has not been applied.
+    """
+    with _control_lock(plan):
+        stood = policy and _setting(plan) > 0
+        if policy and not stood:
+            clear, writes = MARKERS, ()
+        reported = pin is not None and _pin(tdir) == pin
+        _clear(tdir, *clear)
+        for name, text in writes:
+            _write_marker(tdir, name, text)
+        if reported:
+            _write_marker(tdir, 'escalation.next', pin + '\n')
+    return stood, reported
+
+
+def _decide(plan: Path, tdir: Path, args, after: int):
+    """What the policy wants done to the markers: (clear, writes, spec to print, exit code)."""
     current = _dwarf_of(plan, args.task)
     if not current or current in ('-', 'UNASSIGNED'):
-        return 0
+        return (), (), '', 0
     registry = registry_models()
     streak = failed_streak(attempt_rows(tdir), current, registry)
     if streak < after:
-        _clear(tdir)
-        return 0
+        return MARKERS, (), '', 0
     target, why = stronger(current, load_pools(plan / 'fractal-routing.json'), registry)
     if target:
-        _clear(tdir, 'escalation.stop', 'split.suggested')
-        if args.check:
-            (tdir / 'escalation.next').write_text(target + '\n')
-        print(target)
+        writes = (('escalation.next', target + '\n'),) if args.check else ()
+        return ('escalation.stop', 'split.suggested'), writes, target, 0
+    split = ('%s failed %d attempts on %s, and %s. Another attempt on the same model rarely passes, '
+             'so split the task into smaller ones, or retry it with an explicit --dwarf <spec>.\n'
+             % (args.task, streak, current, why))
+    return ('escalation.next',), (('escalation.stop', '%d\t%s\n' % (streak, current)), ('split.suggested', split)), '', 3
+
+
+def escalation(args) -> int:
+    plan = Path(os.path.realpath(args.plan))
+    tdir = _task_dir(plan, args.task)
+    if tdir is None:
         return 0
-    _clear(tdir, 'escalation.next')
-    (tdir / 'escalation.stop').write_text('%d\t%s\n' % (streak, current))
-    (tdir / 'split.suggested').write_text(
-        '%s failed %d attempts on %s, and %s. Another attempt on the same model rarely passes, '
-        'so split the task into smaller ones, or retry it with an explicit --dwarf <spec>.\n'
-        % (args.task, streak, current, why))
-    return 3
+    after = _setting(plan)
+    fractal = _fractal(plan)
+    # Fractal plans freeze their eligible set at selection; a QA-only resume spends no dwarf
+    # attempt, so neither is a moment to change the implementer.
+    idle = after <= 0 or fractal or (tdir / 'resume').exists()
+    # A pin is a human's choice and outranks the policy, so `--check` reports it as the next
+    # model whatever escalate_after says; prepare_retry applies it and claims the file. The
+    # policy is still decided underneath it and its markers kept current. The policy's own
+    # idle test above is separate and stays on the raw resume marker.
+    qa_only = _qa_next(tdir) if args.qa_only_next is None else args.qa_only_next == 'yes'
+    pin = _pin(tdir) if args.check and not fractal and not qa_only else None
+    clear, writes, shown, rc = (MARKERS if after <= 0 else ()), (), '', 0
+    if not idle:
+        clear, writes, shown, rc = _decide(plan, tdir, args, after)
+    if not (writes or shown or pin):
+        _clear(tdir, *clear)
+        return 0
+    stood, reported = _apply(plan, tdir, clear, writes, policy=not idle, pin=pin)
+    if reported:
+        print(pin)
+        return 0
+    if not stood:
+        return 0
+    if shown:
+        print(shown)
+    return rc
+
+
+def _load_control():
+    """forge-control.py, by path: probe and append_line refuse a symlink at any component."""
+    import importlib.util
+    spec = importlib.util.spec_from_file_location(
+        'forge_control', Path(__file__).resolve().with_name('forge-control.py'))
+    module = importlib.util.module_from_spec(spec)
+    sys.modules['forge_control'] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+def record_escalation(args) -> int:
+    """Probe or append tasks/<id>/escalations.tsv. 0 when that is safe; 1 when it is not.
+
+    A missing parent is a refusal on both paths. probe() reports that as the file being
+    absent, so the check has to look at the walk itself. append_line refuses the same case
+    before it opens the leaf: with no directory descriptor that open would use the process
+    cwd, including when the task directory disappears between this check and the append.
+    """
+    if not args.task or args.task in ('.', '..') or '/' in args.task or '\0' in args.task:
+        return 1
+    try:
+        control = _load_control()
+        plan = os.path.realpath(args.plan)
+        rel = 'tasks/%s/escalations.tsv' % args.task
+        parent, _leaf = control._open_parent(plan, rel)
+        if parent is None:
+            return 1
+        os.close(parent)
+        if args.probe:
+            control.probe(plan, rel)
+        else:
+            line = args.line if args.line.endswith('\n') else args.line + '\n'
+            control.append_line(plan, rel, line)
+    except Exception:
+        return 1
+    return 0
 
 
 def main(argv=None) -> int:
@@ -327,6 +534,14 @@ def main(argv=None) -> int:
     p.add_argument('--plan', required=True)
     p.add_argument('--task', required=True)
     p.add_argument('--check', action='store_true')
+    p.add_argument('--qa-only-next', choices=('yes', 'no'), default=None,
+                   help='whether the next entry only re-runs QA, as the caller measured it')
+    p = sub.add_parser('record', help=argparse.SUPPRESS)
+    p.add_argument('--plan', required=True)
+    p.add_argument('--task', required=True)
+    mode = p.add_mutually_exclusive_group(required=True)
+    mode.add_argument('--probe', action='store_true')
+    mode.add_argument('--line')
     args = ap.parse_args(argv)
     if args.command == 'explore':
         try:
@@ -334,6 +549,8 @@ def main(argv=None) -> int:
         except Exception:
             print(args.default)
         return 0
+    if args.command == 'record':
+        return record_escalation(args)
     try:
         return escalation(args)
     except Exception: