@giamme/forge 0.10.0 → 0.11.1

package/references/decompose.md

@@ -266,8 +266,10 @@ So:
 ## The capsule
 
 Every dispatch is a clean slate — forge never passes `--continue`, `--resume`, or
-`codex exec resume`. That keeps one task's confused turn from poisoning another and keeps
-each task's context small, but it also leaves each dwarf blind to the wider run.
+`codex exec resume`, except the opt-in `plan --reviewer-session` experiment (it continues
+a reviewer's session across rounds on claude, openclaude and codex). That keeps one task's
+confused turn from poisoning another and keeps each task's context small, but it also
+leaves each dwarf blind to the wider run.
 
 `tasks/<id>/capsule.md` records ownership and baseline context. `baseline.capsule` preserves
 the implementation-time capsule for QA. MERGED means the reviewed commit is an ancestor of
@@ -275,7 +277,8 @@ this task's pinned baseline, not merely that another task finished while QA was
 Complete requirements, approach, retry findings and distinct memory facts are assembled once
 per role; implementation and review instructions are separate.
 
-It exists to prevent two specific failures that clean slates create:
+It exists to prevent two specific failures that clean slates create, which the opt-in
+`--reviewer-session` experiment does not change:
 
 - a dwarf reimplementing a helper an earlier task already merged, because nothing told it
   that task was done;
@@ -425,7 +428,8 @@ Two details that are load-bearing rather than incidental:
   diff.
 - **An identical retry is not re-reviewed.** If the diff comes back byte-identical to the
   previous attempt, the task fails again without a QA dispatch. Paying a reviewer to read
-  the same code twice buys nothing.
+  the same code twice buys nothing. A retry that only rejects the findings, and leaves
+  that diff unchanged, is still this identical retry.
 
 `retry` is a command a human types. Forge does not loop a dwarf against its own reviewer on
 its own initiative; the one exception is the opt-in `run --retry-failed N` below.
@@ -437,6 +441,14 @@ work: no dwarf, no new commit, no attempt spent. A `tasks/<id>/resume` marker re
 revalidated against the branch tip and the saved source fingerprint before it is trusted; if the
 worktree changed, the full task runs. Findings are carried only from a real review.
 
+On a retry whose diff changed, QA receives the previous round under **Findings from the
+previous review round**, the diff since that round (`tasks/<id>/changes.since.diff`,
+`changes.since.range` and `changes.since.stat`; omitted when the earlier commit is
+missing or not an ancestor, or when nothing changed) and the implementer's reply. It is
+told to restate only findings that are still open, as `- [Px][CONFIRMED|PLAUSIBLE]`
+lines, because every labelled line is counted. That is the retry's review, not the
+QA-only re-run above.
+
 **In-run retries.** `run <plan> --retry-failed N` re-queues a task whose reviewer said
 `FAIL`/`UNKNOWN` as soon as it ends, up to `N` more times in that run, preparing the retry exactly
 as `retry` does (same findings carry-forward, same pinned base, same cumulative review). Other
@@ -466,6 +478,10 @@ turns it off):
   QA-only resume, which spends no implementer attempt.
 - **Reporting:** the policy's state is decided after every attempt, so a run whose retry budget ran out
   still reports `its next retry goes to <spec>` or the split suggestion under the results.
+  A pending pin is reported ahead of both, as `its next retry goes to <spec> (pinned)`, or
+  `(pinned; after the QA-only re-run)` only when the next entry really re-runs QA (the
+  `resume` marker, or an unreviewed verdict, still matches the worktree). A marker the
+  next retry will discard is not that wait.
 
 History cannot yet say whether escalating rescues a task (31% of the 29 later attempts on a
 changed spec passed, mostly effort bumps); the attempts this policy makes are what will.
@@ -480,8 +496,10 @@ decision, removed when it stops; `tasks/<id>/retries.used` stays), so a change d
 run. `pin <task> <spec>` sets the model the task's next full retry uses, once (checked with
 `forge-dispatch.sh doctor`, no quota): `prepare_retry` claims `escalation.pin` as
 `escalation.pin.applying`, rewrites `tasks.tsv`, appends the `escalations.tsv` row with
-`source=pin`, clears `escalation.stop`/`split.suggested`, then consumes the pin. A QA-only resume
-leaves it for the next full retry; Fractal plans never apply pins; a MERGED task refuses one.
+`source=pin`, clears `escalation.stop`/`split.suggested`, then consumes the pin. A symlinked
+`escalations.tsv`, or a symlink in any directory from the plan down to it, is not written:
+the pin stays and nothing is retried. A QA-only resume leaves it for the next full retry;
+Fractal plans never apply pins; a MERGED task refuses one.
 The last column of `escalations.tsv` says who decided: `policy`, `retry` (an explicit
 `--dwarf`) or `pin`; four-column rows read as `policy`. Every change goes to `control.log` (JSON lines:
 `at`, `actor` `cli|ui`, `action`, `task`, `key`, `value`, `previous`) and to the dataset as a

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)