Skip to content

Commit 258f2de

Browse files
radroidclaude
andcommitted
Update toast: changelog-forward design, and a restart that waits for you (#55)
The update toast led with a 12-char SHA, called the build "staged", and never said what changed — the only interesting question on a fork you maintain yourself. Its failure state printed a log path as unclickable text, and "Later" duplicated the corner dismiss. The toast now leads with the change count, puts the commit subjects behind a "What changed" disclosure, pins the build age top-right linking to the workflow run, and replaces "Later" with "Restart when idle". Wired end to end: CI computes the changelog, the manifest carries it, and the app renders it. The relay needed no deploy — it parses buildNumber for ordering and treats the rest as opaque. Decisions that carry risk: The changelog is anchored on the previous RELEASE TAG, not branch ancestry. The sync playbook force-pushes main, so a released commit may not be an ancestor of it. Tags survive the rewrite, and `git log A..B` stays correct when A is not an ancestor. Capped at 20. Idleness reads latestTurn.state, not session.status — #38 records that session.status deadlocks on synthetic turns, and a stuck status here means an armed restart that never fires. Archived and settled threads are excluded; scope is the primary environment only, since remote threads survive the restart. An armed restart has a two-hour ceiling and stands DOWN on expiry. It does not restart anyway (that kills the work the arm protected) and does not wait in silence (#41's dark app with extra steps). Silent-failure tripwires: RUN_ID is rejected when it equals RUN_NUMBER (they are different numbers and the counter yields a 404); empty changelogs are omitted rather than emitted; every new field is optional so an older manifest still decodes, because a required one would fail the decode and silently withhold a real update. Commit subjects are attacker-influenced, so the GITHUB_OUTPUT heredoc uses a random delimiter — with a fixed one a subject equal to that literal would close it early and write arbitrary job outputs that this workflow uses to publish a release. No new upstream seam: ui/toast.tsx stays untouched. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
1 parent 13569f1 commit 258f2de

9 files changed

Lines changed: 764 additions & 12 deletions

File tree

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

Lines changed: 54 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -47,17 +47,23 @@ jobs:
4747
name: Resolve build identity
4848
if: ${{ github.event_name == 'workflow_dispatch' || github.event.workflow_run.conclusion == 'success' }}
4949
runs-on: ubuntu-latest
50-
timeout-minutes: 5
50+
timeout-minutes: 10
5151
outputs:
5252
sha: ${{ steps.identity.outputs.sha }}
5353
short_sha: ${{ steps.identity.outputs.short_sha }}
5454
version: ${{ steps.identity.outputs.version }}
5555
tag: ${{ steps.identity.outputs.tag }}
56+
changes: ${{ steps.identity.outputs.changes }}
5657
steps:
5758
- name: Checkout
5859
uses: actions/checkout@v6
5960
with:
6061
ref: ${{ env.BUILD_SHA }}
62+
# Full history and tags: the changelog is `git log <previous release tag>..<sha>`, and a
63+
# shallow clone has neither endpoint. Only this job pays for it; build and publish stay
64+
# shallow.
65+
fetch-depth: 0
66+
fetch-tags: true
6167
# .repos/ is tracked: 12,961 files, 126 MB. Upstream excludes it from every job.
6268
sparse-checkout: |
6369
/*
@@ -116,6 +122,47 @@ jobs:
116122
echo "version=${base}-t3x.${BUILD_COUNTER}" >> "$GITHUB_OUTPUT"
117123
echo "tag=t3x-build-${short_sha}" >> "$GITHUB_OUTPUT"
118124
125+
# What changed since the last release we actually published.
126+
#
127+
# Anchored on the previous RELEASE TAG, not on main's ancestry. The sync playbook
128+
# force-pushes main, so "the commits since the last build" cannot be derived from
129+
# branch history — a released commit may not even be an ancestor of main. Tags survive
130+
# that rewrite, and `git log A..B` is "reachable from B, not from A", which stays
131+
# correct when A is not an ancestor of B.
132+
#
133+
# Newest first. Merge commits are dropped: on a squash-merge fork their subjects are
134+
# duplicates of the commit they merged.
135+
previous="$(git tag --list 't3x-build-*' --sort=-creatordate | head -n 1 || true)"
136+
if [[ -z "$previous" ]]; then
137+
# First release ever: there is no range. Emitting the entire history as a "changelog"
138+
# would render a toast with thousands of entries.
139+
echo "No previous t3x-build-* tag; emitting an empty changelog."
140+
changes=""
141+
else
142+
echo "Changelog range: ${previous}..${sha}"
143+
# Capped. An unbounded range after a long CI outage (four straight failures has
144+
# happened here) would produce a toast nobody can read, and a manifest nobody wants to
145+
# ship. The count in the title still comes from this list, so the cap is visible as
146+
# "20 changes" rather than silently truncating a larger number.
147+
changes="$(git log "${previous}..${sha}" --no-merges --format=%s --max-count=20 || true)"
148+
fi
149+
150+
# Commit subjects are attacker-influenced content — anyone whose commit reaches main,
151+
# including an upstream sync, chooses this text. Two hardening steps, both load-bearing:
152+
#
153+
# 1. A random delimiter. With a fixed one, a commit subject equal to that literal would
154+
# close the heredoc early and let the rest of the subject write arbitrary job outputs
155+
# (`tag=`, `sha=`) — which this workflow then uses to tag and publish a release.
156+
# 2. Control characters stripped, so nothing can smuggle a newline or an escape sequence
157+
# into a value that later lands in an env var and a toast.
158+
delim="T3X_CHANGES_$(openssl rand -hex 16)"
159+
changes="$(printf '%s' "$changes" | tr -d '\000-\010\013\014\016-\037')"
160+
{
161+
echo "changes<<${delim}"
162+
echo "$changes"
163+
echo "${delim}"
164+
} >> "$GITHUB_OUTPUT"
165+
119166
build:
120167
name: Build ${{ matrix.label }}
121168
needs: [resolve]
@@ -388,6 +435,12 @@ jobs:
388435
VERSION: ${{ needs.resolve.outputs.version }}
389436
REPOSITORY: ${{ github.repository }}
390437
RUN_NUMBER: ${{ github.run_number }}
438+
# run_id addresses the run URL; run_number is the build counter. Different numbers —
439+
# passing run_number here yields a link to whichever run happens to own that id.
440+
RUN_ID: ${{ github.run_id }}
441+
# Read as an env var, never interpolated into shell source: these are commit subjects,
442+
# so the content is chosen by whoever wrote the commit.
443+
CHANGES: ${{ needs.resolve.outputs.changes }}
391444
run: node scripts/t3x/build-update-manifest.mjs staged staged/t3x-latest.json
392445

393446
- name: Create release

‎apps/desktop/src/ipc/methods/t3xUpdate.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,12 @@ const UpdateStatus = Schema.Union([
2222
kind: Schema.Literal("ready"),
2323
shortSha: Schema.String,
2424
version: Schema.String,
25+
// Optional because the manifest's are: a build published before these fields existed still
26+
// has to reach the renderer. A required field here would fail the encode and the toast would
27+
// never appear — withholding a real update, which is the failure this feature exists to fix.
28+
changes: Schema.optionalKey(Schema.Array(Schema.String)),
29+
builtAt: Schema.optionalKey(Schema.String),
30+
runUrl: Schema.optionalKey(Schema.String),
2531
}),
2632
Schema.Struct({ kind: Schema.Literal("restarting") }),
2733
Schema.Struct({

‎apps/desktop/src/t3x/updateDelivery/UpdateDelivery.ts‎

Lines changed: 18 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -184,7 +184,9 @@ export const make = Effect.gen(function* () {
184184
// Interruption is a supersede, not a failure: a newer build was announced and this download
185185
// was abandoned deliberately. Clearing the marker is the only thing owed, and the half-
186186
// written `.part` file is swept on the next run because its bytes were never checksummed.
187-
Effect.ensuring(Ref.update(internal, (current) => ({ ...current, inFlightShortSha: undefined }))),
187+
Effect.ensuring(
188+
Ref.update(internal, (current) => ({ ...current, inFlightShortSha: undefined })),
189+
),
188190
);
189191

190192
if (staged === undefined) return;
@@ -196,7 +198,20 @@ export const make = Effect.gen(function* () {
196198
// clicks, this app should ignore anything older than what is already sitting on its disk.
197199
buildNumberFloor: manifest.buildNumber,
198200
}));
199-
yield* setStatus({ kind: "ready", shortSha: staged.shortSha, version: staged.version });
201+
// The display fields ride the manifest, not the staged bundle: they describe the build that
202+
// was announced, and `staged` only knows what was written to disk. Spread conditionally so an
203+
// older manifest that carried neither produces a status without the keys rather than with
204+
// `undefined` values, which the IPC schema would then have to accept.
205+
yield* setStatus({
206+
kind: "ready",
207+
shortSha: staged.shortSha,
208+
version: staged.version,
209+
...(manifest.changes !== undefined && manifest.changes.length > 0
210+
? { changes: manifest.changes }
211+
: {}),
212+
builtAt: manifest.builtAt,
213+
...(manifest.runUrl !== undefined ? { runUrl: manifest.runUrl } : {}),
214+
});
200215
yield* Effect.logInfo(`t3x update: ${staged.shortSha} is staged and ready`);
201216
});
202217

@@ -451,9 +466,7 @@ const spawnAwaited = Effect.fn("t3x.updateDelivery.spawnAwaited")(function* (
451466
.spawn(
452467
ChildProcess.make(bin, [...args], { stdin: "ignore", stdout: "ignore", stderr: "ignore" }),
453468
)
454-
.pipe(
455-
Effect.mapError((cause) => new T3xInstallCommandError({ bin, detail: String(cause) })),
456-
);
469+
.pipe(Effect.mapError((cause) => new T3xInstallCommandError({ bin, detail: String(cause) })));
457470
const exitCode = yield* handle.exitCode.pipe(
458471
Effect.mapError((cause) => new T3xInstallCommandError({ bin, detail: String(cause) })),
459472
);

‎apps/desktop/src/t3x/updateDelivery/manifest.ts‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,17 @@ export const UpdateManifest = Schema.Struct({
5252
version: Schema.String,
5353
releaseTag: Schema.String,
5454
builtAt: Schema.String,
55+
/**
56+
* Commit subjects in this build, newest first.
57+
*
58+
* `optionalKey`, and it must stay that way: a client running this build can be offered a
59+
* manifest published *before* the field existed, and a required field would fail the decode —
60+
* which this pipeline treats as "no update", silently withholding a real one. The same reason
61+
* `runUrl` is optional.
62+
*/
63+
changes: Schema.optionalKey(Schema.Array(Schema.String)),
64+
/** The workflow run that produced this build. Built from `run_id`, never `run_number`. */
65+
runUrl: Schema.optionalKey(Schema.String),
5566
assets: Schema.Array(UpdateAsset).check(Schema.isMinLength(1)),
5667
});
5768
export type UpdateManifest = typeof UpdateManifest.Type;

0 commit comments

Comments
 (0)