Skip to content

Commit ecefeba

Browse files
radroidclaude
andcommitted
feat(coil): move the release identity, offsetting the counter so clients keep updating (#71)
workflow .github/workflows/t3x-release.yml -> coil-release.yml tags t3x-build-<sha> -> coil-build-<sha> version 0.0.33-t3x.N -> 0.0.33-coil.N manifest t3x-latest.json -> coil-latest.json assets T3Code-<sha>-<arch> -> T3Coil-<sha>-<arch> The workflow rename is the dangerous part, and not for any reason the issue predicted. BUILD_COUNTER is github.run_number, and run_number is scoped to a workflow that GitHub identifies by its FILE PATH. Renaming the file starts a new sequence at 1. That number is the manifest's buildNumber, and decision.ts is a bare `manifest.buildNumber <= installed.buildNumber` — so the first renamed release would have offered build 1 to clients sitting at 26, every one of them would have skipped, and they would have gone on skipping forever with no symptom, because "skip" is the ordinary outcome of that branch and looks exactly like being up to date. Hence `github.run_number + 100`, which clears both the last run under the old filename (32) and the last published build (26). The first coil build is 101. The offset is permanent; the comment on it says so, at length, because it reads like something to tidy up. Two consequences of that offset, one of which was a live bug for a while: - build-update-manifest.mjs asserts VERSION ends with `-coil.<RUN_NUMBER>`, and the workflow was passing raw github.run_number to it. With the offset applied to the version but not to RUN_NUMBER, that assertion fails on every release. The resolve job now publishes the counter as a `build_number` output and the manifest step reads that — one number, resolved once. - parseBuildNumber accepts `-coil.N` AND keeps `-t3x.N`. Not sentiment: every published build up to 26 carries the old suffix, and returning undefined for those reads as "no ordering floor", the one answer that lets an older build look installable. Ordering survives the rename because the counter did, not because the suffixes compare — and they do not, `coil` sorts before `t3x`. The changelog's previous-tag lookup now spans both prefixes, permanently. Without that the first coil release finds no tag, takes the "first release ever" branch, and ships an empty changelog for a build with twenty commits in it. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
1 parent 2666bcd commit ecefeba

7 files changed

Lines changed: 113 additions & 53 deletions

File tree

Lines changed: 60 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# t3x fork release — build the desktop app on every green merge to main and publish it.
1+
# coil fork release — build the desktop app on every green merge to main and publish it.
22
#
33
# Upstream's release.yml cannot be reused: it runs on blacksmith-12vcpu-macos-26 and
44
# blacksmith-32vcpu-windows-2025, runners this fork has no access to (the same reason t3x-ci.yml
@@ -9,7 +9,7 @@
99
# public repositories, and this fork is public. The build costs nothing.
1010
#
1111
# Design: docs/superpowers/specs/2026-08-03-update-delivery-design.md
12-
name: t3x fork release
12+
name: coil fork release
1313

1414
# workflow_run, NOT push.
1515
#
@@ -36,7 +36,7 @@ permissions:
3636
# Not cancel-in-progress. A half-cancelled release can leave a tag created and assets missing,
3737
# and two merges landing minutes apart is normal here.
3838
concurrency:
39-
group: t3x-release
39+
group: coil-release
4040
cancel-in-progress: false
4141

4242
env:
@@ -52,6 +52,7 @@ jobs:
5252
sha: ${{ steps.identity.outputs.sha }}
5353
short_sha: ${{ steps.identity.outputs.short_sha }}
5454
version: ${{ steps.identity.outputs.version }}
55+
build_number: ${{ steps.identity.outputs.build_number }}
5556
tag: ${{ steps.identity.outputs.tag }}
5657
changes: ${{ steps.identity.outputs.changes }}
5758
steps:
@@ -77,7 +78,23 @@ jobs:
7778
# workflow_dispatch path it is user-supplied, and `${{ }}` interpolation splices the raw
7879
# value into the shell source before bash ever sees it.
7980
env:
80-
BUILD_COUNTER: ${{ github.run_number }}
81+
# +100 is LOAD-BEARING. Do not "simplify" it away.
82+
#
83+
# `github.run_number` is scoped to a workflow, and GitHub identifies a workflow by its
84+
# FILE PATH. Renaming this file (it used to be the t3x-prefixed one) for #71 therefore
85+
# did not continue the old sequence — it began a new one at 1.
86+
#
87+
# This number is the manifest's `buildNumber`, and `decision.ts` is a pure
88+
# `manifest.buildNumber <= installed.buildNumber` comparison. Published builds were at
89+
# 26 when this file was renamed, so an un-offset counter would have shipped build 1 to
90+
# every installed client, each of which would have evaluated `1 <= 26` and skipped —
91+
# forever, and silently, because "skip" is the ordinary outcome of that branch and looks
92+
# exactly like being up to date.
93+
#
94+
# 100 clears both the old high-water marks: 32 (the last run under the previous filename)
95+
# and 26 (the last published build). The first coil build is 101. Renaming this file
96+
# again would need a fresh offset above whatever is published by then.
97+
BUILD_COUNTER: ${{ github.run_number + 100 }}
8198
run: |
8299
set -euo pipefail
83100
if [[ ! "$BUILD_SHA" =~ ^[0-9a-f]{40}$ ]]; then
@@ -101,9 +118,9 @@ jobs:
101118
# The upstream base does not move between syncs (0.0.31 -> 0.0.31, issue #47), so without
102119
# a fork-owned counter every build here would carry an identical version. An earlier
103120
# draft used the short sha instead: identifiable, but semver compares prerelease
104-
# identifiers, and `-t3x.a3f9c21b` vs `-t3x.b0e77c14` sorts alphabetically by hash, which
105-
# orders nothing. A numeric identifier sorts numerically, so 0.0.31-t3x.43 correctly
106-
# precedes 0.0.31-t3x.44.
121+
# identifiers, and `-coil.a3f9c21b` vs `-coil.b0e77c14` sorts alphabetically by hash, which
122+
# orders nothing. A numeric identifier sorts numerically, so 0.0.31-coil.43 correctly
123+
# precedes 0.0.31-coil.44.
107124
#
108125
# This is the SAME number the manifest carries as buildNumber and the relay orders on.
109126
# One counter, used everywhere, rather than a version scheme that disagrees with the
@@ -114,13 +131,14 @@ jobs:
114131
# "which commit". Keeping those separate is the whole lesson of #47.
115132
#
116133
# --build-version becomes electron-builder's `version` and must be valid semver — a raw
117-
# sha is not. resolveDesktopUpdateChannel only special-cases -nightly.<d>.<d>, so a -t3x.
134+
# sha is not. resolveDesktopUpdateChannel only special-cases -nightly.<d>.<d>, so a -coil.
118135
# prerelease stays on the "latest" channel and the product name is unchanged.
119136
base="$(node -p "require('./apps/desktop/package.json').version")"
120137
echo "sha=$sha" >> "$GITHUB_OUTPUT"
121138
echo "short_sha=$short_sha" >> "$GITHUB_OUTPUT"
122-
echo "version=${base}-t3x.${BUILD_COUNTER}" >> "$GITHUB_OUTPUT"
123-
echo "tag=t3x-build-${short_sha}" >> "$GITHUB_OUTPUT"
139+
echo "build_number=${BUILD_COUNTER}" >> "$GITHUB_OUTPUT"
140+
echo "version=${base}-coil.${BUILD_COUNTER}" >> "$GITHUB_OUTPUT"
141+
echo "tag=coil-build-${short_sha}" >> "$GITHUB_OUTPUT"
124142
125143
# What changed since the last release we actually published.
126144
#
@@ -132,11 +150,17 @@ jobs:
132150
#
133151
# Newest first. Merge commits are dropped: on a squash-merge fork their subjects are
134152
# duplicates of the commit they merged.
135-
previous="$(git tag --list 't3x-build-*' --sort=-creatordate | head -n 1 || true)"
153+
# Both prefixes, permanently. #71 renamed the tag from `t3x-build-*` to `coil-build-*`,
154+
# and a lookup that knew only the new one would have found nothing on the first coil
155+
# release, taken the "first release ever" branch below, and shipped an empty changelog
156+
# for a build that had 20-odd commits in it. The old tags do not expire, so neither does
157+
# this: dropping `t3x-build-*` later would silently re-break the same release note the
158+
# day someone rebuilds an old sha.
159+
previous="$(git tag --list 'coil-build-*' 't3x-build-*' --sort=-creatordate | head -n 1 || true)"
136160
if [[ -z "$previous" ]]; then
137161
# First release ever: there is no range. Emitting the entire history as a "changelog"
138162
# would render a toast with thousands of entries.
139-
echo "No previous t3x-build-* tag; emitting an empty changelog."
163+
echo "No previous coil-build-* or t3x-build-* tag; emitting an empty changelog."
140164
changes=""
141165
else
142166
echo "Changelog range: ${previous}..${sha}"
@@ -155,7 +179,7 @@ jobs:
155179
# (`tag=`, `sha=`) — which this workflow then uses to tag and publish a release.
156180
# 2. Control characters stripped, so nothing can smuggle a newline or an escape sequence
157181
# into a value that later lands in an env var and a toast.
158-
delim="T3X_CHANGES_$(openssl rand -hex 16)"
182+
delim="COIL_CHANGES_$(openssl rand -hex 16)"
159183
changes="$(printf '%s' "$changes" | tr -d '\000-\010\013\014\016-\037')"
160184
{
161185
echo "changes<<${delim}"
@@ -357,7 +381,7 @@ jobs:
357381
expected='vp run --filter @t3tools/desktop --filter t3 build'
358382
actual="$(node -p 'require("./package.json").scripts["build:desktop"] || ""')"
359383
if [[ "$actual" != "$expected" ]]; then
360-
echo "::error::root build:desktop is now '$actual' (expected '$expected'). Re-inline it in t3x-release.yml." >&2
384+
echo "::error::root build:desktop is now '$actual' (expected '$expected'). Re-inline it in coil-release.yml." >&2
361385
exit 1
362386
fi
363387
@@ -517,7 +541,7 @@ jobs:
517541
exit 1
518542
fi
519543
520-
dest="staged/T3Code-${SHORT_SHA}-${ARCH}.${ASSET_EXT}"
544+
dest="staged/T3Coil-${SHORT_SHA}-${ARCH}.${ASSET_EXT}"
521545
mv "$src" "$dest"
522546
523547
if [[ "$RUNNER_OS" == "Windows" ]]; then
@@ -545,7 +569,7 @@ jobs:
545569
- name: Upload staged artifact
546570
uses: actions/upload-artifact@v4
547571
with:
548-
name: t3x-release-${{ matrix.manifest_platform }}
572+
name: coil-release-${{ matrix.manifest_platform }}
549573
path: staged/*
550574
retention-days: 3
551575
if-no-files-found: error
@@ -570,7 +594,7 @@ jobs:
570594
- name: Download built artifacts
571595
uses: actions/download-artifact@v4
572596
with:
573-
pattern: t3x-release-*
597+
pattern: coil-release-*
574598
merge-multiple: true
575599
path: staged
576600

@@ -583,20 +607,25 @@ jobs:
583607
SHORT_SHA: ${{ needs.resolve.outputs.short_sha }}
584608
VERSION: ${{ needs.resolve.outputs.version }}
585609
REPOSITORY: ${{ github.repository }}
586-
RUN_NUMBER: ${{ github.run_number }}
587-
# run_id addresses the run URL; run_number is the build counter. Different numbers —
588-
# passing run_number here yields a link to whichever run happens to own that id.
610+
# The RESOLVED counter, not github.run_number. Since #71 the two differ by the +100
611+
# offset the resolve job applies, and build-update-manifest.mjs asserts that VERSION ends
612+
# with `-coil.<RUN_NUMBER>`. Passing the raw run_number here would fail that assertion on
613+
# every single release — loudly, which is the only reason this was caught rather than
614+
# shipped. One counter, resolved once, read everywhere.
615+
RUN_NUMBER: ${{ needs.resolve.outputs.build_number }}
616+
# run_id addresses the run URL; the build counter is a different number entirely —
617+
# passing the counter here yields a link to whichever run happens to own that id.
589618
RUN_ID: ${{ github.run_id }}
590619
# Read as an env var, never interpolated into shell source: these are commit subjects,
591620
# so the content is chosen by whoever wrote the commit.
592621
CHANGES: ${{ needs.resolve.outputs.changes }}
593-
run: node scripts/coil/build-update-manifest.mjs staged staged/t3x-latest.json
622+
run: node scripts/coil/build-update-manifest.mjs staged staged/coil-latest.json
594623

595624
# The install steps used to live inline in this file, which made the release body the only
596625
# place they existed — and the download page pointed at "the release notes" without linking
597626
# them, so a first-time reader could go from the landing page to an app macOS calls damaged
598627
# having never seen one (issue #72). Both surfaces now render
599-
# scripts/t3x/install-instructions.json.
628+
# scripts/coil/install-instructions.json.
600629
#
601630
# A rendering failure must not cost a release: by the time this step runs, both matrix legs
602631
# have finished and ~22 minutes of macOS and Windows compute is already spent. So a failure
@@ -610,9 +639,9 @@ jobs:
610639
NOTES_PATH: ${{ runner.temp }}/release-notes.md
611640
run: |
612641
set -uo pipefail
613-
if ! node scripts/t3x/render-release-notes.mjs \
642+
if ! node scripts/coil/render-release-notes.mjs \
614643
--sha "$FULL_SHA" --short-sha "$SHORT_SHA" > "$NOTES_PATH"; then
615-
echo "::warning::Could not render the install notes; publishing a minimal body. This is a bug in scripts/t3x/render-release-notes.mjs — the release itself is fine."
644+
echo "::warning::Could not render the install notes; publishing a minimal body. This is a bug in scripts/coil/render-release-notes.mjs — the release itself is fine."
616645
printf 'Automated fork build of `%s`.\n\nInstall instructions: https://coil.curlycloud.dev/download\n' \
617646
"$FULL_SHA" > "$NOTES_PATH"
618647
fi
@@ -630,8 +659,8 @@ jobs:
630659
name: ${{ needs.resolve.outputs.version }}
631660
prerelease: true
632661
files: |
633-
staged/T3Code-*
634-
staged/t3x-latest.json
662+
staged/T3Coil-*
663+
staged/coil-latest.json
635664
fail_on_unmatched_files: true
636665
body_path: ${{ steps.notes.outputs.path }}
637666

@@ -665,7 +694,7 @@ jobs:
665694
# comes along to heal it.
666695
#
667696
# If it still gives up, the build is recoverable without a new commit — this workflow takes a
668-
# `sha` input, so `gh workflow run t3x-release.yml -f sha=<sha>` republishes it.
697+
# `sha` input, so `gh workflow run coil-release.yml -f sha=<sha>` republishes it.
669698
- name: Retry the release if the action gave up
670699
if: ${{ steps.create_release.outcome == 'failure' }}
671700
shell: bash
@@ -704,15 +733,15 @@ jobs:
704733
# release is completed with `upload --clobber` rather than recreated.
705734
if gh release view "$RELEASE_TAG" >/dev/null 2>&1; then
706735
echo "Release $RELEASE_TAG exists; uploading assets."
707-
if gh release upload "$RELEASE_TAG" staged/T3Code-* staged/t3x-latest.json --clobber; then
736+
if gh release upload "$RELEASE_TAG" staged/T3Coil-* staged/coil-latest.json --clobber; then
708737
exit 0
709738
fi
710739
elif gh release create "$RELEASE_TAG" \
711740
--target "$TARGET_SHA" \
712741
--title "$RELEASE_NAME" \
713742
--prerelease \
714743
--notes-file "$NOTES_FILE" \
715-
staged/T3Code-* staged/t3x-latest.json; then
744+
staged/T3Coil-* staged/coil-latest.json; then
716745
exit 0
717746
fi
718747
@@ -726,7 +755,7 @@ jobs:
726755
done
727756
728757
echo "::error::Could not publish $RELEASE_TAG after $attempt attempts over 7.5 minutes." >&2
729-
echo "::error::Republish without a new commit: gh workflow run t3x-release.yml -f sha=$TARGET_SHA" >&2
758+
echo "::error::Republish without a new commit: gh workflow run coil-release.yml -f sha=$TARGET_SHA" >&2
730759
exit 1
731760
732761
- name: Notify the update relay
@@ -742,7 +771,7 @@ jobs:
742771
exit 0
743772
fi
744773
745-
body="$(cat staged/t3x-latest.json)"
774+
body="$(cat staged/coil-latest.json)"
746775
747776
# Build 20 (run 31391175380) died here: the publish had already durably applied — the
748777
# relay served the new manifest on /latest — but the Durable Object round trip threw a

‎apps/desktop/src/coil/updateDelivery/config.test.ts‎

Lines changed: 22 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -53,22 +53,41 @@ describe("relayEndpoints", () => {
5353

5454
describe("parseBuildNumber", () => {
5555
it("reads the counter this fork's release workflow writes", () => {
56+
expect(parseBuildNumber("0.0.33-coil.101")).toBe(101);
57+
});
58+
59+
it("still reads the pre-rename counter", () => {
60+
// #71 renamed the suffix. This case is not nostalgia: every published build up to 26 carries
61+
// `-t3x.<n>`, and dropping it would make those versions parse as `undefined` — "no ordering
62+
// floor" — which is the one answer that lets an OLDER build look installable.
5663
expect(parseBuildNumber("0.0.31-t3x.44")).toBe(44);
5764
});
5865

66+
it("orders across the rename, because the counter never restarted", () => {
67+
// The whole point of the +100 offset in coil-release.yml. Nothing compares the suffixes —
68+
// which is just as well, since "coil" sorts before "t3x".
69+
const before = parseBuildNumber("0.0.33-t3x.26");
70+
const after = parseBuildNumber("0.0.33-coil.101");
71+
expect(before).toBeDefined();
72+
expect(after).toBeDefined();
73+
expect(after!).toBeGreaterThan(before!);
74+
});
75+
5976
it("has no counter for an upstream build", () => {
6077
// Which `decideUpdateAction` reads as "no ordering floor" — so the first fork build installs
6178
// over an upstream one rather than being refused as not-newer.
6279
expect(parseBuildNumber("0.0.31")).toBeUndefined();
6380
});
6481

6582
it("ignores a counter that is not at the end", () => {
83+
expect(parseBuildNumber("0.0.33-coil.101+meta")).toBeUndefined();
6684
expect(parseBuildNumber("0.0.31-t3x.44+meta")).toBeUndefined();
6785
});
6886

6987
it("rejects zero and negatives", () => {
88+
expect(parseBuildNumber("0.0.33-coil.0")).toBeUndefined();
89+
expect(parseBuildNumber("0.0.33-coil.-1")).toBeUndefined();
7090
expect(parseBuildNumber("0.0.31-t3x.0")).toBeUndefined();
71-
expect(parseBuildNumber("0.0.31-t3x.-1")).toBeUndefined();
7291
});
7392
});
7493

@@ -97,11 +116,11 @@ describe("parsePendingInstall", () => {
97116
it("reads back what recordPendingInstall wrote", () => {
98117
const encoded = encodePendingInstall({
99118
shortSha: "dd90bbace7c3",
100-
version: "0.0.31-t3x.6",
119+
version: "0.0.31-coil.6",
101120
});
102121
expect(parsePendingInstall(encoded)).toEqual({
103122
shortSha: "dd90bbace7c3",
104-
version: "0.0.31-t3x.6",
123+
version: "0.0.31-coil.6",
105124
});
106125
});
107126

‎apps/desktop/src/coil/updateDelivery/config.ts‎

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -110,13 +110,24 @@ export function encodePendingInstall(target: PendingInstall): string {
110110
/**
111111
* The build counter of the running app, read out of its own version string.
112112
*
113-
* `t3x-release.yml` builds `<base>-t3x.<run_number>` and `build-update-manifest.mjs` asserts that
113+
* `coil-release.yml` builds `<base>-coil.<counter>` and `build-update-manifest.mjs` asserts that
114114
* the manifest's `buildNumber` is that same number, so parsing it back out here is reading the
115115
* value the release wrote — not re-deriving it. An upstream build (`0.0.31`, no suffix) yields
116116
* `undefined`, which `decideUpdateAction` treats as "no floor", so the first fork build installs.
117+
*
118+
* Both suffixes, because this function is asked about two different version strings. The obvious
119+
* one is the running app's own, and for a `-t3x.` build that is answered by the `-t3x.`-only code
120+
* it shipped with — this branch never runs there. The one that matters is the version the app is
121+
* asked to *compare against* around the cutover: a build carrying this code can still be offered,
122+
* or be preceded by, a `-t3x.` release. Returning `undefined` for those would erase the floor
123+
* entirely and make a genuinely older build look installable.
124+
*
125+
* Note the numbers stay comparable across the rename by construction, not by luck: the counter is
126+
* `github.run_number + 100` precisely so `-coil.101` outranks `-t3x.26`. Nothing here compares the
127+
* suffixes themselves, which is fortunate — `coil` sorts before `t3x`.
117128
*/
118129
export function parseBuildNumber(version: string): number | undefined {
119-
const match = /-t3x\.(\d+)$/u.exec(version.trim());
130+
const match = /-(?:coil|t3x)\.(\d+)$/u.exec(version.trim());
120131
if (match === null) return undefined;
121132
const parsed = Number(match[1]);
122133
return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : undefined;

‎apps/desktop/src/coil/updateDelivery/decision.test.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ const MANIFEST: UpdateManifest = {
77
shortSha: "ffffffffffff",
88
buildNumber: 20,
99
sha: "f".repeat(40),
10-
version: "0.0.31-t3x.ffffffffffff",
10+
version: "0.0.31-coil.ffffffffffff",
1111
releaseTag: "t3x-build-ffffffffffff",
1212
builtAt: "2026-08-03T12:00:00.000Z",
1313
assets: [
@@ -54,7 +54,7 @@ describe("decideUpdateAction", () => {
5454

5555
it("refuses to act when this build carries no release counter", () => {
5656
// Changed deliberately on 2026-08-07; it previously acted. `buildNumber` comes from the app's
57-
// own version, and only `t3x-release.yml` writes `-t3x.<n>` — so `undefined` does not mean
57+
// own version, and only `coil-release.yml` writes `-coil.<n>` — so `undefined` does not mean
5858
// "first run", it means "this app was built locally". Treating that as "no floor" let a
5959
// locally built app install ANY announced release over itself, including one cut from an
6060
// OLDER commit than the one it was built from: a silent downgrade that reports success.

‎apps/desktop/src/coil/updateDelivery/decision.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -99,7 +99,7 @@ export function decideUpdateAction(
9999

100100
// No counter means no way to order, and "cannot order" must not silently mean "accept".
101101
//
102-
// Only builds from `t3x-release.yml` carry `-t3x.<n>`; anything built locally
102+
// Only builds from `coil-release.yml` carry `-coil.<n>`; anything built locally
103103
// (`auto-build-desktop.sh`, a hand-run `build:desktop`) is a bare `0.0.31`. Treating a missing
104104
// counter as "no floor" let such a build install ANY announced release over itself — including
105105
// one cut from an older commit than the one it was built from. That downgrade reports success,

0 commit comments

Comments
 (0)