Skip to content

Commit 85fb4d0

Browse files
radroidclaude
authored andcommitted
docs(coil): design the t3x -> coil rename around its four silent failures (#71)
The rename is mechanical; the risk is not. Four of the strings involved are load-bearing for something that outlives the merge, and each fails without an error surface: - the build counter is github.run_number, keyed to a WORKFLOW FILENAME, so renaming t3x-release.yml restarts it at 1 against clients sitting at 26 and every one of them skips forever. The issue attributes this hazard to the version string; that part is genuinely safe. The filename is not. - the relay hostname is compiled into builds already on disk, so the old Worker has to serve permanently. The shim proxies rather than redirects: relayClient talks through Effect's HttpClient and treats any non-2xx as bad-status, and redirect behaviour on a live SSE stream cannot be tested against builds already in the field. - a LaunchAgent plist hardcodes scripts/t3x/auto-build-desktop.sh, so the rename stops the nightly build with no log line. Same failure class as #41. - app.setName() sets the safeStorage Keychain service name, so saved environment tokens stop decrypting. Threads are unaffected -- userDataDirName is a hardcoded literal, not derived -- which is why #85 moved nobody's data. Also records the two deliberate displacement edits (APP_BASE_NAME, productName) that break the fork's +N/-0 seam invariant, so a later sync reads them as recorded rather than as drift. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
1 parent 69005e4 commit 85fb4d0

1 file changed

Lines changed: 204 additions & 0 deletions

File tree

Lines changed: 204 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,204 @@
1+
# Renaming the fork's identity from `t3x` to `coil`
2+
3+
Issue [#71](https://github.com/radroid/t3code/issues/71). The landing site was rebranded to Coil in
4+
PR #69 and deliberately stopped there. This moves everything else.
5+
6+
The rename itself is mechanical. What makes it a design problem is that four of the strings being
7+
renamed are load-bearing for something that outlives the merge: a monotonic counter GitHub derives
8+
from a filename, a hostname compiled into builds already on disk, a path baked into a LaunchAgent
9+
plist, and a macOS Keychain service name. Each one fails silently — no error, no log line, just a
10+
capability that quietly stops working. The bulk of this document is about those four.
11+
12+
## Decisions
13+
14+
| Question | Decision |
15+
|---|---|
16+
| Scope | All four stages of the issue, including the relay |
17+
| App name | `T3 Coil (Alpha)` |
18+
| Bundle id | `dev.curlycloud.coil` → `dev.curlycloud.t3coil` |
19+
| Signing certificate | `T3X Code Signing` → `T3 Coil Code Signing` |
20+
| First renamed build | One-time manual install; the updater's refusal is reworded, not bypassed |
21+
| Relay | `coil-update-relay` becomes authoritative; `t3x-update-relay` stays deployed as a proxy |
22+
| GitHub secrets and repo variables | Keep the `T3X_` prefix |
23+
24+
Two of these have a cost that is paid by the user rather than by CI, and both are worth restating
25+
because neither is recoverable by editing code after the fact.
26+
27+
**The bundle id and the certificate each cost one full round of macOS permission dialogs.** macOS
28+
keys TCC grants — Screen Recording, Accessibility, Files & Folders — on the pair
29+
`(service, bundle id)`, and the *designated requirement* that authenticates the app names both the
30+
bundle id and the signing certificate. Changing either invalidates every existing grant. Changing
31+
both at once costs one round of prompts, not two, which is the only reason to do them together.
32+
This is the second such reset in a week (PR #85 was the first), and it should be the last: both
33+
values are now the ones the fork intends to keep.
34+
35+
**Neither cost is incurred at merge time.** It lands when the renamed build is installed. So
36+
`DESKTOP_BUNDLE_IDENTIFIER` and `MAC_SIGNING_IDENTITY_NAME` are single constants in
37+
`scripts/coil/mac-signature.ts`, with a test that fails if their four downstream copies drift —
38+
changing them before merge is a one-line edit, and after merge is a permission reset.
39+
40+
## The four silent failures
41+
42+
### 1. The build counter is keyed to a filename
43+
44+
`t3x-release.yml:80` sets `BUILD_COUNTER: ${{ github.run_number }}`, and `:122` spends it as the
45+
version's prerelease identifier. `run_number` is scoped to a workflow, and GitHub identifies a
46+
workflow by its **file path**. Renaming the file to `coil-release.yml` therefore does not continue
47+
the sequence — it starts a new one at 1.
48+
49+
That interacts badly with the one comparison the updater actually makes (`decision.ts:118`):
50+
51+
```ts
52+
if (manifest.buildNumber <= installed.buildNumber) {
53+
return { kind: "skip", reason: "not-newer" };
54+
}
55+
```
56+
57+
Published builds are at 26 and the workflow's `run_number` is at 32. A renamed workflow would
58+
publish build 1, every installed client would evaluate `1 <= 26`, and all of them would skip
59+
forever. There is no error surface for this: skipping is the normal, expected outcome of that
60+
branch, so it looks exactly like being up to date.
61+
62+
Issue #71 names this hazard but attributes it to the *version string*, and concludes the suffix
63+
change is safe because the updater never compares versions. Both halves of that are true and
64+
neither is the risk. The risk is the filename.
65+
66+
**Resolution.** Rename the file and offset the counter:
67+
68+
```yaml
69+
BUILD_COUNTER: ${{ github.run_number + 100 }}
70+
```
71+
72+
100 clears both the current run (32) and the published high-water mark (26) with room that no
73+
plausible backfill closes. The first coil build is 101. The offset is permanent and load-bearing —
74+
removing it later re-creates the same failure — so it carries a comment saying so.
75+
76+
Two smaller consequences of the same rename:
77+
78+
- `parseBuildNumber` (`config.ts`) matches `/-t3x\.(\d+)$/`. It gains `-coil.N` and **keeps**
79+
`-t3x.N`. Keeping it is not for old clients — those run their own old code against their own old
80+
version and are unaffected — but for the interim where a `-t3x.` release is still the newest
81+
thing on disk while new code reads it, and so that the regex documents both eras.
82+
- The changelog anchors on `git tag --list 't3x-build-*'`. Unchanged, the first coil release finds
83+
no previous tag, takes the "first release ever" branch, and emits an empty changelog; the
84+
`--max-count=20` cap keeps that from being catastrophic but the entry is still wrong. The lookup
85+
spans both prefixes, permanently.
86+
87+
### 2. The relay hostname is compiled into builds already on disk
88+
89+
`config.ts:24` hardcodes `https://t3x-update-relay.businesses.workers.dev`. The env override exists
90+
but no normal install sets it — deliberately, because a `.app` launched from Finder inherits
91+
launchd's environment and not a shell's. So every shipped build polls that exact hostname for as
92+
long as it runs, and if the hostname stops answering they go silent with no channel left to tell
93+
them.
94+
95+
`coil-update-relay` becomes the authoritative Worker and `DEFAULT_RELAY_URL` points at it. The old
96+
hostname stays deployed permanently, serving the same data.
97+
98+
**The shim proxies; it does not redirect.** The issue suggests "proxy or 302". Those are not
99+
equivalent here. `relayClient.ts` talks to the relay through Effect's `HttpClient`, not raw `fetch`,
100+
and it classifies any non-2xx response as `bad-status` on both tiers. Whether that client follows a
101+
307 on a streaming `text/event-stream` response is not a fact that can be established against builds
102+
already in the field, and being wrong about it strands every one of them. A pass-through —
103+
`return fetch(rewrittenUrl, request)` — is byte-identical to today's behaviour from the client's
104+
side, streams SSE without special handling, and depends on nothing about redirect semantics. It
105+
costs the same handful of lines.
106+
107+
**Verification before cutover, against a real old build.** The `T3X_UPDATE_RELAY_URL` override does
108+
work when the `.app` is launched from a terminal rather than Finder, which makes it possible to
109+
point the *currently installed* build at a throwaway shim and confirm both `/latest` and `/events`
110+
behave. That is the only test that proves anything about clients in the field, so it is a gate on
111+
the relay cutover rather than a nice-to-have.
112+
113+
The old Worker keeps its Durable Object migration tag but stops using the binding; it holds no state
114+
once it is a proxy, so it cannot drift from the new one. Rollback is redeploying the current worker
115+
source, which stays in git history.
116+
117+
### 3. A LaunchAgent plist hardcodes a script path
118+
119+
`~/Library/LaunchAgents/dev.t3x.autobuild.plist` runs
120+
`/Users/rajdholakia/Developer/t3code/scripts/t3x/auto-build-desktop.sh --watch`. Renaming
121+
`scripts/t3x/` leaves launchd invoking a path that no longer exists. launchd does not report this
122+
anywhere the user looks; the nightly build simply stops happening. Issue #41 is the same failure
123+
class and cost 103 minutes before anyone noticed.
124+
125+
**Resolution.** The plist is reinstalled as a cutover step —
126+
`scripts/coil/auto-build-desktop.sh --print-launchd --install` — and the agent label moves from
127+
`dev.t3x.autobuild` to `dev.coil.autobuild`, so the old agent must be unloaded rather than
128+
overwritten. For one release the script reads both `T3X_AUTOBUILD_*` and `COIL_AUTOBUILD_*`
129+
environment names, so a plist that is half-migrated falls back to defaults instead of silently
130+
running with the wrong worktree or applications directory.
131+
132+
### 4. `app.setName()` sets a Keychain service name
133+
134+
`DesktopAppIdentity.ts:122` calls `electronApp.setName(environment.displayName)`. On macOS,
135+
Electron's `safeStorage` derives its Keychain item from the app name, and
136+
`DesktopSavedEnvironments.ts` uses `safeStorage` to encrypt saved-environment bearer tokens. Renaming
137+
the app therefore points `safeStorage` at a Keychain item that does not exist, and previously saved
138+
tokens do not decrypt.
139+
140+
Threads, settings and sessions are **not** affected, and this is worth stating precisely because the
141+
adjacent literals look like they should be. `userDataDirName = "t3code"` and
142+
`legacyUserDataDirName = "T3 Code (Alpha)"` (`DesktopEnvironment.ts:171-172`) are hardcoded, not
143+
derived from `displayName` or from the bundle id. That is why PR #85 moved nobody's threads, and it
144+
is why this rename does not either. Renaming *those* would orphan every thread and is out of scope.
145+
146+
**Resolution.** Accept the re-encrypt, but make it legible: the decode path is verified to degrade
147+
to a per-environment "re-enter this token" state rather than an error or an empty list. No
148+
migration is possible — the new build cannot decrypt what the old name encrypted — so the only
149+
choice is whether the user finds out from a clear prompt or from a confusing failure.
150+
151+
## What is deliberately not renamed
152+
153+
| Kept | Why |
154+
|---|---|
155+
| `userDataDirName` / `legacyUserDataDirName` | Renaming orphans every thread, setting and session |
156+
| GitHub secrets and repo variables (`T3X_*`) | Invisible to users and to macOS; renaming opens a window between merge and re-setting them where the release is broken, for no gain |
157+
| `~/.t3x/mac-signing`, `t3x-signing.keychain` | Local paths on one machine; moving them adds a manual step to an already manual certificate rotation |
158+
| `t3codeCommitHash`, `@t3tools/*`, `T3CODE_*` | Upstream's identity, not the fork's |
159+
| `apps/marketing/` | Untouched by design — see SEAMS.md's parallel-path note |
160+
161+
## Seam impact
162+
163+
Every fork edit on an upstream-owned file to date is `+N/-0`. That invariant is what makes the
164+
rebase check meaningful: because the fork only appends, anything that displaced upstream content
165+
would show up as a moved deletion count, so the count itself is the signal.
166+
167+
This change breaks it deliberately, in exactly two places:
168+
169+
- `APP_BASE_NAME` in `apps/desktop/src/app/DesktopEnvironment.ts`
170+
- `productName` in `apps/desktop/package.json`
171+
172+
Both are one-line literal replacements — the smallest possible displacement, and the reason
173+
`T3 Coil (Alpha)` was chosen over an unsuffixed `T3 Coil`, which would have meant restructuring
174+
`resolveDesktopAppBranding` instead. `SEAMS.md` is re-baselined and gains a carve-out naming these
175+
two lines, so a future sync reads the `-2` as recorded rather than as drift.
176+
177+
## Cutover
178+
179+
Ordering follows the issue's, with the relay last because it is the only step that cannot be
180+
rolled back by reverting a commit.
181+
182+
1. **Docs, scripts, source directories, IPC surface.** No runtime effect.
183+
2. **App identity.** Name, bundle id, certificate, reworded refusal.
184+
3. **Release identity.** Tags, version suffix, the counter offset.
185+
4. **Automation.** Workflow filenames, the `t3x-sync` label, `t3x/sync-*` branch and recovery-tag
186+
prefixes. These are matched by *running* workflows, so they land together, and they land only
187+
when no sync issue or sync PR is open. `coil-ci.yml`'s push trigger matches both branch prefixes
188+
for one cycle.
189+
5. **Relay.** Deploy `coil-update-relay`, verify the shim against an installed build, then redeploy
190+
the old hostname as the proxy.
191+
192+
Manual steps, all in the PR body: create the `coil-sync` label, unload and reinstall the LaunchAgent,
193+
rotate the signing certificate and re-record the designated requirement, deploy both Workers, and
194+
drag the first dmg once.
195+
196+
## Verification
197+
198+
- `parseBuildNumber` covers `-coil.N`, `-t3x.N`, and an unsuffixed upstream version.
199+
- `mac-signature.test.ts` still enforces that the bundle id agrees across all four of its copies.
200+
- `installTarget.test.ts` covers the reworded refusal and asserts it still refuses.
201+
- Relay worker tests cover the proxy path for `/latest` and `/events`.
202+
- Typecheck, lint and the full test suite.
203+
- The first coil release is checked by hand for `buildNumber: 101` and a non-empty changelog before
204+
anything is expected to update itself.

0 commit comments

Comments
 (0)