|
| 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