zx-bulk-release 3.0.4 → 3.1.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [3.1.0](https://github.com/semrel-extra/zx-bulk-release/compare/v3.0.5...v3.1.0) (2026-04-12)
+
+### Features
+* feat: coordinated delivery with supply chain security ([772be14](https://github.com/semrel-extra/zx-bulk-release/commit/772be14525e751cf9ca805380d63330c446cd965))
+
+### Fixes & improvements
+* fix: make git-tag a courier channel, remove pushTag from publish ([a34ceb9](https://github.com/semrel-extra/zx-bulk-release/commit/a34ceb9d6ca40b8e8f57d29c80f6f4f055927711))
+* fix: improve logging ([09461c7](https://github.com/semrel-extra/zx-bulk-release/commit/09461c70ee35843fdc106db9a151869657467951))
+
+## [3.0.5](https://github.com/semrel-extra/zx-bulk-release/compare/v3.0.4...v3.0.5) (2026-04-11)
+
+### Fixes & improvements
+* perf: minor code imprs ([2564f3f](https://github.com/semrel-extra/zx-bulk-release/commit/2564f3fd8fdd42c08a2aa32e1e9f2cfee7d3199d))
+
 ## [3.0.4](https://github.com/semrel-extra/zx-bulk-release/compare/v3.0.3...v3.0.4) (2026-04-11)
 
 ### Fixes & improvements

package/README.md

@@ -14,17 +14,17 @@
 * Pkg changelogs go to `changelog` branch (configurable).
 * Docs are published to `gh-pages` branch (configurable).
 * No extra builds. The required deps are fetched from the pkg registry (`npmFetch` config opt).
-* **Two-phase pipeline**: build and delivery can run as separate jobs with isolated credentials.
-
+* **Flexible pipeline**: run all phases in one command, split into two (pack/deliver), or use all four (receive/pack/verify/deliver) for maximum supply chain security.
+* **Coordinated delivery**: multiple release agents can safely serve the same monorepo concurrently via git-tag-based semaphores.
 
 > [!NOTE]
-> **[Migration guide v2 → v3](./MIGRATION_V2_V3.md)**
+> **[Migration guide v2 → v3](./MIGRATION_V2_V3.md)** | **[Delivery specification](./DELIVER_SPEC.md)** | **[Security model](./SECURITY.md)**
 
 ## Roadmap
 * [x] Store release metrics to `meta`.
 * [x] Two-phase pipeline (pack / deliver).
+* [x] Semaphore. Let several release agents serve the monorepo at the same time.
 * [ ] Multistack. Add support for java/kt/py.
-* [ ] Semaphore. Let several release agents to serve the monorepo at the same time.
 
 ## Requirements
 * macOS / linux
@@ -44,7 +44,10 @@ GH_TOKEN=ghtoken GH_USER=username NPM_TOKEN=npmtoken npx zx-bulk-release [opts]
 ```
 | Flag                         | Description                                                                                       | Default          |
 |------------------------------|---------------------------------------------------------------------------------------------------|------------------|
+| `--receive`                  | Consume rebuild signal, analyze, preflight. Writes `.zbr-context.json`. Run before deps install.  |                  |
 | `--pack [dir]`               | Pack only: build, test, and write delivery tars to `dir`. No credentials needed.                  | `parcels`        |
+| `--verify [dir]`             | Verify untrusted parcels against context, copy valid ones to `parcels/`. Use `--context` for path. | `parcels`       |
+| `--context <path>`           | Path to trusted `.zbr-context.json` (used with `--verify`).                                       | `.zbr-context.json` |
 | `--deliver [dir]`            | Deliver only: read tars from `dir` and run delivery channels. No source code needed.              | `parcels`        |
 | `--ignore`                   | Packages to ignore: `a, b`                                                                        |                  |
 | `--include-private`          | Include `private` packages                                                                        | `false`          |
@@ -59,8 +62,29 @@ GH_TOKEN=ghtoken GH_USER=username NPM_TOKEN=npmtoken npx zx-bulk-release [opts]
 | `--debug`                    | Enable [zx](https://github.com/google/zx#verbose) verbose mode                                    |                  |
 | `--version` / `-v`           | Print own version                                                                                 |                  |
 
-### Two-phase pipeline
-By default, zbr runs the full pipeline in a single process. For better security isolation, split build and delivery into separate CI jobs:
+### Pipeline modes
+
+zbr supports three deployment schemes — pick the one that matches your security requirements.
+
+#### All-in-one
+A single command runs all phases in one process. Simple but requires all credentials at build time.
+
+```yaml
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
+      - run: yarn install
+      - run: npx zx-bulk-release
+        env:
+          GH_TOKEN: ${{ secrets.GH_TOKEN }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+```
+
+#### Two phases: pack + deliver
+Build and delivery run as separate jobs. The pack phase needs no credentials — tars contain `${{ENV_VAR}}` templates resolved at delivery time.
 
 ```yaml
 jobs:
@@ -69,11 +93,12 @@ jobs:
     steps:
       - uses: actions/checkout@v4
         with: { fetch-depth: 0 }
+      - run: yarn install
       - run: npx zx-bulk-release --pack
       - uses: actions/upload-artifact@v4
         with:
-          name: parcels
-          path: parcels
+          name: parcels-${{ github.run_id }}
+          path: parcels/
           retention-days: 1
           if-no-files-found: ignore
 
@@ -83,19 +108,91 @@ jobs:
     steps:
       - uses: actions/download-artifact@v4
         id: download
-        with: { name: parcels, path: parcels }
+        with:
+          name: parcels-${{ github.run_id }}
+          path: parcels/
         continue-on-error: true
       - if: steps.download.outcome == 'success'
         run: npx zx-bulk-release --deliver
         env:
           GH_TOKEN: ${{ secrets.GH_TOKEN }}
           NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
-      - if: steps.download.outcome == 'success'
+          GIT_COMMITTER_NAME: Semrel Extra Bot
+          GIT_COMMITTER_EMAIL: semrel-extra-bot@hotmail.com
+```
+
+#### Four phases: receive + pack + verify + deliver
+Maximum supply chain security. Each phase has strict trust boundaries. See [SECURITY.md](./SECURITY.md) for the threat model.
+
+- **receive** — runs *before* `yarn install`, consumes rebuild signals, analyzes, writes trusted context
+- **pack** — runs *after* deps install with zero credentials, builds and packs tars
+- **verify** — validates untrusted parcels against the trusted context
+- **deliver** — delivers only verified parcels
+
+```yaml
+on:
+  push:
+    branches: [master]
+    tags: ['zbr-rebuild.*']
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
+
+      # receive — runs BEFORE deps install, safe to use GH_TOKEN
+      - run: npx zx-bulk-release --receive
+        id: receive
+        env:
+          GH_TOKEN: ${{ secrets.GH_TOKEN }}
+
+      # Trust anchor: context uploaded before any third-party code
+      - uses: actions/upload-artifact@v4
+        with:
+          name: context-${{ github.run_id }}
+          path: .zbr-context.json
+
+      # pack — deps installed, hostile code may run, zero credentials
+      - if: steps.receive.outputs.status == 'proceed'
+        run: |
+          yarn install
+          npx zx-bulk-release --pack
+
+      - if: steps.receive.outputs.status == 'proceed'
         uses: actions/upload-artifact@v4
-        with: { name: parcels, path: parcels, overwrite: true, retention-days: 1 }
+        with:
+          name: parcels-${{ github.run_id }}
+          path: parcels/
+
+  deliver:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      # Download trusted context and untrusted parcels separately
+      - uses: actions/download-artifact@v4
+        with:
+          name: context-${{ github.run_id }}
+          path: .
+      - uses: actions/download-artifact@v4
+        with:
+          name: parcels-${{ github.run_id }}
+          path: parcels-unverified/
+
+      # verify — validate untrusted parcels against trusted context
+      - run: npx zx-bulk-release --verify parcels-unverified/
+
+      # deliver — only verified parcels
+      - run: npx zx-bulk-release --deliver
+        env:
+          GH_TOKEN: ${{ secrets.GH_TOKEN }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+          GIT_COMMITTER_NAME: Semrel Extra Bot
+          GIT_COMMITTER_EMAIL: semrel-extra-bot@hotmail.com
 ```
 
-After delivery, each tar is replaced with a marker (`released` or `skip`). The final `upload-artifact` syncs these markers back to CI storage, so a re-run of the deliver job will skip already-delivered parcels. Artifacts expire naturally via retention policy.
+After delivery, each tar is replaced with a marker (`released`, `skip`, `conflict`, or `orphan`). In the four-phase mode, parcels are verified against the trusted context (uploaded before deps install) before any delivery begins.
 
 **Recovery** is simply re-running the deliver job. Only undelivered tars (not yet replaced with markers) will be processed. No rebuild required.
 
@@ -254,6 +351,7 @@ The release pipeline is split into three subsystems under `post/`:
 
 ```
 post/
+  modes/     — pipeline entry points: receive, pack, verify, deliver
   depot/     — preparation: analysis, versioning, building, testing, tar packing
   courier/   — sealed delivery: receives self-describing tars and delivers through channels
   api/       — shared infrastructure wrappers (git, npm, gh)
@@ -263,21 +361,28 @@ This separation ensures that courier never touches the project directory — it
 
 ### Flow
 ```
-topo ─► contextify ─► analyze ──► build ──► test ──► pack ──► publish ─► clean
-         (per pkg)    (per pkg)   (per pkg)  (per pkg) (per pkg) (per pkg)
+receive:  topo -> contextify -> analyze -> preflight -> context.json
+pack:     build -> test -> pack -> directive
+verify:   validate parcels against context -> copy to output
+deliver:  deliver parcels
+
+all-in-one: topo -> contextify -> analyze -> preflight -> build -> test -> pack -> publish -> clean
 ```
 [`@semrel-extra/topo`](https://github.com/semrel-extra/topo) resolves the release queue respecting dependency graphs. The graph allows parallel execution where the dependency tree permits; `memoizeBy` prevents duplicate work when a package is reached by multiple paths.
 
 By default, packages marked as `private` are omitted. Override with `--include-private`.
 
+**Preflight** runs between `analyze` and `build`. It checks tag availability on git remote and eliminates version conflicts before wasting build/test time. If a tag is already taken by a newer commit, preflight re-resolves the version. If taken by the same or an older commit, the package is skipped.
+
 ### Steps
 Each step has a uniform signature `(pkg, ctx)`:
 - **`contextify`** — resolves per-package config, latest release metadata, and git context.
 - **`analyze`** — determines semantic changes, release type, and next version.
+- **`preflight`** — checks tag availability on remote, re-resolves version on conflict, skips duplicates.
 - **`build`** — runs `buildCmd` (with dep traversal and optional npm artifact fetch).
 - **`test`** — runs `testCmd`.
-- **`pack`** — stages delivery artifacts into self-describing tar containers (`npm pack`, docs copy, assets, release notes). Each tar is named `{tag}.{channel}.{hash8}.tar` and contains a `manifest.json` with channel name, delivery instructions, and template credentials (`${{ENV_VAR}}`). After this step, everything the courier needs is outside the project dir.
-- **`publish`** — pushes the release tag (commitment point), hands tars to courier's `deliver()`, runs `cmd` channel separately.
+- **`pack`** — stages delivery artifacts into self-describing tar containers (`npm pack`, docs copy, assets, release notes). Each tar is named `parcel.{sha7}.{channel}.{tag}.{hash6}.tar` and contains a `manifest.json` with channel name, delivery instructions, and template credentials (`${{ENV_VAR}}`). A directive meta-parcel is also generated, listing all parcels and their delivery steps. After this step, everything the courier needs is outside the project dir.
+- **`publish`** — hands tars to courier's `deliver()`, runs `cmd` channel separately. Tag push is handled by the `git-tag` channel.
 - **`clean`** — restores `package.json` files and unsets git user config.
 
 Set `config.releaseRules` to override the default rules preset:
@@ -292,25 +397,42 @@ Set `config.releaseRules` to override the default rules preset:
 ### Tar containers
 Each delivery artifact is a self-describing tar archive:
 ```
-{tag}.{channel}.{hash8}.tar
+parcel.{sha7}.{channel}.{tag}.{hash6}.tar
   manifest.json    — channel name, delivery params, template credentials
   package.tgz     — (npm channel) npm tarball
   assets/          — (gh-release channel) release assets
   docs/            — (gh-pages channel) documentation files
 ```
+The `sha7` prefix groups all parcels of one commit. The `hash6` suffix is a content hash for deduplication — two builds of the same commit producing identical content yield the same filename (last-writer-wins), while different content gets a different hash.
+
+A **directive** meta-parcel (`parcel.{sha7}.directive.{ts}.tar`) is generated alongside regular parcels. It contains the complete delivery map: package queue, per-package channel steps, and an authoritative list of parcel filenames. The directive enables coordinated delivery — see [DELIVER_SPEC.md](./DELIVER_SPEC.md).
 
 The manifest contains `${{ENV_VAR}}` placeholders that are resolved by the courier at delivery time via `resolveManifest()`. This ensures credentials never touch the build phase.
 
 ### Channels
 Delivery channels are a registry of `{name, when, prepare?, run, requires?, snapshot?, transport?}` objects:
-- **meta** — pushes release metadata to the `meta` branch (or as a GH release asset).
-- **npm** — publishes to the npm registry.
-- **gh-release** — creates a GitHub release with optional file assets.
-- **gh-pages** — pushes docs to a `gh-pages` branch.
-- **changelog** — pushes a changelog entry to a `changelog` branch.
+- **git-tag** — pushes the release tag to git remote. Runs before other channels. Returns `conflict` if the tag already exists. Skipped in snapshot mode.
+- **meta** — pushes release metadata to the `meta` branch (or as a GH release asset). Checks docs seniority before committing.
+- **npm** — publishes to the npm registry. Returns `duplicate` on `EPUBLISHCONFLICT` / 403.
+- **gh-release** — creates a GitHub release with optional file assets (requires tag to exist). Returns `duplicate` on 422.
+- **gh-pages** — pushes docs to a `gh-pages` branch. Checks docs seniority before committing.
+- **changelog** — pushes a changelog entry to a `changelog` branch. Checks docs seniority before committing.
 - **cmd** — runs a custom `publishCmd` (depot-side, not through courier; `transport: false`).
 
-Each channel declares `requires` — a list of manifest fields that must be present after credential resolution. Courier validates all parcels before running any channel (fail-fast).
+Each channel declares `requires` — a list of manifest fields that must be present after credential resolution. Courier validates before delivery; missing credentials produce a warning and `skip` marker.
+
+Channels return one of: `ok` (success), `duplicate` (already published, goal achieved), or `conflict` (version collision, needs rebuild). Unrecoverable errors are thrown.
+
+### Coordinated delivery
+When multiple zbr processes target the same monorepo concurrently, delivery is coordinated via git-tag-based semaphores:
+
+1. **Directive** — each build produces a meta-parcel listing all packages and their delivery steps.
+2. **Semaphore lock** — before delivering, a process pushes `zbr-deliver.{sha7}` as an annotated tag. Atomic push = ownership. Failure = another process is working.
+3. **Orphan cleanup** — the directive invalidates parcels not in its authoritative list (stale artifacts from previous builds).
+4. **Conflict resolution** — if `git-tag` returns `conflict`, all parcels of that package are marked, and a `zbr-rebuild.{sha7}` tag signals CI to rebuild with fresh versions.
+5. **Partial delivery** — skipped parcels (missing credentials) remain valid tarballs. Another process with the right credentials can pick them up later.
+
+See [DELIVER_SPEC.md](./DELIVER_SPEC.md) for the full protocol specification.
 
 ### Credential flow
 ```
@@ -318,7 +440,7 @@ depot (build phase)                          courier (deliver phase)
   manifest: { token: '${{NPM_TOKEN}}' }  →    resolveManifest(manifest, env)
                                                  → { token: 'actual-secret' }
 ```
-Template credentials (`${{ENV_VAR}}`) are written into manifests at pack time. Courier resolves them from `process.env` at delivery time. This means the build phase never sees real secrets.
+Template credentials (`${{ENV_VAR}}`) are written into manifests at pack time. Courier resolves them from `process.env` at delivery time. This means the build phase never sees real secrets — including git push credentials (`GH_TOKEN`, `GIT_COMMITTER_NAME`, `GIT_COMMITTER_EMAIL`) which are now resolved by the `git-tag` channel at delivery time.
 
 ### Tags
 [Lerna](https://github.com/lerna/lerna) tags (like `@pkg/name@v1.0.0-beta.0`) are suitable for monorepos, but they don't follow [semver spec](https://semver.org/). Therefore, we propose another contract:

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "zx-bulk-release",
   "alias": "bulk-release",
-  "version": "3.0.4",
+  "version": "3.1.0",
   "description": "zx-based alternative for multi-semantic-release",
   "type": "module",
   "exports": {

package/src/main/js/config.js

@@ -1,6 +1,7 @@
 import { cosmiconfig } from 'cosmiconfig'
 import { asArray, camelize, memoizeBy } from './util.js'
 import { GH_URL, resolveGhApiUrl } from './post/api/gh.js'
+import { DEFAULT_GIT_COMMITTER_NAME, DEFAULT_GIT_COMMITTER_EMAIL } from './post/api/git.js'
 
 const CONFIG_NAME = 'release'
 const CONFIG_FILES = [
@@ -72,8 +73,8 @@ export const parseEnv = ({GH_USER, GH_USERNAME, GH_META, GH_URL: _GH_URL, GITHUB
     npmProvenance:      NPM_PROVENANCE,
     npmOidc:            NPM_OIDC || (!NPM_TOKEN && ACTIONS_ID_TOKEN_REQUEST_URL),
     npmRegistry:        NPM_REGISTRY || 'https://registry.npmjs.org',
-    gitCommitterName:   GIT_COMMITTER_NAME || 'Semrel Extra Bot',
-    gitCommitterEmail:  GIT_COMMITTER_EMAIL || 'semrel-extra-bot@hotmail.com',
+    gitCommitterName:   GIT_COMMITTER_NAME || DEFAULT_GIT_COMMITTER_NAME,
+    gitCommitterEmail:  GIT_COMMITTER_EMAIL || DEFAULT_GIT_COMMITTER_EMAIL,
   }
 }
 

package/src/main/js/post/api/gh.js

@@ -1,5 +1,6 @@
 // Low-level GitHub API primitives. No domain knowledge, no imports from processor/ or steps/.
 
+import nodeFs from 'node:fs'
 import {$, path, tempy, glob, fs, fetch} from 'zx-extra'
 import {asArray, attempt2} from '../../util.js'
 
@@ -88,3 +89,13 @@ export const ghGetAsset = async ({repoName, tag, name, ghUrl}) => {
   }
   return res.text()
 }
+
+export const setOutput = (name, value) => {
+  const outputFile = process.env.GITHUB_OUTPUT
+  if (outputFile) {
+    try { nodeFs.appendFileSync(outputFile, `${name}=${value}\n`) } catch { /* not in CI */ }
+  }
+}
+
+export const isRebuildTrigger = (env) =>
+  !!(env.GITHUB_REF_TYPE === 'tag' && env.GITHUB_REF_NAME?.startsWith('zbr-rebuild.'))

package/src/main/js/post/api/git.js

@@ -1,3 +1,6 @@
+export const DEFAULT_GIT_COMMITTER_NAME  = 'Semrel Extra Bot'
+export const DEFAULT_GIT_COMMITTER_EMAIL = 'semrel-extra-bot@hotmail.com'
+
 import {$, fs, path, tempy, copy} from 'zx-extra'
 import {log} from '../log.js'
 import {attempt2, attempt3, memoizeBy} from '../../util.js'
@@ -51,6 +54,8 @@ export const getRoot = memoizeBy(async (cwd) => (await $({cwd})`git rev-parse --
 
 export const getSha = memoizeBy(async (cwd) => (await $({cwd})`git rev-parse HEAD`).toString().trim(), getRoot)
 
+export const getCommitTimestamp = memoizeBy(async (cwd) => (await $({cwd})`git log -1 --format=%ct`).toString().trim(), getRoot)
+
 export const parseOrigin = (originUrl) => {
   const [, , repoHost, repoName] = originUrl.replace(':', '/').replace(/\.git/, '').match(/.+(@|\/\/)([^/]+)\/(.+)$/) || []
 
@@ -117,3 +122,17 @@ export const setUserConfig = memoizeBy(async(cwd, gitCommitterName, gitCommitter
 export const unsetUserConfig = async(cwd) => $({cwd, nothrow: true})`
   git config --unset user.name &&
   git config --unset user.email`
+
+export const getRemoteTagSha = async (cwd, tag) =>
+  (await $({cwd, nothrow: true})`git ls-remote --tags origin refs/tags/${tag}`)
+    .toString().split('\t')[0]?.trim() || null
+
+export const deleteRemoteTag = async (cwd, tag) =>
+  $({cwd, nothrow: true})`git push origin :refs/tags/${tag}`
+
+export const pushAnnotatedTag = async (cwd, tag, message) => {
+  await $({cwd})`git tag -a ${tag} -m ${message}`
+  await $({cwd})`git push origin ${tag}`
+}
+
+export const clearTagsCache = () => { $.memo?.delete?.(getTags) }

package/src/main/js/post/courier/channels/changelog.js

@@ -2,9 +2,15 @@ import {$} from 'zx-extra'
 import {queuefy} from 'queuefy'
 import {fetchRepo, pushCommit} from '../../api/git.js'
 import {log} from '../../log.js'
+import {hasHigherVersion} from '../seniority.js'
 
 const run = queuefy(async (manifest, dir) => {
-  const {releaseNotes, branch, file, msg, repoAuthedUrl, gitCommitterEmail, gitCommitterName, ghBasicAuth} = manifest
+  const {name, version, releaseNotes, branch, file, msg, repoAuthedUrl, gitCommitterEmail, gitCommitterName, ghBasicAuth} = manifest
+
+  if (await hasHigherVersion(dir, name, version)) {
+    log.warn(`skipping changelog for ${name}@${version}: higher version already released`)
+    return 'ok'
+  }
 
   log.info('push changelog')
 
@@ -19,6 +25,7 @@ const run = queuefy(async (manifest, dir) => {
     gitCommitterName,
     basicAuth: ghBasicAuth,
   })
+  return 'ok'
 })
 
 export default {

package/src/main/js/post/courier/channels/gh-pages.js

@@ -2,11 +2,17 @@ import {path} from 'zx-extra'
 import {queuefy} from 'queuefy'
 import {log} from '../../log.js'
 import {pushCommit} from '../../api/git.js'
+import {hasHigherVersion} from '../seniority.js'
 
 const run = queuefy(async (manifest, dir) => {
-  const {branch, to, msg, repoAuthedUrl, gitCommitterEmail, gitCommitterName, ghBasicAuth} = manifest
+  const {name, version, branch, to, msg, repoAuthedUrl, gitCommitterEmail, gitCommitterName, ghBasicAuth} = manifest
   const docsDir = path.join(dir, 'docs')
 
+  if (await hasHigherVersion(docsDir, name, version)) {
+    log.warn(`skipping gh-pages for ${name}@${version}: higher version already released`)
+    return 'ok'
+  }
+
   log.info(`publish docs to ${branch}`)
 
   await pushCommit({
@@ -20,6 +26,7 @@ const run = queuefy(async (manifest, dir) => {
     gitCommitterName,
     basicAuth: ghBasicAuth,
   })
+  return 'ok'
 })
 
 export default {

package/src/main/js/post/courier/channels/gh-release.js

@@ -2,6 +2,9 @@ import {fs, path} from 'zx-extra'
 import {log} from '../../log.js'
 import {ghCreateRelease, ghFetch} from '../../api/gh.js'
 
+const isDuplicate = (e) =>
+  /already_exists|Validation Failed|422/i.test(e?.message || e?.stderr || '')
+
 const run = async (manifest, dir) => {
   const {tag, token, apiUrl, repoName, releaseNotes, assets} = manifest
   if (!token) return null
@@ -9,7 +12,13 @@ const run = async (manifest, dir) => {
   log.info('create gh release')
   const now = Date.now()
 
-  const res = await ghCreateRelease({ghApiUrl: apiUrl, ghToken: token, repoName, tag, body: releaseNotes})
+  let res
+  try {
+    res = await ghCreateRelease({ghApiUrl: apiUrl, ghToken: token, repoName, tag, body: releaseNotes})
+  } catch (e) {
+    if (isDuplicate(e)) return 'duplicate'
+    throw e
+  }
 
   if (assets?.length) {
     const uploadUrl = res.upload_url.slice(0, res.upload_url.indexOf('{'))
@@ -25,6 +34,7 @@ const run = async (manifest, dir) => {
   }
 
   log.info(`duration gh release: ${Date.now() - now}`)
+  return 'ok'
 }
 
 export default {

package/src/main/js/post/courier/channels/git-tag.js

@@ -0,0 +1,25 @@
+import {pushTag} from '../../api/git.js'
+import {DEFAULT_GIT_COMMITTER_NAME, DEFAULT_GIT_COMMITTER_EMAIL} from '../../api/git.js'
+
+export const isTagConflict = (e) =>
+  /already exists|updates were rejected|failed to push/i.test(e?.message || e?.stderr || '')
+
+const run = async (manifest) => {
+  const {tag, cwd} = manifest
+  const gitCommitterName  = manifest.gitCommitterName  || DEFAULT_GIT_COMMITTER_NAME
+  const gitCommitterEmail = manifest.gitCommitterEmail || DEFAULT_GIT_COMMITTER_EMAIL
+  try {
+    await pushTag({cwd, tag, gitCommitterName, gitCommitterEmail})
+    return 'ok'
+  } catch (e) {
+    if (isTagConflict(e)) return 'conflict'
+    throw e
+  }
+}
+
+export default {
+  name: 'git-tag',
+  requires: ['tag', 'cwd'],
+  when: (pkg) => !pkg.ctx?.flags?.snapshot,
+  run,
+}

package/src/main/js/post/courier/channels/meta.js

@@ -3,10 +3,16 @@ import {log} from '../../log.js'
 import {pushCommit} from '../../api/git.js'
 import {getArtifactPath, isAssetMode} from '../../depot/generators/meta.js'
 import {prepareMeta} from '../../depot/generators/meta.js'
+import {hasHigherVersion} from '../seniority.js'
 
 const pushMetaBranch = queuefy(async (manifest, dir) => {
   const {name, version, tag, type, data: meta, repoAuthedUrl, gitCommitterEmail, gitCommitterName, ghBasicAuth} = manifest
-  if (type === null || isAssetMode(type)) return
+  if (type === null || isAssetMode(type)) return 'ok'
+
+  if (await hasHigherVersion(dir, name, version)) {
+    log.warn(`skipping meta for ${name}@${version}: higher version already released`)
+    return 'ok'
+  }
 
   log.info('push artifact to branch \'meta\'')
 
@@ -23,6 +29,7 @@ const pushMetaBranch = queuefy(async (manifest, dir) => {
     gitCommitterName,
     basicAuth: ghBasicAuth,
   })
+  return 'ok'
 })
 
 export default {

package/src/main/js/post/courier/channels/npm.js

@@ -4,23 +4,36 @@ import {npmPublish} from '../../api/npm.js'
 export const isNpmPublished = (pkg) =>
   !pkg.manifest.private && pkg.config.npmPublish !== false
 
+const isDuplicate = (e) =>
+  /EPUBLISHCONFLICT|cannot publish over|403/i.test(e?.message || e?.stderr || '')
+
+const run = async (manifest, dir) => {
+  try {
+    await npmPublish({
+      name: manifest.name,
+      version: manifest.version,
+      npmTarball: path.join(dir, 'package.tgz'),
+      preversion: manifest.preversion,
+      manifest: {},
+      config: {
+        npmRegistry: manifest.registry,
+        npmToken: manifest.token,
+        npmConfig: manifest.config,
+        npmProvenance: manifest.provenance,
+        npmOidc: manifest.oidc,
+      },
+    })
+    return 'ok'
+  } catch (e) {
+    if (isDuplicate(e)) return 'duplicate'
+    throw e
+  }
+}
+
 export default {
   name:     'npm',
   requires: (manifest) => manifest.oidc ? [] : ['token'],
   when:     isNpmPublished,
-  run:      (manifest, dir) => npmPublish({
-    name: manifest.name,
-    version: manifest.version,
-    npmTarball: path.join(dir, 'package.tgz'),
-    preversion: manifest.preversion,
-    manifest: {},
-    config: {
-      npmRegistry: manifest.registry,
-      npmToken: manifest.token,
-      npmConfig: manifest.config,
-      npmProvenance: manifest.provenance,
-      npmOidc: manifest.oidc,
-    },
-  }),
+  run,
   snapshot: true,
 }

package/src/main/js/post/courier/directive.js

@@ -0,0 +1,81 @@
+import {fs, path, glob} from 'zx-extra'
+import {packTar, unpackTar} from '../tar.js'
+import {log} from '../log.js'
+
+const GIT_CHANNELS = new Set(['git-tag', 'gh-release', 'changelog', 'gh-pages', 'meta'])
+
+// parcel.{sha7}.{channel}.{...}.tar — channel is the 3rd dot-segment
+export const parcelChannel = (name) => name.replace(/\.tar$/, '').split('.')[2]
+
+const splitSteps = (channelNames) => {
+  const git = channelNames.filter(n => GIT_CHANNELS.has(n))
+  const ext = channelNames.filter(n => !GIT_CHANNELS.has(n))
+  return [git, ext].filter(s => s.length)
+}
+
+export const buildDirective = async (ctx, packedPkgs, outputDir) => {
+  const {sha, timestamp} = packedPkgs[0].ctx.git
+  const packages = {}
+  const parcels = []
+
+  for (const pkg of packedPkgs) {
+    const pkgParcels = (pkg.tars || []).map(t => path.basename(t))
+    packages[pkg.name] = {
+      version:  pkg.version,
+      tag:      pkg.tag,
+      deliver:  splitSteps(pkg.activeTransport || []),
+      parcels:  pkgParcels,
+    }
+    parcels.push(...pkgParcels)
+  }
+
+  const sha7 = sha.slice(0, 7)
+  const manifest = {
+    channel: 'directive',
+    sha, timestamp: Number(timestamp),
+    queue: packedPkgs.map(p => p.name),
+    packages, parcels,
+  }
+
+  const tarPath = path.join(outputDir, `parcel.${sha7}.directive.${timestamp}.tar`)
+  await packTar(tarPath, manifest, [])
+  return tarPath
+}
+
+export const parseDirective = async (tarPath) => {
+  const content = await fs.readFile(tarPath, 'utf8').catch(() => null)
+  if (content === 'released' || content === 'conflict') return null
+
+  const {manifest} = await unpackTar(tarPath, tarPath + '.d')
+  if (manifest.channel !== 'directive') return null
+  return manifest
+}
+
+export const scanDirectives = async (dir) => {
+  const tars = await glob(path.join(dir, 'parcel.*.directive.*.tar'))
+  const result = []
+
+  for (const tarPath of tars) {
+    const d = await parseDirective(tarPath)
+    if (d) result.push({...d, tarPath})
+  }
+
+  return result.sort((a, b) => a.timestamp - b.timestamp)
+}
+
+export const invalidateOrphans = async (dir, directive) => {
+  const sha7 = directive.sha.slice(0, 7)
+  const owned = new Set(directive.parcels || [])
+  const all = await glob(path.join(dir, `parcel.${sha7}.*.tar`))
+  let count = 0
+
+  for (const tarPath of all) {
+    const name = path.basename(tarPath)
+    if (parcelChannel(name) === 'directive') continue
+    if (owned.has(name)) continue
+    await fs.writeFile(tarPath, 'orphan')
+    count++
+  }
+
+  if (count) log.info(`invalidated ${count} orphan parcel(s) for ${sha7}`)
+}