Skip to content

Commit 743f96f

Browse files
radroidclaude
andcommitted
feat(t3x): put the fork's build counter in the version, and bound the restart
Two changes. **Versioning.** The fork build version was 0.0.31-t3x.<shortsha>. That is identifiable but not orderable: semver compares prerelease identifiers, and -t3x.a3f9c21b versus -t3x.b0e77c14 sorts alphabetically by hash, which orders nothing. Since the upstream base never moves between syncs (#47), the fork had no working notion of "newer" in its own version string at all. It now carries the CI run number: 0.0.31-t3x.43. Numeric identifiers sort numerically, and it is the SAME number the manifest carries as buildNumber and the relay orders on — one counter everywhere, rather than a version scheme that disagrees with the update logic. build-update-manifest.mjs asserts the version ends with the counter, so the two cannot drift into a state where the app orders by one value and displays another. The sha is not lost: release tag, both filenames, the manifest, and t3codeCommitHash. The version answers "which is newer", the hash answers "which commit", and keeping those apart is the lesson of #47. **Restart.** A fork-owned restart path rather than DesktopLifecycle.relaunch, which cannot be used here for two reasons. Its shutdown wait is unbounded — a wedged PTY or an SSH tunnel that never returns means the relaunch never fires and the app sits dark indefinitely, which is #41 through a different door. And it re-execs process.execPath, which under App Translocation points into a read-only snapshot, so the app would return on the OLD build with verification passing against the wrong process. Adding a timeout to DesktopLifecycle.ts was the alternative. It would have been seam row 36 on a file the fork does not currently touch, against a ledger whose tripwire asks for re-isolation first — so the bounded path lives in fork-owned code and arms the relaunch immediately before exit, never earlier, so a failed wait cannot leave a booby-trapped Cmd-Q behind. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
1 parent 0c0307b commit 743f96f

4 files changed

Lines changed: 151 additions & 11 deletions

File tree

‎.github/workflows/t3x-release.yml‎

Lines changed: 25 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,8 @@ jobs:
7070
# BUILD_SHA is read from the environment rather than interpolated into the script. On the
7171
# workflow_dispatch path it is user-supplied, and `${{ }}` interpolation splices the raw
7272
# value into the shell source before bash ever sees it.
73+
env:
74+
BUILD_COUNTER: ${{ github.run_number }}
7375
run: |
7476
set -euo pipefail
7577
if [[ ! "$BUILD_SHA" =~ ^[0-9a-f]{40}$ ]]; then
@@ -88,13 +90,30 @@ jobs:
8890
# actually read about itself, so it is the only honest comparison key.
8991
short_sha="$(git rev-parse --short=12 HEAD)"
9092
91-
# --build-version becomes electron-builder's `version`, which must be valid semver — a
92-
# raw SHA is not. resolveDesktopUpdateChannel only special-cases -nightly.<d>.<d>, so a
93-
# -t3x. prerelease stays on the "latest" channel and the product name is unchanged.
93+
# The fork's build counter, and the reason the version is orderable at all.
94+
#
95+
# The upstream base does not move between syncs (0.0.31 -> 0.0.31, issue #47), so without
96+
# a fork-owned counter every build here would carry an identical version. An earlier
97+
# draft used the short sha instead: identifiable, but semver compares prerelease
98+
# identifiers, and `-t3x.a3f9c21b` vs `-t3x.b0e77c14` sorts alphabetically by hash, which
99+
# orders nothing. A numeric identifier sorts numerically, so 0.0.31-t3x.43 correctly
100+
# precedes 0.0.31-t3x.44.
101+
#
102+
# This is the SAME number the manifest carries as buildNumber and the relay orders on.
103+
# One counter, used everywhere, rather than a version scheme that disagrees with the
104+
# update logic.
105+
#
106+
# The sha is not lost: it is in the release tag, both asset filenames, the manifest, and
107+
# t3codeCommitHash inside the app. Version answers "which is newer"; the hash answers
108+
# "which commit". Keeping those separate is the whole lesson of #47.
109+
#
110+
# --build-version becomes electron-builder's `version` and must be valid semver — a raw
111+
# sha is not. resolveDesktopUpdateChannel only special-cases -nightly.<d>.<d>, so a -t3x.
112+
# prerelease stays on the "latest" channel and the product name is unchanged.
94113
base="$(node -p "require('./apps/desktop/package.json').version")"
95-
echo "sha=$sha" >> "$GITHUB_OUTPUT"
96-
echo "short_sha=$short_sha" >> "$GITHUB_OUTPUT"
97-
echo "version=${base}-t3x.${short_sha}" >> "$GITHUB_OUTPUT"
114+
echo "sha=$sha" >> "$GITHUB_OUTPUT"
115+
echo "short_sha=$short_sha" >> "$GITHUB_OUTPUT"
116+
echo "version=${base}-t3x.${BUILD_COUNTER}" >> "$GITHUB_OUTPUT"
98117
echo "tag=t3x-build-${short_sha}" >> "$GITHUB_OUTPUT"
99118
100119
build:
Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
import * as Duration from "effect/Duration";
2+
import * as Effect from "effect/Effect";
3+
4+
import * as ElectronApp from "../../electron/ElectronApp.ts";
5+
import * as DesktopShutdown from "../../app/DesktopShutdown.ts";
6+
7+
/**
8+
* Restarting into a freshly installed build.
9+
*
10+
* This deliberately does **not** call `DesktopLifecycle.relaunch`, even though that exists and does
11+
* almost this. Two differences make it unusable here, and both are load-bearing:
12+
*
13+
* 1. **Its shutdown wait is unbounded.** `requestDesktopShutdownAndWait` awaits a bare `Deferred`
14+
* that resolves only once every backend has stopped, and `DesktopBackendManager.closeRun` takes
15+
* a no-timeout branch when given no options. A wedged PTY drain, an SSH tunnel, or a `wsl.exe`
16+
* backend that never returns means the relaunch never fires — the app sits on "Restarting…"
17+
* indefinitely. That is issue #41 reached through a different door: an app that is dark, for an
18+
* unbounded time, with no error anywhere.
19+
*
20+
* 2. **It re-execs `process.execPath`.** Under macOS App Translocation that points into a
21+
* randomised read-only snapshot, so the app would come back on the OLD build while
22+
* post-install verification passed against the wrong process. `installTarget.ts` refuses
23+
* translocated paths before we ever get here, but the exec path still has to come from the
24+
* install target rather than from the running process.
25+
*
26+
* Editing `DesktopLifecycle.ts` to add a timeout was the other option. It would have added seam
27+
* row 36 to a ledger whose own tripwire asks for re-isolation first, on a file the fork does not
28+
* currently touch — so this restart path lives here instead.
29+
*/
30+
31+
/**
32+
* How long to let a graceful shutdown run before forcing the exit.
33+
*
34+
* Long enough for a healthy teardown — backends stop in well under a second normally — and short
35+
* enough that a hung one costs the user ten seconds rather than their whole session. The relaunch
36+
* is armed before the timer starts, so a forced exit still comes back up.
37+
*/
38+
export const SHUTDOWN_GRACE = Duration.seconds(10);
39+
40+
export type RestartOutcome = "graceful" | "forced-after-timeout";
41+
42+
/**
43+
* Quit and come back on the new build.
44+
*
45+
* Ordering is the point of this function:
46+
*
47+
* 1. Ask for shutdown and wait, bounded.
48+
* 2. Arm the relaunch — immediately before exiting, never earlier. `app.relaunch()` registers
49+
* intent for the *next* quit, so arming it before a wait that might fail would leave the app
50+
* alive with a booby-trapped Cmd-Q that silently resurrects it later.
51+
* 3. Exit, whether or not the shutdown finished.
52+
*/
53+
export const restartIntoInstalledBuild = Effect.fn("t3x.updateDelivery.restart")(function* (args: {
54+
readonly execPath: string;
55+
readonly argv: readonly string[];
56+
}) {
57+
const electronApp = yield* ElectronApp.ElectronApp;
58+
const shutdown = yield* DesktopShutdown.DesktopShutdown;
59+
60+
yield* shutdown.request;
61+
62+
// `Effect.timeout` fails on expiry; the failure is the signal to stop waiting, not an error to
63+
// report. Either way we exit — the only difference is whether backends got to close cleanly.
64+
const outcome: RestartOutcome = yield* shutdown.awaitComplete.pipe(
65+
Effect.timeout(SHUTDOWN_GRACE),
66+
Effect.as<RestartOutcome>("graceful"),
67+
Effect.catch(() => Effect.succeed<RestartOutcome>("forced-after-timeout")),
68+
);
69+
70+
if (outcome === "forced-after-timeout") {
71+
yield* Effect.logWarning(
72+
"t3x: shutdown did not finish within the grace period; forcing exit so the relaunch still happens",
73+
);
74+
}
75+
76+
yield* electronApp.relaunch({ execPath: args.execPath, args: [...args.argv] });
77+
yield* electronApp.exit(0);
78+
79+
return outcome;
80+
});
81+
82+
/**
83+
* The executable to re-exec, derived from the bundle we just installed into.
84+
*
85+
* Never `process.execPath` — see the translocation note above.
86+
*/
87+
export function executablePathForBundle(appBundlePath: string, appName: string): string {
88+
const binaryName = appName.endsWith(".app") ? appName.slice(0, -".app".length) : appName;
89+
return `${appBundlePath}/Contents/MacOS/${binaryName}`;
90+
}

‎docs/superpowers/specs/2026-08-03-update-delivery-design.md‎

Lines changed: 25 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -150,10 +150,30 @@ Also required at the workflow level: `permissions: contents: write` (upstream's
150150
(`:2035`). Upload is a separate workflow step, exactly as upstream does it. Earlier drafts of this
151151
design claimed publishing came for free; it does not.
152152

153-
**Version must be semver, so identity is carried separately.** `--build-version` becomes
154-
electron-builder's `version` field and a 40-char SHA is not valid semver. Use
155-
`0.0.31-t3x.<shortsha>`; `resolveDesktopUpdateChannel` only special-cases `-nightly.<d>.<d>`
156-
(`:1478`), so this stays on the `latest` channel and the product name is unchanged.
153+
**The version carries the fork's build counter: `0.0.31-t3x.<buildNumber>`.**
154+
155+
The upstream base does not move between syncs (#47), so a fork-owned counter is the only thing
156+
distinguishing one build from the next. It must be **numeric**: semver compares prerelease
157+
identifiers, and an earlier draft used the short sha — identifiable, but `-t3x.a3f9c21b` versus
158+
`-t3x.b0e77c14` sorts alphabetically by hash, which orders nothing. Numeric identifiers sort
159+
numerically, so `0.0.31-t3x.43` correctly precedes `0.0.31-t3x.44`.
160+
161+
It is the **same** `github.run_number` the manifest carries as `buildNumber` and the relay orders
162+
on. One counter used everywhere, rather than a version scheme that disagrees with the update logic.
163+
`build-update-manifest.mjs` asserts the version ends with `-t3x.<buildNumber>`, so the two cannot
164+
drift into a state where the app orders by one value and displays another.
165+
166+
The sha is not lost — it is in the release tag, both asset filenames, the manifest, and
167+
`t3codeCommitHash` inside the app. **The version answers "which is newer"; the hash answers "which
168+
commit".** Keeping those two questions apart is the whole lesson of #47.
169+
170+
`resolveDesktopUpdateChannel` only special-cases `-nightly.<d>.<d>` (`:1478`), so a `-t3x.`
171+
prerelease stays on the `latest` channel and the product name is unchanged.
172+
173+
One cosmetic consequence, accepted: semver sorts any prerelease *below* the plain release, so
174+
`0.0.31-t3x.43` ranks below a bare `0.0.31`. Nothing in this design compares version strings, so it
175+
never affects behaviour — but it is why the About box shows a version that looks like a
176+
pre-release of upstream's.
157177

158178
**Identity reuses what already exists.** The build script already runs
159179
`git rev-parse --short=12 HEAD` (`:523`) and writes `t3codeCommitHash` into the staged
@@ -216,7 +236,7 @@ The final step of the release workflow POSTs to the Worker:
216236
{
217237
"sha": "<40-char, display and traceability only>",
218238
"shortSha": "<12-char, the comparison key>",
219-
"version": "0.0.31-t3x.<shortsha>",
239+
"version": "0.0.31-t3x.<buildNumber>",
220240
"builtAt": "<ISO8601>",
221241
"releaseTag": "t3x-build-<shortsha>",
222242
"assets": [{ "platform": "darwin-arm64", "url": "…", "sha256": "…", "bytes": 123 }]

‎scripts/t3x/build-update-manifest.mjs‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,17 @@ if (!Number.isSafeInteger(buildNumber) || buildNumber <= 0) {
4545
throw new Error(`RUN_NUMBER must be a positive integer, got "${process.env.RUN_NUMBER}".`);
4646
}
4747

48+
// The version's counter and the manifest's ordering key are the same number by construction.
49+
// Asserted rather than assumed: if they ever drift, the app would order updates by one value while
50+
// displaying another, and "0.0.31-t3x.44 is installed" could be a build the client considers older
51+
// than what it already has. Cheap check, silent failure if omitted.
52+
if (!version.endsWith(`-t3x.${buildNumber}`)) {
53+
throw new Error(
54+
`VERSION "${version}" does not end with the build counter "-t3x.${buildNumber}". ` +
55+
"The release workflow must derive both from github.run_number.",
56+
);
57+
}
58+
4859
const assets = NodeFS.readdirSync(inputDir)
4960
.filter((name) => name.startsWith("asset-") && name.endsWith(".json"))
5061
.map((name) => JSON.parse(NodeFS.readFileSync(NodePath.join(inputDir, name), "utf8")))

0 commit comments

Comments
 (0)