@giamme/forge 0.10.0 → 0.11.0

package/references/harnesses.md

@@ -22,6 +22,7 @@ provider test. See [Fractal execution](fractal.md).
 - [opencode](#opencode)
 - [antigravity (agy)](#antigravity-agy)
 - [grok](#grok)
+- [Continuing a reviewer session](#continuing-a-reviewer-session)
 - [Adding a harness](#adding-a-harness)
 
 ## At a glance
@@ -265,7 +266,8 @@ passes 30m and exposes `--agy-timeout` to change it.
 
 ```
 grok --model <model> --prompt-file <prompt> --output-format streaming-messages-json \
-  --reasoning-effort <effort> (--permission-mode acceptEdits --allow Bash [--deny Edit --deny Write] | --always-approve)
+  --reasoning-effort <effort> --background-wait-timeout <limit> \
+  (--permission-mode acceptEdits --allow Bash [--deny Edit --deny Write] | --always-approve)
 ```
 
 The xAI Grok Build CLI, signed in with `grok login` (or `XAI_API_KEY`); `grok models` lists
@@ -294,6 +296,15 @@ GitHub Copilot) as a second row.
   - **Untested:** whether `--permission-mode dontAsk` (deny without cancelling) together with
     explicit Edit/Write/Bash allows would avoid the cancel. Nothing changes until that is
     proven live.
+- **Background work waits as long as forge's limit allows.** After its last turn a headless run
+  waits for the background jobs it started (a test suite run in the background, say) and wakes
+  the model with each result. By default it waits only 600 s, then stops the work and exits 1:
+  a real dwarf whose full suite ran longer ended as an error. forge passes the role's own limit
+  as `--background-wait-timeout`, or a day when the limit is off (`--timeout 0`; grok refuses
+  0). grok counts from the last turn and forge from the start, so forge's watchdog always fires
+  first and the run ends as a timeout. The flag is missing from `grok --help`; preflight checks
+  it with `grok --background-wait-timeout 1 --help` instead, because grok rejects an unknown flag
+  that comes before `--help` (exit 2).
 - The prompt goes by `--prompt-file`, never argv, and stdin is `/dev/null`.
 
 Verified live on 2026-10-19 with a `FORGE_OK` dispatch: exit 0, `permissionMode` acceptEdits,
@@ -301,6 +312,37 @@ the answer extracted from the `result` line, tokens recorded, nothing left runni
 day, grok-4.7 dwarfs implemented and passed review on real tasks (the forge-ui integration run).
 A grok reviewer has not been proven live yet.
 
+## Continuing a reviewer session
+
+`forge-dispatch.sh qa <spec> ... --continue-session <id>` continues an earlier reviewer session instead of
+starting a fresh one. `<id>` is the session or thread id a dispatch left in `<run-dir>/<role>.session`
+(8 to 128 characters of `[A-Za-z0-9-]`, not starting with `-`). It is accepted for the `qa` role on claude,
+openclaude and codex in custom-prompt mode only; any other role, harness, `--native-review` or a malformed id
+is a usage error (exit 2). Nothing in forge asks for it by default.
+
+Probed 2026-10-22 (claude 2.1.307, codex 0.162.0):
+
+| Harness | Argv | Notes |
+|---|---|---|
+| claude, openclaude | the fresh QA argv plus `--resume <id>` | Continues from a different working directory and keeps the same session id. Permission flags and the read-only restriction stay; the prompt is still on stdin. |
+| codex | `codex exec resume <id> --json -m MODEL --skip-git-repo-check -o LAST [-c model_reasoning_effort=…] -c 'sandbox_mode="read-only"' -` | Continues from a different working directory. `exec resume` has **no `-C/--cd` and no `-s/--sandbox`**, so the dispatch's own `cd "$REPO"` sets the directory and the sandbox is passed as a config override (the quotes are TOML). The first turn's sandbox was inherited when probed (read-only); the override makes it explicit. Under `--yolo` the bypass flag replaces the override. |
+
+The prompt is preceded by a short fixed preamble (this continues your earlier review, the work has changed,
+the working directory is now `<repo>`, re-read files, this round's instructions win). `<role>.prompt` includes
+it. `<role>.continue` records the attempt as `requested=<id>`, then `mode=continued` or `mode=failed` with
+`reason=<one line>`, and is archived with the attempt.
+
+**Exit 9** means the session was not continued and the caller may dispatch fresh. Dispatch never retries fresh
+itself, so each dispatch keeps its own honest record. It happens when:
+
+- the harness does not advertise the flags continuing needs (`codex exec resume --help`, or `--resume` in
+  claude's help) but would pass preflight for a fresh QA dispatch: `reason=unsupported`, before any model call;
+  a harness that fails the fresh preflight too keeps exit 3;
+- the harness ran and exited non-zero: `reason=` the log's last error line.
+
+A timeout stays exit 7 and an infrastructure stop stays exit 8; both still write `mode=failed`. `doctor --spec`
+without `--continue-session` is unchanged.
+
 ## Installing forge into a harness
 
 Each harness discovers skills differently, and the differences are not guessable — verify

package/references/ui.md

@@ -38,7 +38,10 @@ run goes on, with the same exit code.
   model; the bell tells you when a run finishes or fails, a task fails or a final review gives its
   verdict, and can raise browser notifications while the tab is in the background.
 - **Plan run:** tasks in their planned waves with dependency cables, then the finish line:
-  integration, verification and the whole-run final review, each a node with its status. The
+  integration, verification and the whole-run final review, each a node with its status. Tasks
+  merged with `accept` show as accepted (hollow green), not failed. A final review superseded
+  by later task merges into the integration branch shows as OUTDATED (hollow unlit) instead of
+  as the run's verdict; changes on the user's own branch after an integrate are not tracked. The
   *Execution* view shows the same run on wall-clock time, one block per attempt in the lane it
   ran in, with projected blocks for what has not started and a strip of busy slots against
   `--max-parallel`.

package/scripts/forge-config.py

@@ -201,8 +201,11 @@ def dataset_block():
     if explicit:
         home = Path(explicit).expanduser()
     else:
-        base = os.environ.get('XDG_DATA_HOME') or str(Path.home() / '.local' / 'share')
-        home = Path(base).expanduser() / 'forge'
+        value = os.environ.get('XDG_DATA_HOME') or ''  # an empty or relative value counts as unset
+        base = Path(value).expanduser() if value else None
+        if base is None or not base.is_absolute():
+            base = Path.home() / '.local' / 'share'
+        home = base / 'forge'
     enabled = os.environ.get('FORGE_DATASET', 'on').strip().lower() not in ('off', '0', 'no', 'false')
     return dict(path=str(home / 'dataset'), enabled=enabled)
 

package/scripts/forge-control.py

@@ -225,6 +225,10 @@ def remove_safe(plan, rel):
 
 def append_line(plan, rel, line):
     fd, leaf = _open_parent(plan, rel)
+    # A missing parent leaves no directory descriptor. Opening the leaf then would pass
+    # dir_fd=None and create it in the process cwd, outside the plan, before the close failed.
+    if fd is None:
+        raise Invalid(f'{rel}: a parent directory is missing')
     try:
         _regular(fd, leaf, rel)
         afd = os.open(leaf, os.O_WRONLY | os.O_APPEND | os.O_CREAT | os.O_NOFOLLOW | os.O_CLOEXEC, 0o644, dir_fd=fd)

package/scripts/forge-dispatch.sh

@@ -9,6 +9,8 @@
 #   forge-dispatch.sh dwarf <spec> --prompt-file <f> [--repo <dir>] [--run-dir <d>] [--yolo] [--dry-run]
 #   forge-dispatch.sh qa    <spec> --prompt-file <f> [--repo <dir>] [--run-dir <d>] [--yolo] [--dry-run]
 #                                  [--native-review [--review-base <ref>]]
+#   forge-dispatch.sh qa <spec> ... --continue-session <id>   continue that reviewer session
+#                                  (claude, openclaude, codex; custom prompt only)
 #   any role: [--no-ripwire] [--ripwire-query-file <requirements>]
 #   any role: [--timeout <seconds>]   0 disables the watchdog
 #
@@ -28,6 +30,9 @@
 #               answer): the model never got to do its work. $ROLE.infra says which.
 #               A DWARF that exits 0 with an empty final message also writes $ROLE.infra
 #               (class=empty) but still exits 0; consult the file only if the diff is empty.
+#             9 the session was not continued (--continue-session only): the harness cannot
+#               continue one, or it ran and failed. The caller may dispatch fresh; dispatch
+#               never does, so each dispatch keeps its own record. $ROLE.continue says why.
 # A process still alive in the harness's group after it exited is killed and listed in
 # $ROLE.orphans (only written when there is something to list).
 set -uo pipefail
@@ -149,7 +154,7 @@ SPEC="$1"; shift
 
 RIPWIRE_QUERY=""
 OUTPUT=full
-REPO="$PWD"; RUN_DIR=""; PROMPT_FILE=""; YOLO=0; DRY=0; REVIEW_BASE=""; PROMPT_VIA_STDIN=0; NATIVE_REVIEW=0; AGY_TIMEOUT="30m"; TIMEOUT_FLAG=""
+REPO="$PWD"; RUN_DIR=""; PROMPT_FILE=""; YOLO=0; DRY=0; REVIEW_BASE=""; PROMPT_VIA_STDIN=0; NATIVE_REVIEW=0; CONTINUE_ID=""; CONTINUE_GIVEN=0; AGY_TIMEOUT="30m"; TIMEOUT_FLAG=""
 while [ $# -gt 0 ]; do
   case "$1" in
     --no-ripwire) export FORGE_RIPWIRE=off; shift ;;
@@ -160,6 +165,7 @@ while [ $# -gt 0 ]; do
     --prompt-file)  PROMPT_FILE="${2:?--prompt-file needs a value}"; shift 2 ;;
     --review-base)  REVIEW_BASE="${2:?--review-base needs a value}"; shift 2 ;;
     --native-review) NATIVE_REVIEW=1; shift ;;
+    --continue-session) [ $# -ge 2 ] || die "--continue-session needs a session id"; CONTINUE_ID="$2"; CONTINUE_GIVEN=1; shift 2 ;;
     --agy-timeout)  AGY_TIMEOUT="${2:?--agy-timeout needs a value}"; shift 2 ;;
     --timeout)      TIMEOUT_FLAG="${2:?--timeout needs a value in seconds, 0 to disable}"; shift 2 ;;
     --yolo)         YOLO=1; shift ;;
@@ -207,6 +213,12 @@ fi
 if [ "$NATIVE_REVIEW" = 1 ] && { [ "$ROLE" != qa ] || [ "$HARNESS" != codex ]; }; then
   die "--native-review requires QA on codex"
 fi
+if [ "$CONTINUE_GIVEN" = 1 ]; then
+  [ "$ROLE" = qa ] && [ "$NATIVE_REVIEW" != 1 ] && { [ "$HARNESS" = codex ] || [ "$HARNESS" = claude ] || [ "$HARNESS" = openclaude ]; } \
+    || die "--continue-session needs the qa role on codex, claude or openclaude, without --native-review"
+  case "$CONTINUE_ID" in ''|*[!A-Za-z0-9-]*) die "--continue-session id must be letters, digits and '-' only" ;; esac
+  [ "${#CONTINUE_ID}" -ge 8 ] && [ "${#CONTINUE_ID}" -le 128 ] || die "--continue-session id must be 8 to 128 characters"
+fi
 
 # --- resolve effort -----------------------------------------------------------
 LADDER="$(ladder_for "$HARNESS")"
@@ -301,10 +313,11 @@ RUN_DIR="$(cd "$RUN_DIR" && pwd)"   # normalize, so the containment check below
 case "$RUN_DIR" in "$REPO"|"$REPO"/*) die "--run-dir must be outside --repo, or it lands in the diff under review" ;; esac
 
 # Start an immutable attempt record before preparation, including failures.
+write_continue() { :; }   # redefined below once there is an attempt to archive it into
 ATTEMPT=""
 if [ "$PREFLIGHT" != 1 ] && [ "$DRY" != 1 ]; then
   ATTEMPT="$(python3 "$RUNTIME" begin "$RUN_DIR" "$ROLE")" || exit 3
-  rm -f "$RUN_DIR/$ROLE.last" "$RUN_DIR/$ROLE.log" "$RUN_DIR/$ROLE.resolved" "$RUN_DIR/$ROLE.cmd" "$RUN_DIR/$ROLE.timedout" "$RUN_DIR/$ROLE.infra" "$RUN_DIR/$ROLE.orphans"
+  rm -f "$RUN_DIR/$ROLE.last" "$RUN_DIR/$ROLE.log" "$RUN_DIR/$ROLE.resolved" "$RUN_DIR/$ROLE.cmd" "$RUN_DIR/$ROLE.timedout" "$RUN_DIR/$ROLE.infra" "$RUN_DIR/$ROLE.orphans" "$RUN_DIR/$ROLE.session" "$RUN_DIR/$ROLE.continue"
   trap 'exit 143' TERM
   trap 'exit 130' INT
   # GUARD_ON is 1 only when the harness was started in its own process group (see the
@@ -322,6 +335,14 @@ if [ "$PREFLIGHT" != 1 ] && [ "$DRY" != 1 ]; then
     fi
     if [ -n "${wpid:-}" ]; then pkill -P "$wpid" 2>/dev/null; kill "$wpid" 2>/dev/null; fi
   }
+  # What the EXIT trap's `finish` archives. Pessimistic until an outcome is known, so every
+  # path out of a continue request (a signal, a usage error after this point) leaves a record.
+  write_continue() { # write_continue <continued|failed> [reason]
+    [ -n "$CONTINUE_ID" ] || return 0
+    { echo "requested=$CONTINUE_ID"; echo "mode=$1"; [ -z "${2:-}" ] || echo "reason=$2"; } > "$RUN_DIR/$ROLE.continue.tmp" \
+      && mv "$RUN_DIR/$ROLE.continue.tmp" "$RUN_DIR/$ROLE.continue"
+  }
+  write_continue failed "dispatch did not complete"
   trap 'result=$?; exit_cleanup; python3 "$RUNTIME" finish "$ATTEMPT" "$RUN_DIR" "$ROLE" "$HARNESS" "$result"; exit "$result"' EXIT
 fi
 [ -n "$PROMPT_FILE" ] || die "role '$ROLE' needs --prompt-file"
@@ -372,139 +393,219 @@ if [ -n "$ATTEMPT" ]; then
     --prompt "$PROMPT_FILE" --query "$RIPWIRE_QUERY" --baseline "$REVIEW_BASE" \
     --artifacts "$ATTEMPT" --native "$NATIVE_REVIEW" || note "Ripwire preparation failed; continuing"
 fi
+# A continued reviewer remembers the earlier round, including its instructions. $ROLE.prompt
+# records what was sent, so the preamble goes into the file itself.
+if [ -n "$CONTINUE_ID" ]; then
+  continued_prompt="$(mktemp "$RUN_DIR/.prompt.XXXXXX")" || die "cannot create continued prompt"
+  {
+    printf 'This continues your earlier review of this work. The work has changed since you last\n'
+    printf 'looked. Your working directory is now %s. Re-read files rather than relying on what\n' "$REPO"
+    printf 'you read before. Review this round exactly as instructed below; where it differs from\n'
+    printf "earlier instructions (a threshold, for example), this round's instructions win.\n\n"
+    cat "$PROMPT_FILE"
+  } > "$continued_prompt" && mv "$continued_prompt" "$RUN_DIR/$ROLE.prompt" || { rm -f "$continued_prompt"; die "cannot install continued prompt"; }
+fi
 cp "$PROMPT_FILE" "$RUN_DIR/$ROLE.delivered"
 case "$HARNESS" in opencode|antigravity) PROMPT="$(cat "$PROMPT_FILE")" ;; esac
 
 # --- build argv ---------------------------------------------------------------
-CMD=()
-case "$HARNESS" in
-  codex)
-    if [ "$ROLE" = "qa" ] && [ "$NATIVE_REVIEW" = 1 ]; then
-      # codex's built-in reviewer. Its scope flags are mutually exclusive with a
-      # custom PROMPT, so this mode trades away the goal context: it can judge
-      # whether the diff is correct, but not whether it is the change that was
-      # actually asked for. `codex exec review` also has no --cd, hence the
-      # subshell cd below.
-      CMD=(codex exec review --json -m "$MODEL" --skip-git-repo-check -o "$LAST")
-      [ -n "$EFFORT" ] && CMD+=(-c "model_reasoning_effort=$EFFORT")
-      if [ -n "$REVIEW_BASE" ]; then CMD+=(--base "$REVIEW_BASE"); else CMD+=(--uncommitted); fi
-      if [ "$YOLO" = 1 ]; then CMD+=(--dangerously-bypass-approvals-and-sandbox); fi
-    else
-      CMD=(codex exec --json -m "$MODEL" -C "$REPO" --skip-git-repo-check -o "$LAST")
-      [ -n "$EFFORT" ] && CMD+=(-c "model_reasoning_effort=$EFFORT")
-      # --approve-for-me and --dangerously-bypass-... are mutually exclusive.
-      if [ "$YOLO" = 1 ]; then CMD+=(--dangerously-bypass-approvals-and-sandbox)
-      elif [ "$ROLE" = "dwarf" ]; then CMD+=(--approve-for-me)
-      else CMD+=(-s read-only); fi
-      CMD+=(-)
+# Sets CMD (and PROMPT_VIA_STDIN) for the dispatch, or for the fresh one when CONTINUE_ID is empty.
+build_cmd() {
+  CMD=()
+  case "$HARNESS" in
+    codex)
+      if [ "$ROLE" = "qa" ] && [ "$NATIVE_REVIEW" = 1 ]; then
+        # codex's built-in reviewer. Its scope flags are mutually exclusive with a
+        # custom PROMPT, so this mode trades away the goal context: it can judge
+        # whether the diff is correct, but not whether it is the change that was
+        # actually asked for. `codex exec review` also has no --cd, hence the
+        # subshell cd below.
+        CMD=(codex exec review --json -m "$MODEL" --skip-git-repo-check -o "$LAST")
+        [ -n "$EFFORT" ] && CMD+=(-c "model_reasoning_effort=$EFFORT")
+        if [ -n "$REVIEW_BASE" ]; then CMD+=(--base "$REVIEW_BASE"); else CMD+=(--uncommitted); fi
+        if [ "$YOLO" = 1 ]; then CMD+=(--dangerously-bypass-approvals-and-sandbox); fi
+      elif [ -n "$CONTINUE_ID" ]; then
+        # `codex exec resume` has no -C and no -s, so it runs where it is started (the
+        # subshell cd below) and the sandbox is spelled out as a config override instead
+        # of being left to what the first turn recorded. The quotes are TOML.
+        # An id that starts with '-' would be read as a flag, so it goes after a `--`.
+        CMD=(codex exec resume)
+        case "$CONTINUE_ID" in -*) ;; *) CMD+=("$CONTINUE_ID") ;; esac
+        CMD+=(--json -m "$MODEL" --skip-git-repo-check -o "$LAST")
+        [ -n "$EFFORT" ] && CMD+=(-c "model_reasoning_effort=$EFFORT")
+        if [ "$YOLO" = 1 ]; then CMD+=(--dangerously-bypass-approvals-and-sandbox)
+        else CMD+=(-c 'sandbox_mode="read-only"'); fi
+        case "$CONTINUE_ID" in -*) CMD+=(-- "$CONTINUE_ID") ;; esac
+        CMD+=(-)
+        PROMPT_VIA_STDIN=1
+      else
+        CMD=(codex exec --json -m "$MODEL" -C "$REPO" --skip-git-repo-check -o "$LAST")
+        [ -n "$EFFORT" ] && CMD+=(-c "model_reasoning_effort=$EFFORT")
+        # --approve-for-me and --dangerously-bypass-... are mutually exclusive.
+        if [ "$YOLO" = 1 ]; then CMD+=(--dangerously-bypass-approvals-and-sandbox)
+        elif [ "$ROLE" = "dwarf" ]; then CMD+=(--approve-for-me)
+        else CMD+=(-s read-only); fi
+        CMD+=(-)
+        PROMPT_VIA_STDIN=1
+      fi
+      ;;
+    claude|openclaude)
+      # The run dir sits outside the repo (so it stays out of the diff), which also
+      # puts it outside the harness's default reach — without this the agent
+      # refuses to open the very artifacts forge just wrote for it.
+      CMD=("$HARNESS" -p --model "$MODEL" --add-dir "$RUN_DIR")
+      # One JSON message per line: what the agent said and every tool call, so the run keeps
+      # its conversation (forge-ui reads it), ending in the `result` line forge-runtime.py
+      # takes the final message and the tokens from. stream-json needs --verbose with -p.
+      CMD+=(--output-format stream-json --verbose)
+      [ -n "$EFFORT" ] && CMD+=(--effort "$EFFORT")
+      # Before the variadic flags below, which would otherwise swallow it.
+      # --resume takes an optional value, so an id that starts with '-' is joined with '='.
+      case "$CONTINUE_ID" in
+        '') ;;
+        -*) CMD+=("--resume=$CONTINUE_ID") ;;
+        *) CMD+=(--resume "$CONTINUE_ID") ;;
+      esac
+      if [ "$YOLO" = 1 ]; then
+        CMD+=(--dangerously-skip-permissions)
+      else
+        # `acceptEdits`, not `auto`. Re-measured against this machine's CLIs:
+        # acceptEdits allows both Edit and Bash, whereas `auto` allows Bash but
+        # still prompts for Edit — and a headless dwarf has nobody to answer that
+        # prompt, so it ends with "I need your permission to edit f.py" and an
+        # empty diff. The failure is silent: the harness exits 0 and forge sees a
+        # successful run that changed nothing.
+        CMD+=(--permission-mode acceptEdits)
+        # Neither mode alone is enough, and the gap is silent in both directions:
+        # `auto` allows shell but prompts for Edit, so a dwarf ends with "I need
+        # your permission to edit" and an empty diff; `acceptEdits` allows Edit but
+        # still prompts for any non-trivial shell command, so a dwarf writes code
+        # and then stalls on "awaiting approval to run pytest" without ever
+        # verifying it. acceptEdits plus an explicit Bash allowance gives both, and
+        # QA's --disallowed-tools below still overrides the edit permission.
+        CMD+=(--allowedTools "Bash")
+        # Disable editing tools as defense in depth. Bash can still write files;
+        # runners use disposable snapshots and fingerprint checks for acceptance.
+        read_only_role && CMD+=(--disallowed-tools "Edit,Write,NotebookEdit")
+      fi
+      # The prompt goes on stdin, not argv. --disallowed-tools and friends are
+      # variadic, so any positional after them is silently eaten as another tool
+      # name — the run then dies on "Input must be provided" if you are lucky, or
+      # reviews nothing at all if you are not. stdin also lifts the argv length
+      # limit, which a long goal plus an inlined diff will otherwise hit.
       PROMPT_VIA_STDIN=1
-    fi
-    ;;
-  claude|openclaude)
-    # The run dir sits outside the repo (so it stays out of the diff), which also
-    # puts it outside the harness's default reach — without this the agent
-    # refuses to open the very artifacts forge just wrote for it.
-    CMD=("$HARNESS" -p --model "$MODEL" --add-dir "$RUN_DIR")
-    # One JSON message per line: what the agent said and every tool call, so the run keeps
-    # its conversation (forge-ui reads it), ending in the `result` line forge-runtime.py
-    # takes the final message and the tokens from. stream-json needs --verbose with -p.
-    CMD+=(--output-format stream-json --verbose)
-    [ -n "$EFFORT" ] && CMD+=(--effort "$EFFORT")
-    if [ "$YOLO" = 1 ]; then
-      CMD+=(--dangerously-skip-permissions)
-    else
-      # `acceptEdits`, not `auto`. Re-measured against this machine's CLIs:
-      # acceptEdits allows both Edit and Bash, whereas `auto` allows Bash but
-      # still prompts for Edit — and a headless dwarf has nobody to answer that
-      # prompt, so it ends with "I need your permission to edit f.py" and an
-      # empty diff. The failure is silent: the harness exits 0 and forge sees a
-      # successful run that changed nothing.
-      CMD+=(--permission-mode acceptEdits)
-      # Neither mode alone is enough, and the gap is silent in both directions:
-      # `auto` allows shell but prompts for Edit, so a dwarf ends with "I need
-      # your permission to edit" and an empty diff; `acceptEdits` allows Edit but
-      # still prompts for any non-trivial shell command, so a dwarf writes code
-      # and then stalls on "awaiting approval to run pytest" without ever
-      # verifying it. acceptEdits plus an explicit Bash allowance gives both, and
-      # QA's --disallowed-tools below still overrides the edit permission.
-      CMD+=(--allowedTools "Bash")
-      # Disable editing tools as defense in depth. Bash can still write files;
-      # runners use disposable snapshots and fingerprint checks for acceptance.
-      read_only_role && CMD+=(--disallowed-tools "Edit,Write,NotebookEdit")
-    fi
-    # The prompt goes on stdin, not argv. --disallowed-tools and friends are
-    # variadic, so any positional after them is silently eaten as another tool
-    # name — the run then dies on "Input must be provided" if you are lucky, or
-    # reviews nothing at all if you are not. stdin also lifts the argv length
-    # limit, which a long goal plus an inlined diff will otherwise hit.
-    PROMPT_VIA_STDIN=1
-    ;;
-  opencode)
-    CMD=(opencode run -m "$MODEL" --dir "$REPO")
-    [ -n "$EFFORT" ] && CMD+=(--variant "$EFFORT")
-    # opencode run exposes no sandbox tier — without --auto it blocks on a
-    # permission prompt that nothing can answer headlessly, so it is always set.
-    CMD+=(--auto)
-    read_only_role && [ "$YOLO" != 1 ] && CMD+=(--agent plan)
-    # One JSON event per line (text, tool_use, step_finish, error): the conversation, the
-    # final message and the tokens, read by forge-runtime.py and forge-ui.
-    CMD+=(--format json)
-    CMD+=("$PROMPT")
-    ;;
-  antigravity)
-    # `agy --print` is a Go flag with an OPTIONAL value: written detached it eats
-    # whatever token follows as its prompt ("--print took --print-timeout as its
-    # prompt"). The attached --print=... form is the only safe spelling, and it
-    # goes last so nothing can be captured after it.
-    CMD=(agy --model "$MODEL" --print-timeout "$AGY_TIMEOUT")
-    [ -n "$EFFORT" ] && CMD+=(--effort "$EFFORT")
-    # --add-dir on the repo is not optional. Antigravity is workspace-scoped
-    # rather than cwd-scoped, so without it the agent searches the wrong tree and
-    # the run dies on "Find command timed out: context deadline exceeded".
-    CMD+=(--add-dir "$REPO" --add-dir "$RUN_DIR")
-    if [ "$YOLO" = 1 ]; then CMD+=(--dangerously-skip-permissions)
-    elif read_only_role; then CMD+=(--mode plan)
-    else CMD+=(--mode accept-edits); fi
-    CMD+=(--print="$PROMPT")
-    ;;
-  grok)
-    # Headless grok refuses any tool call that needs approval and still exits 0
-    # ("permission required: Edit calc.py was not run"): the same silent empty diff
-    # claude gives without acceptEdits, so the dwarf gets edits and the whole shell.
-    # The Messages-format stream ends in a claude-shaped `result` line, which
-    # forge-runtime.py reads for the final message and the tokens.
-    CMD=(grok --model "$MODEL" --prompt-file "$PROMPT_FILE" --output-format streaming-messages-json)
-    [ -n "$EFFORT" ] && CMD+=(--reasoning-effort "$EFFORT")
-    if [ "$YOLO" = 1 ]; then
-      CMD+=(--always-approve)
-    else
-      CMD+=(--permission-mode acceptEdits --allow Bash)
-      # A deny rule beats the mode and every allow, so a reviewer keeps its shell for
-      # running tests but cannot edit. Bash can still write files, as with claude.
-      read_only_role && CMD+=(--deny Edit --deny Write)
-    fi
-    ;;
-  *) die "no dispatch recipe for harness '$HARNESS'" ;;
-esac
+      ;;
+    opencode)
+      CMD=(opencode run -m "$MODEL" --dir "$REPO")
+      [ -n "$EFFORT" ] && CMD+=(--variant "$EFFORT")
+      # opencode run exposes no sandbox tier — without --auto it blocks on a
+      # permission prompt that nothing can answer headlessly, so it is always set.
+      CMD+=(--auto)
+      read_only_role && [ "$YOLO" != 1 ] && CMD+=(--agent plan)
+      # One JSON event per line (text, tool_use, step_finish, error): the conversation, the
+      # final message and the tokens, read by forge-runtime.py and forge-ui.
+      CMD+=(--format json)
+      CMD+=("$PROMPT")
+      ;;
+    antigravity)
+      # `agy --print` is a Go flag with an OPTIONAL value: written detached it eats
+      # whatever token follows as its prompt ("--print took --print-timeout as its
+      # prompt"). The attached --print=... form is the only safe spelling, and it
+      # goes last so nothing can be captured after it.
+      CMD=(agy --model "$MODEL" --print-timeout "$AGY_TIMEOUT")
+      [ -n "$EFFORT" ] && CMD+=(--effort "$EFFORT")
+      # --add-dir on the repo is not optional. Antigravity is workspace-scoped
+      # rather than cwd-scoped, so without it the agent searches the wrong tree and
+      # the run dies on "Find command timed out: context deadline exceeded".
+      CMD+=(--add-dir "$REPO" --add-dir "$RUN_DIR")
+      if [ "$YOLO" = 1 ]; then CMD+=(--dangerously-skip-permissions)
+      elif read_only_role; then CMD+=(--mode plan)
+      else CMD+=(--mode accept-edits); fi
+      CMD+=(--print="$PROMPT")
+      ;;
+    grok)
+      # Headless grok refuses any tool call that needs approval and still exits 0
+      # ("permission required: Edit calc.py was not run"): the same silent empty diff
+      # claude gives without acceptEdits, so the dwarf gets edits and the whole shell.
+      # The Messages-format stream ends in a claude-shaped `result` line, which
+      # forge-runtime.py reads for the final message and the tokens.
+      CMD=(grok --model "$MODEL" --prompt-file "$PROMPT_FILE" --output-format streaming-messages-json)
+      [ -n "$EFFORT" ] && CMD+=(--reasoning-effort "$EFFORT")
+      # After its last turn a headless run waits for the background work it started (a test
+      # suite, say) and wakes the model with each result, but by default for only 600 s: then
+      # it stops that work and exits 1, and a dwarf whose suite outlasts the wait ends as an
+      # error. forge's own limit bounds the run instead. grok counts from the last turn and
+      # forge from the start, so forge's watchdog always fires first; a day stands in for no
+      # limit (grok refuses 0).
+      if [ "$LIMIT" = 0 ]; then CMD+=(--background-wait-timeout 86400)
+      else CMD+=(--background-wait-timeout "$LIMIT"); fi
+      if [ "$YOLO" = 1 ]; then
+        CMD+=(--always-approve)
+      else
+        CMD+=(--permission-mode acceptEdits --allow Bash)
+        # A deny rule beats the mode and every allow, so a reviewer keeps its shell for
+        # running tests but cannot edit. Bash can still write files, as with claude.
+        read_only_role && CMD+=(--deny Edit --deny Write)
+      fi
+      ;;
+    *) die "no dispatch recipe for harness '$HARNESS'" ;;
+  esac
+}
+build_cmd
 
 # Offline validation uses the exact command recipe, never a model request.
-preflight_command() {
-  local bin help arg flag
-  local help_args=(--help)
-  bin="$(command -v "$(binary_for "$HARNESS")")" || die "harness '$HARNESS' is not installed" 3
-  case "$HARNESS" in
-    codex) help_args=(exec --help); [ "$NATIVE_REVIEW" = 1 ] && help_args=(exec review --help) ;;
-    opencode) help_args=(run --help) ;;
-  esac
-  help="$(python3 "$RUNTIME" help "${FORGE_CAPABILITY_CACHE:-$RUN_DIR/capabilities}" "$REGISTRY" "${BASH_SOURCE[0]}" "$bin" "${help_args[@]}")" || die "cannot read $HARNESS help" 3
+capability_help() { # capability_help <binary> <help args...>
+  python3 "$RUNTIME" help "${FORGE_CAPABILITY_CACHE:-$RUN_DIR/capabilities}" "$REGISTRY" "${BASH_SOURCE[0]}" "$@"
+}
+# Prints the first flag of CMD the help text does not advertise; fails when all are.
+unadvertised_flag() { # unadvertised_flag <help text>
+  local arg flag
   for arg in "${CMD[@]:1}"; do
     [ "$arg" = "$PROMPT" ] && continue
     [ "$arg" = - ] && continue
+    [ "$arg" = -- ] && continue
+    [ -n "$CONTINUE_ID" ] && [ "$arg" = "$CONTINUE_ID" ] && continue
     case "$arg" in
       -*) flag="${arg%%=*}"
-          printf '%s\n' "$help" | grep -E -- "(^|[[:space:],|])$flag([=[:space:],|]|$)" >/dev/null || die "$HARNESS does not advertise required flag $flag" 3 ;;
+          # grok's help hides this one; preflight_command checks it with a probe instead.
+          [ "$HARNESS $flag" = "grok --background-wait-timeout" ] && continue
+          printf '%s\n' "$1" | grep -E -- "(^|[[:space:],|])$flag([=[:space:],|]|$)" >/dev/null || { printf '%s' "$flag"; return 0; } ;;
     esac
   done
+  return 1
+}
+preflight_command() {
+  local bin help flag request="$CONTINUE_ID"
+  local help_args=(--help) continue_args=(--help)
+  bin="$(command -v "$(binary_for "$HARNESS")")" || die "harness '$HARNESS' is not installed" 3
+  case "$HARNESS" in
+    codex) help_args=(exec --help); continue_args=(exec resume --help); [ "$NATIVE_REVIEW" = 1 ] && help_args=(exec review --help) ;;
+    opencode) help_args=(run --help) ;;
+  esac
+  # grok's help hides --background-wait-timeout, which every grok recipe passes. grok checks
+  # every flag and its value before it answers --help, so a help call with the flag in front
+  # proves it exists.
+  if [ "$HARNESS" = grok ]; then
+    capability_help "$bin" --background-wait-timeout 1 --help >/dev/null 2>&1 \
+      || die "$HARNESS does not accept required flag --background-wait-timeout (update $HARNESS)" 3
+  fi
+  if [ -n "$CONTINUE_ID" ]; then
+    # codex's resume subcommand has its own help, so its flags are checked against that one.
+    if help="$(capability_help "$bin" "${continue_args[@]}" 2>/dev/null)" && ! unadvertised_flag "$help" >/dev/null; then
+      return 0
+    fi
+    # Cannot continue. Say so only if a fresh dispatch would have worked; otherwise this is
+    # the harness being unusable, which keeps its exit 3 below.
+    CONTINUE_ID=""; build_cmd
+    preflight_command
+    CONTINUE_ID="$request"
+    write_continue failed unsupported
+    note "$HARNESS does not advertise what continuing a session needs; the caller may dispatch fresh"
+    exit 9
+  fi
+  help="$(capability_help "$bin" "${help_args[@]}")" || die "cannot read $HARNESS help" 3
+  flag="$(unadvertised_flag "$help")" && die "$HARNESS does not advertise required flag $flag" 3
+  return 0
 }
 [ -z "$ATTEMPT" ] || python3 "$RUNTIME" phase "$ATTEMPT" preflight
 if [ "$DRY" != 1 ] || [ "$PREFLIGHT" = 1 ]; then preflight_command; fi
@@ -631,6 +732,7 @@ echo "duration_s=$DURATION" >> "$RUN_DIR/$ROLE.resolved"
 [ "$OUTPUT" != summary ] || echo "forge: role=$ROLE backend_exit=$rc final=$LAST log=$LOG metrics=$ATTEMPT/metrics.json"
 if [ -f "$RUN_DIR/$ROLE.timedout" ]; then
   note "$HARNESS exceeded the ${LIMIT}s timeout and was killed after ${DURATION}s — see $LOG"
+  write_continue failed timeout
   exit 7
 fi
 # Infrastructure, not the model's work: auth, quota, rate limit, network, or an answer that
@@ -661,11 +763,23 @@ if [ -n "$INFRA" ]; then
     note "$HARNESS cancelled the $ROLE before it finished: $infra_detail — recorded in $RUN_DIR/$ROLE.infra"
   else
     note "$HARNESS failed on infrastructure ($infra_class${infra_after:+, retry after ${infra_after}s}): $infra_detail — see $LOG"
+    write_continue failed "infrastructure: $infra_class"
     exit 8
   fi
 fi
 if [ "$rc" -ne 0 ]; then
   note "$HARNESS exited $rc — see $LOG"
+  if [ -n "$CONTINUE_ID" ]; then
+    # The log's last error-looking line, else its last line, on one line.
+    reason="$(grep -i -E 'error|fail|not found|no conversation|invalid|unknown' "$LOG" 2>/dev/null | tail -n 1)"
+    [ -n "$reason" ] || reason="$(grep '[^[:space:]]' "$LOG" 2>/dev/null | tail -n 1)"
+    reason="$(printf '%s' "$reason" | tr '\r\t\n' '   ')"
+    [ -n "${reason// }" ] || reason="$HARNESS exited $rc"
+    write_continue failed "${reason:0:200}"
+    note "the session was not continued; the caller may dispatch fresh"
+    exit 9
+  fi
   exit 4
 fi
+write_continue continued
 echo "forge: $ROLE done in ${DURATION}s -> $LAST" >&2