ci(port): track upstream HEAD instead of the latest published release

The pipeline resolved the latest npm release and ported its tag. That is why
today's cron run found "no changes" while upstream main carried an unported
doom-loop commit (#73) — ~7,500 lines, ~4,700 of it tests, rewriting a large part
of model-result.ts. Release tracking sounds conservative and produces exactly the
failure this pipeline exists to prevent: the port stays blind to unreleased work,
then absorbs the whole delta in one automated run against the most load-bearing
module in the package. Tracking HEAD keeps each delta reviewable.

Ref resolution

- The workflow no longer queries the npm registry. A blank ref means upstream
  default-branch HEAD, which scripts/upstream already resolves on its own.
- The publish dispatch's client_payload.ref is now deliberately IGNORED (with a
  ::notice:: saying so). It carries the release tag, which becomes an ancestor of
  HEAD as soon as the port is ahead of the release — honoring it would revert
  landed work. The dispatch still does its real job: waking the pipeline promptly
  after a release. It just syncs to HEAD like every other trigger.
- Fixed a latent bug in the Run port step: it passed `--ref ""` when no ref was
  resolved. The arg parser consumes the empty value, so that is not the same as
  omitting the flag. Now the flag is only passed when there is a ref. Verified all
  four arg combinations parse correctly.

Refusing to port backwards

scripts/upstream now exits 3 if the target commit is an ancestor of
state.yaml's upstream_commit, printing how many commits behind it is and pointing
at --force as the deliberate override. Without this, a single stale --ref (or a
dispatch payload, before the change above) would instruct the converter to
faithfully port an older tree and silently revert everything since. Verified: the
guard fires on the real 0.8.0 tag once state claims HEAD, and --force bypasses it.

Version honesty when ahead of a release

Being ahead is now the normal state, and it is invisible to the old check:
package.json on main still carries the last released number, so pyproject.toml
matches it and the check passes — while the tree contains unreleased work.

- verify.sh now also compares the ported commit against the release tag for the
  declared version. Level with the tag PASSes as publishable; ahead prints a NOTE
  with the commit count and an explicit "do not publish this version" warning.
  Ahead is not a failure — it is the intended state — so it does not fail the run.
- publish.yaml gets a hard gate, because verify.sh's NOTE only appears when a sync
  run has left an upstream checkout in tmp/, and there is none at publish time. It
  clones upstream, requires a release tag matching the declared version, and
  refuses if the ported commit is ahead of it. Verified in all three states: level
  allows, ahead refuses, missing tag refuses.

Publishing X.Y.Z from a tree ahead of upstream's X.Y.Z tag ships unreleased work
under a released number, and a PyPI version can never be reused.

Also: exclude tmp/ from ruff

Found while testing: a port run writes scratch files under tmp/ (gitignored, but
ruff still walks it), and one stray probe script failed `ruff check` and
`ruff format` — 22 errors that had nothing to do with the port. A sync run could
fail its own mechanical gate on its own scratch space. mypy was already scoped to
src/tests and unaffected.

Docs

PORTING.md's pipeline diagram now shows the real trigger set and the backwards
refusal, plus a section on why HEAD over releases and the two consequences. The
contract's Package Version section says between-releases is now the normal state,
tells a sync to report how far ahead it is, and states the publishing rule.

Verification: verify.sh PASS (0 failures) · all three workflows parse · guard and
publish-gate logic each verified in three states · ruff/mypy clean with a
deliberately broken file in tmp/ · 114 passed, coverage 83.89%.

Co-Authored-By: Claude <noreply@anthropic.com>

Author: LukasParke

.github/workflows/publish.yaml

@@ -87,6 +87,41 @@ jobs:
       - name: Verify (lint, types, tests, coverage floor, required API)
         run: ./.upstreamer/scripts/verify.sh
 
+      # The port tracks upstream HEAD, so it is routinely AHEAD of the release
+      # whose version number pyproject.toml carries. Publishing from that state
+      # would ship unreleased upstream work as a released version — permanently,
+      # since a PyPI version can never be reused.
+      #
+      # verify.sh reports this, but only when a sync run has left an upstream
+      # checkout in tmp/. There is none here, so check it explicitly against the
+      # public repo rather than letting the guard be silent at the one moment it
+      # matters most.
+      - name: Refuse to publish a version the port is ahead of
+        run: |
+          set -euo pipefail
+          VERSION="$(grep -m1 '^version' pyproject.toml | sed 's/.*"\(.*\)".*/\1/')"
+          PORTED="$(grep -m1 '^upstream_commit:' .upstreamer/state.yaml | awk '{print $2}')"
+          echo "declared version: $VERSION"
+          echo "ported commit:    $PORTED"
+
+          rm -rf /tmp/upstream-check
+          git clone -q --filter=blob:none --no-checkout \
+            https://github.com/OpenRouterTeam/typescript-agent.git /tmp/upstream-check
+          git -C /tmp/upstream-check fetch -q --tags origin
+
+          TAG="@openrouter/agent@${VERSION}"
+          if ! git -C /tmp/upstream-check rev-parse -q --verify "refs/tags/$TAG" >/dev/null; then
+            echo "::error::Upstream has no release tag $TAG. This package's version tracks the ported @openrouter/agent version, so publishing $VERSION means upstream released it. Wait for the upstream release, or correct the version."
+            exit 1
+          fi
+
+          AHEAD="$(git -C /tmp/upstream-check rev-list --count "refs/tags/$TAG..$PORTED" 2>/dev/null || echo 0)"
+          if [ "${AHEAD:-0}" -gt 0 ]; then
+            echo "::error::The ported commit is $AHEAD commit(s) ahead of the $TAG release tag. Publishing $VERSION now would ship unreleased upstream work under a released version number, and a PyPI version can never be reused. Publish from a commit level with a release tag, or wait for upstream to release what the port has reached."
+            exit 1
+          fi
+          echo "Ported tree is level with $TAG — $VERSION is honest to publish."
+
       - name: Build sdist and wheel
         run: |
           set -euo pipefail

.github/workflows/upstreamer-port.yaml

@@ -1,10 +1,27 @@
 name: Upstreamer Port
 
-# Ports @openrouter/agent into this repo. Two triggers:
-#   1. repository_dispatch from typescript-agent's publish.yaml on a new npm release
-#      (event type: openrouter-agent-published) — the intended path. Ports track
-#      published releases, not every commit to upstream main.
-#   2. Weekly cron as a safety net for missed dispatches, plus manual dispatch.
+# Ports @openrouter/agent into this repo.
+#
+# The port tracks upstream's **default-branch HEAD**, not the latest published npm
+# release. Release tracking sounds safer but produces exactly the failure this
+# pipeline exists to prevent: upstream can sit for weeks with large unreleased
+# work on main (doom-loop detection, #73, was ~7.5k lines) and the port stays
+# blind to it, then absorbs the whole delta in one automated run touching the most
+# load-bearing modules. Tracking HEAD keeps each delta small enough to review.
+#
+# Consequence to keep in mind: the port is then routinely AHEAD of the latest
+# release, so its declared version legitimately lags upstream's package.json. The
+# verifier reports that rather than failing, and publishing is gated on it — see
+# the Package Version section of .upstreamer/upstreamer.md.
+#
+# Three triggers, all resolving to HEAD unless given an explicit ref:
+#   1. Weekly cron — the primary path now that releases are not the trigger.
+#   2. repository_dispatch from typescript-agent's publish.yaml on a new npm
+#      release. Still useful as a "something just shipped, sync promptly" nudge,
+#      but it no longer pins the ref to that release tag: doing so would port
+#      BACKWARDS once the port is ahead of the release. scripts/upstream refuses
+#      an ancestor ref outright.
+#   3. Manual dispatch, optionally with an explicit ref.
 #
 # Opens a PR. Never pushes to main. A failed parity eval leaves
 # .upstreamer/state.yaml unchanged, so the next run retries the same delta.
@@ -52,21 +69,29 @@ jobs:
       - name: Set up language toolchain
         uses: ./.github/actions/port-toolchain
 
-      # Ports track published releases, not upstream main. When no ref arrives
-      # (cron, or a manual dispatch with the input left blank), resolve the
-      # latest published @openrouter/agent version from the public npm registry
-      # and port its release tag. This makes the cron fully equivalent to the
-      # repository_dispatch fast path — same tag either way — so the pipeline
-      # works with no cross-repo token at all if the dispatch is unavailable.
+      # Blank ref = upstream default-branch HEAD, which scripts/upstream resolves
+      # itself. That is the normal case for both the cron and a publish dispatch.
+      #
+      # Only an EXPLICIT manual `ref` input is honored. The publish dispatch's
+      # client_payload.ref is deliberately ignored: it carries the release tag,
+      # which is an ancestor of HEAD once the port is ahead of the release, so
+      # honoring it would revert landed work. The dispatch still does its real
+      # job — waking the pipeline promptly after a release — it just syncs to HEAD
+      # like every other trigger. (scripts/upstream also refuses an ancestor ref
+      # outright, so this is defense in depth, not the only guard.)
       - name: Resolve target ref
         id: target
         run: |
           set -euo pipefail
-          REF="${{ inputs.ref || github.event.client_payload.ref }}"
-          if [ -z "$REF" ]; then
-            VERSION="$(curl -fsSL 'https://registry.npmjs.org/@openrouter%2Fagent/latest' | python3 -c 'import json,sys; print(json.load(sys.stdin)["version"])')"
-            REF="@openrouter/agent@${VERSION}"
-            echo "No ref provided — resolved latest npm release: $REF"
+          REF="${{ inputs.ref }}"
+          if [ -n "$REF" ]; then
+            echo "Explicit ref requested: $REF"
+          else
+            PAYLOAD_REF="${{ github.event.client_payload.ref }}"
+            if [ -n "$PAYLOAD_REF" ]; then
+              echo "::notice::Ignoring dispatch payload ref '$PAYLOAD_REF' — this port tracks upstream HEAD, and a release tag is an ancestor once the port is ahead of it. Syncing to HEAD instead."
+            fi
+            echo "No explicit ref — porting upstream default-branch HEAD."
           fi
           echo "ref=$REF" >> "$GITHUB_OUTPUT"
 
@@ -84,9 +109,14 @@ jobs:
             echo "::error::OPENROUTER_API_KEY secret is not set. See .upstreamer/port.env.example."
             exit 1
           fi
-          args=(--ref "${{ steps.target.outputs.ref }}")
+          # Only pass --ref when there is actually a ref. `--ref ""` is not the
+          # same as omitting it: the arg parser consumes the empty value and the
+          # script would target an empty ref instead of defaulting to HEAD.
+          args=()
+          REF="${{ steps.target.outputs.ref }}"
+          [ -n "$REF" ] && args+=(--ref "$REF")
           [ "${{ inputs.force }}" = "true" ] && args+=(--force)
-          ./scripts/upstream "${args[@]}"
+          ./scripts/upstream ${args[@]+"${args[@]}"}
 
       - name: Check for changes
         id: diff

.upstreamer/scripts/verify.sh

@@ -86,6 +86,30 @@ if [ -f "$upstream_pkg" ]; then
   else
     fail "version drift: pyproject.toml=$declared, upstream @openrouter/agent=$target"
   fi
+
+  # This port tracks upstream HEAD, so it routinely contains work that upstream
+  # has not released. package.json still carries the last released number, so the
+  # check above passes — and the port would publish "0.8.0" while containing
+  # post-0.8.0 commits. Not a verifier failure (being ahead is the intended
+  # state), but it must be visible, because publishing it as a released version
+  # number is a real misrepresentation and PyPI versions cannot be reused.
+  upstream_git="tmp/upstreamer/upstream"
+  if [ -d "$upstream_git/.git" ]; then
+    ported_sha="$(git -C "$upstream_git" rev-parse HEAD 2>/dev/null || true)"
+    rel_tag="$(git -C "$upstream_git" tag -l "@openrouter/agent@$target" | head -1)"
+    if [ -n "$ported_sha" ] && [ -n "$rel_tag" ]; then
+      ahead="$(git -C "$upstream_git" rev-list --count "$rel_tag^{commit}..$ported_sha" 2>/dev/null || echo 0)"
+      if [ "${ahead:-0}" -gt 0 ]; then
+        echo "  NOTE: ported tree is $ahead commit(s) ahead of the $target release tag."
+        echo "        Declaring $declared is correct for the port, but do NOT publish"
+        echo "        $declared to PyPI from this state — it would ship unreleased"
+        echo "        upstream work under a released version number. Publish only from"
+        echo "        a commit level with a release tag, or after upstream releases."
+      else
+        pass "ported tree is level with the $target release tag (publishable)"
+      fi
+    fi
+  fi
 else
   # Only present during a sync run. Standalone/CI invocations legitimately have no
   # upstream checkout; not a failure, but say so rather than passing silently.

.upstreamer/upstreamer.md

@@ -65,13 +65,24 @@ output. Leave them alone.
 ## Package Version
 
 `pyproject.toml` `version` tracks the ported `@openrouter/agent` version. Read it
-from the upstream `packages/agent/package.json` at the target commit and set it
-to match. If the target commit is between releases, keep the last released
-version and note the drift in the final report.
-
-Publishing is gated on this: a released version can never be reused on PyPI, so a
-sync that bumps the version is what makes the next release possible. Never bump it
-past what was actually ported.
+from the upstream `packages/agent/package.json` at the target commit and set it to
+match. Never set it past what was actually ported.
+
+**This port targets upstream HEAD, so between-releases is the normal state, not the
+exception.** `package.json` on `main` still carries the last released number, so
+matching it is correct and the verifier passes — but the ported tree then contains
+commits upstream has not released. When that is the case:
+
+- Keep `version` at the number `package.json` shows. Do not invent a
+  pre-release suffix; the verifier compares against `package.json` exactly.
+- **Say so in the final report**: how many commits ahead of the release tag the
+  target is, and what unreleased upstream work is now included. The verifier
+  prints this as a `NOTE`, but the report is what a reviewer reads.
+
+Publishing is gated on this. A released version can never be reused on PyPI, so
+publishing `X.Y.Z` from a tree that is ahead of upstream's `X.Y.Z` tag ships
+unreleased work under a released number, permanently. Release from a commit level
+with a release tag, or after upstream publishes the version the port has reached.
 
 ## Required Public API
 

PORTING.md

@@ -9,27 +9,58 @@ listed in the Idiomatic Divergences section of `.upstreamer/upstreamer.md`.
 
 ## How it works
 
+The port tracks upstream's **default-branch HEAD**, not the latest published npm
+release.
+
 ```
-typescript-agent publishes @openrouter/agent to npm
-        │
-        │  repository_dispatch: openrouter-agent-published
+   weekly cron  ·  publish dispatch  ·  manual dispatch
+        │              (a nudge,          (optional
+        │               not a ref)         explicit ref)
         ▼
 .github/workflows/upstreamer-port.yaml
-        │
+        │  resolve ref: explicit input, else upstream HEAD
         ▼
 scripts/upstream
         │  1. fetch upstream, resolve target commit
-        │  2. compare against .upstreamer/state.yaml — skip if unchanged
-        │  3. opencode runs the port against .upstreamer/upstreamer.md
-        │  4. .upstreamer/scripts/verify.sh   (mechanical gate)
-        │  5. .upstreamer/eval.md            (parity gate, fresh context)
-        │  6. advance state.yaml — ONLY if both gates pass
+        │  2. REFUSE if target is behind state.yaml (would revert work)
+        │  3. compare against .upstreamer/state.yaml — skip if unchanged
+        │  4. opencode runs the port against .upstreamer/upstreamer.md
+        │  5. .upstreamer/scripts/verify.sh   (mechanical gate)
+        │  6. .upstreamer/eval.md            (parity gate, fresh context)
+        │  7. advance state.yaml — ONLY if both gates pass
         ▼
     Pull request  (never a direct push to main)
 ```
 
-A weekly cron backs up the dispatch in case one is missed, and
-`workflow_dispatch` allows a manual run against any ref.
+### Why HEAD and not the latest release
+
+Release tracking sounds more conservative and is worse in practice. Upstream can
+sit for weeks with large unreleased work on `main` — doom-loop detection (#73) was
+~7,500 lines, ~4,700 of it tests, and rewrote a big part of `model-result.ts`. A
+release-tracking port stays blind to that, then absorbs the entire delta in one
+automated run touching the most load-bearing module in the package. Tracking HEAD
+keeps each delta small enough that a human can actually review it.
+
+Two consequences follow, and both are handled rather than ignored:
+
+**The port is routinely ahead of the latest release.** So a release ref is now
+*dangerous*: it resolves to an ancestor of what is already ported, and the
+converter would faithfully "port" the older tree, reverting landed work.
+`scripts/upstream` refuses a target that is behind `state.yaml` (exit 3) unless
+`--force` is given, and the workflow ignores the publish dispatch's
+`client_payload.ref` for the same reason.
+
+**Its declared version legitimately lags upstream's `package.json`.** Being ahead
+of a release means carrying commits upstream has not versioned yet, while
+`package.json` still shows the last released number. The verifier reports how many
+commits ahead the ported tree is and warns not to publish that version to PyPI —
+shipping unreleased upstream work under a released version number is a
+misrepresentation, and a PyPI version can never be reused. Publish from a commit
+level with a release tag.
+
+The weekly cron is the primary trigger. The publish dispatch still fires on a new
+npm release — useful as "something shipped, sync promptly" — but it syncs to HEAD
+like everything else. `workflow_dispatch` allows a manual run against any ref.
 
 ## The contract is the product
 

pyproject.toml

@@ -77,6 +77,12 @@ include = [
 [tool.ruff]
 line-length = 120
 target-version = "py310"
+# tmp/ is the port pipeline's scratch space (upstream checkout, probe scripts a
+# sync run writes while exploring). It is gitignored, but ruff still walks it, so
+# a stray scratch file there fails the verifier on grounds unrelated to the port.
+# Ruff honors .gitignore for untracked files but not for an explicitly-walked
+# directory, so exclude it outright.
+extend-exclude = ["tmp"]
 
 [tool.ruff.lint]
 select = ["E", "F", "I", "UP", "B"]

scripts/upstream

@@ -149,6 +149,35 @@ echo "target:    $target_commit${ref:+ ($ref)}" >&2
 echo "last port: ${last_upstream_commit:-none}" >&2
 echo "model:     ${model:-<opencode default>}" >&2
 
+# Refuse to port backwards.
+#
+# The port tracks upstream's default branch, so it is routinely AHEAD of the
+# latest published release. That makes a release ref actively dangerous: a
+# publish dispatch (or a manual --ref v0.8.0) resolves to a commit that is an
+# ancestor of what we already ported, and the converter would dutifully "port"
+# the older tree — silently reverting everything landed since.
+#
+# Ancestor of last-ported, and not equal to it, means strictly behind. Unrelated
+# histories (no merge-base) are not caught here; they surface as a normal diff
+# for review rather than a silent revert.
+if [ "$force" -eq 0 ] && [ -n "$last_upstream_commit" ] && [ "$target_commit" != "$last_upstream_commit" ] \
+   && git -C "$upstream_dir" merge-base --is-ancestor "$target_commit" "$last_upstream_commit" 2>/dev/null; then
+  behind_by="$(git -C "$upstream_dir" rev-list --count "$target_commit..$last_upstream_commit" 2>/dev/null || echo "?")"
+  cat >&2 <<MSG
+ERROR: refusing to port backwards.
+
+  target:      $target_commit${ref:+ ($ref)}
+  last ported: $last_upstream_commit
+  target is $behind_by commit(s) BEHIND what is already ported.
+
+This repo tracks upstream's default branch, so it is normally ahead of the latest
+release tag. Porting an older ref would revert work already landed and eval-passed.
+
+If you genuinely intend to move the port back to this ref, re-run with --force.
+MSG
+  exit 3
+fi
+
 if [ "$force" -eq 0 ] && [ "$target_commit" = "$last_upstream_commit" ]; then
   {
     echo "Run summary"