ci: cancel superseded runs on main, not just on PRs

.github/workflows/ci.yml

@@ -21,13 +21,15 @@ on:
 permissions:
   contents: read
 
-# PR pushes cancel the superseded run of the same PR (only the latest commit
-# matters). Pushes to main, merge-queue entries, and manual dispatches get
-# SHA-keyed groups with no cancellation, so a new main push can never kill an
-# in-flight main or queue run. Same pattern as package-preview.yml.
+# Only the latest commit of a ref matters: a PR push cancels the superseded
+# run of the same PR, and a main push cancels the superseded main run, so a
+# burst of merges leaves one run for the tip instead of a queue. Merge-queue
+# entries and dispatches key on their own ref. Same pattern as
+# package-preview.yml; docs.yml and release.yml never cancel a main run
+# because a deploy or publish must not die mid-flight.
 concurrency:
-  group: ci-${{ github.event.pull_request.number || github.sha }}
-  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+  group: ci-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
 
 env:
   # Workbench browser suites launch Playwright's bundled Chromium — pinned by

.github/workflows/docs.yml

@@ -28,15 +28,15 @@ on:
 permissions:
   contents: read
 
-# PR pushes cancel the superseded run of the same PR. Every run that can
-# deploy (push or manual dispatch on main) shares one non-cancelling group so
-# build-and-deploy runs execute in order and an older, slower build can never
-# deploy over a newer one (GitHub keeps at most one pending run per group, so
-# a superseded pending build is dropped, never reordered). Dispatches on other
-# refs and merge-queue entries (ref gh-readonly-queue/main/...) get SHA-keyed
-# groups.
+# PR pushes cancel the superseded run of the same PR. Runs on main (push or
+# dispatch, both refs/heads/main) share one non-cancelling group because the
+# deploy job must never be killed mid-deployment: GitHub keeps at most one
+# pending run per group, so a burst of merges leaves the in-flight run plus
+# the newest pending one and drops the rest. Merge-queue entries (ref
+# gh-readonly-queue/main/...) and dispatches on other refs key on their own
+# ref.
 concurrency:
-  group: docs-${{ github.ref == 'refs/heads/main' && github.event_name != 'pull_request' && 'main' || github.event.pull_request.number || github.sha }}
+  group: docs-${{ github.event.pull_request.number || github.ref }}
   cancel-in-progress: ${{ github.event_name == 'pull_request' }}
 
 jobs:

.github/workflows/package-preview.yml

@@ -7,11 +7,12 @@ on:
 
 permissions: {}
 
-# PR builds cancel superseded runs (only the latest preview matters), but each
-# push to main gets a SHA-keyed group so overlapping pushes never cancel a
-# main preview publish — every main commit must stay installable by SHA.
+# Only the latest preview of a ref matters: a PR push cancels the superseded
+# PR run and a main push cancels the superseded main run. A main commit that
+# was overtaken before its preview published is not installable by SHA; the
+# tip always is.
 concurrency:
-  group: package-preview-${{ github.event.pull_request.number || github.sha }}
+  group: package-preview-${{ github.event.pull_request.number || github.ref }}
   cancel-in-progress: true
 
 jobs:

AGENTS.md

@@ -204,6 +204,10 @@
   paste the commands and their results in the PR body. Do not wait for CI on
   the PR. CI still runs on `main` after the merge: whoever merged watches
   that run and fixes or reverts a red `main` before starting anything else.
+  A later push to `main` cancels the superseded `CI` and `Package preview`
+  run (`concurrency` in `ci.yml`, `package-preview.yml`), so watch the tip
+  commit's run; `docs.yml` and `release.yml` never cancel a `main` run,
+  since a deploy or publish must not die mid-flight.
   `gh pr update-branch` only when GitHub reports the branch as conflicting;
   never `--admin`, never force-push `main`.
 

docs/preview-packages.md

@@ -51,7 +51,7 @@ time of its merge, which is the state that landed on `main`.
 
 ## Pin an exact commit
 
-Any commit that had a package-preview run can be installed by SHA (short SHAs
+Any commit whose package-preview run completed can be installed by SHA (short SHAs
 work), which is the right form for lockfiles and reproducible setups:
 
 ```sh
@@ -107,11 +107,11 @@ installable artifacts.
 `pnpm preview:publish` (`pkg-pr-new publish --previewVersion --peerDeps
 --no-compact --no-template './packages/agent-bundle' './packages/rsc-runtime'
 './packages/rsc-markdown-stream' './packages/create-agent-bundle'`)
-after a full build, on every pull request and on every push to `main`. Runs for
-`main` pushes use a per-commit concurrency group, so overlapping pushes
-cannot cancel one another and every `main` commit has an installable
-snapshot. (PR runs cancel superseded builds for the same PR — only the
-latest preview of a PR matters.) The "Publish pkg.pr.new preview"
+after a full build, on every pull request and on every push to `main`. Runs are
+grouped per PR and per branch with `cancel-in-progress`, so a newer push
+cancels the superseded build: only the latest preview of a PR or of `main`
+matters, and a `main` commit overtaken before its preview published has no
+installable snapshot (pin the tip instead). The "Publish pkg.pr.new preview"
 check on a PR or commit links to the exact URLs for that build. Previews are
 built from the same `pnpm build` output the release gates verify; they are
 not npm releases and carry preview version strings.

website/docs/en/guide/distribution/preview-packages.mdx

@@ -22,9 +22,9 @@ pull request and on every push to `main`. It publishes `packages/agent-bundle`,
 `@agent-bundle/runtime` depends on), and `packages/create-agent-bundle` with
 `--previewVersion --peerDeps --no-compact --no-template`.
 
-Runs for `main` pushes use a **per-commit** concurrency group, so overlapping pushes cannot
-cancel one another and every `main` commit has an installable snapshot. PR runs do cancel
-superseded builds for the same PR, because only the latest preview of a PR matters.
+Runs are grouped per PR and per branch with `cancel-in-progress`, so a newer push cancels the
+superseded build: only the latest preview of a PR or of `main` matters. A `main` commit that was
+overtaken before its preview published has no installable snapshot; pin the tip instead.
 
 The "Publish pkg.pr.new preview" check on a PR or commit links to the exact URLs for that build.
 Previews are built from the same `pnpm build` output the release gates verify — but they are not

website/docs/en/guide/start/installation.mdx

@@ -17,15 +17,15 @@ in the artifact manifest.
 
 Nothing is published to npm yet. This is deliberate: the current package names are
 placeholders, and the `agent-bundle` name on npm currently belongs to an unrelated project.
-Until the first release, install the preview tarballs CI publishes for every commit and pull
-request:
+Until the first release, install the preview tarballs CI publishes for every pull request and
+for the tip of `main`:
 
 ```sh
 npm i -D https://pkg.pr.new/ScriptedAlchemy/agent-bundle/agent-bundle@<sha-or-pr>
 ```
 
-Use a PR number or the SHA of a commit whose package-preview run succeeded — every green `main`
-commit has one. Short SHAs work, and a SHA is the right form for lockfiles and reproducible
+Use a PR number or the SHA of a commit whose package-preview run succeeded — a `main` commit
+overtaken before its run finished has none. Short SHAs work, and a SHA is the right form for lockfiles and reproducible
 setups; a PR number tracks that pull request's most recent build.
 
 ### Pair the runtime package from the same commit

website/docs/zh/guide/distribution/preview-packages.mdx

@@ -18,8 +18,9 @@ pull request 与每次推送到 `main`。它以 `--previewVersion --peerDeps --n
 发布 `packages/agent-bundle`、`packages/rsc-runtime`、`packages/rsc-markdown-stream`（`@agent-bundle/runtime`
 所依赖的 Markdown 渲染器）与 `packages/create-agent-bundle`。
 
-针对 `main` 推送的运行使用**逐提交**的并发分组，因此相互重叠的推送不会取消彼此，每个 `main` 提交都有
-一份可安装的快照。PR 的运行则会取消同一个 PR 中被取代的构建，因为只有 PR 的最新一次预览才有意义。
+运行按 PR 和按分支分组并启用 `cancel-in-progress`，因此更新的推送会取消被取代的构建：只有 PR 或 `main`
+的最新一次预览才有意义。若某个 `main` 提交在其预览发布之前就被后续提交取代，则它没有可安装的快照；
+请改为固定到最新提交。
 
 PR 或提交上的「Publish pkg.pr.new preview」检查会链接到该次构建的确切 URL。预览包由发布门禁所校验的
 同一份 `pnpm build` 输出构建而来——但它们不是 npm 正式版本，并且携带预览版本号。

website/docs/zh/guide/start/installation.mdx

@@ -15,13 +15,13 @@ description: '从 pkg.pr.new 预览通道安装 agent-bundle，以及首个 npm
 ## 从预览通道安装
 
 目前尚未向 npm 发布任何内容。这是刻意为之：现有的包名只是占位符，而 npm 上的 `agent-bundle` 这个名字
-当前属于一个无关项目。在首个正式版本发布之前，请安装 CI 为每个提交和每个 pull request 发布的预览包：
+当前属于一个无关项目。在首个正式版本发布之前，请安装 CI 为每个 pull request 以及 `main` 最新提交发布的预览包：
 
 ```sh
 npm i -D https://pkg.pr.new/ScriptedAlchemy/agent-bundle/agent-bundle@<sha-or-pr>
 ```
 
-使用 PR 编号，或使用某个 package-preview 运行成功的提交 SHA —— 每个绿色的 `main` 提交都有一个。
+使用 PR 编号，或使用某个 package-preview 运行成功的提交 SHA —— 在其运行完成前就被取代的 `main` 提交没有预览。
 短 SHA 同样可用；对于 lockfile 与可复现的环境，SHA 是正确的形式，而 PR 编号则会跟踪该 pull request
 的最新一次构建。