tangled tools: tangled_pr_resubmit.py — a push does not advance a PR round

Pushing a fixup to the source branch does NOT update the pull: the appview serves the patch
it fetched when the pull was opened or last resubmitted, so a reviewer keeps reading the
pre-fixup code and no `/round/<r>/interdiff` exists. Nothing warns you — the push succeeded,
the branch is right, the pull silently lags. It cost a review cycle on 2026-08-16 (three
flat-file PRs reviewed against stale trees because "pushed" was read as "resubmitted").

The appview's action is a bare htmx POST with no body,
`POST /{owner}/{repo}/pulls/{n}/resubmit`, which re-fetches the branch patch from the knot
and opens the next round. The tool wraps it and:

- takes several `--pull` numbers at once (a stack-wide rebase touches every rung);
- prints the new round and its interdiff URL — what a reply to a reviewer leads with;
- says plainly when the round did NOT move (the branch already matched the pull) instead of
  reporting a silent success;
- `--check` reports the current round without posting.

It reads the round from the round selector rather than the page text, because a comment that
quotes a `/round/2/interdiff` URL would otherwise be counted as a round (that fooled me
first).

README gains a table of the Tangled tools, which did not exist, and states the trap.

README.md

@@ -357,6 +357,28 @@ Run it by hand with `engine/agents.py up --config agents.toml`.
 
 ---
 
+## Tangled (the atproto forge) — the PR tools
+
+One tool per action, all reading `tangled.cookie` from the secret store (`--cookie-file` is a
+legacy fallback). They exist because Tangled has no client CLI: each action is an htmx POST to
+the appview that only a logged-in session can make.
+
+| tool | action |
+|---|---|
+| `tangled_pr.py` | open a pull (branch-based; `--target` is the branch it merges into) |
+| `tangled_pr_edit.py` | edit a pull's title/body, or `--show` the current one |
+| `tangled_pr_resubmit.py` | **advance a pull to a new round after you pushed a fixup**, and print the interdiff URL |
+| `tangled_pr_merge.py` | `--check` mergeability, then `--merge` or `--close` |
+| `tangled_comments.py` | read a pull's review comments (`--json` for machine use) |
+| `tangled_comment_post.py` | post a comment on a pull |
+| `tangled_repo.py` | create a repo as the bot (see also the `tangled-repo` skill) |
+
+**The trap `tangled_pr_resubmit.py` exists for:** pushing the branch does NOT update the pull.
+The appview keeps serving the patch it fetched when the pull was opened or last resubmitted,
+so reviewers read the pre-fixup code and no interdiff exists — with no warning, because the
+push itself succeeded. Always: push, resubmit, then reply with the printed interdiff URL. See
+`machine-docs/PR-WORKFLOW.md`, "A push does NOT advance the round".
+
 ## Secrets — one encrypted store, never in git
 
 **Every credential on an orchestrator host lives in one sops+age encrypted file. Do not put a