# Files changed · PR \#19559 · pingdotgg/t3code

[View on GitCafe](https://git.cafe/pingdotgg/t3code/pull/19559/diffs)

Repository: [pingdotgg/t3code](https://git.cafe/pingdotgg/t3code)

Visibility: public

[refactor: prune narration and history comments](https://git.cafe/pingdotgg/t3code/pull/19559.md)

Version: 4

Head commit: 391c8d32d02b8f95b8dfa8d987444d5664ff4ef5

Base commit: ba3582222fcd378fab79d49aee6db65c4b4925b3

Comparison base: ba3582222fcd378fab79d49aee6db65c4b4925b3

Showing up to 20 entries from this revision. If the pull request changes, reopen the first page before continuing.

## \.coderabbit.config.ts

Status: modified; +1; −6

```diff
@@ -1,6 +1,5 @@
 import { defineConfig, type CodeRabbitContext } from "@coderabbitai/config";
 
-// Org members and collaborators can approve their own pull requests.
 const UNGATED_AUTHORS = new Set(["OWNER", "MEMBER", "COLLABORATOR"]);
 const isGated = ({ pr }: CodeRabbitContext) => !UNGATED_AUTHORS.has(pr?.authorAssociation ?? "");
 
@@ -17,11 +16,7 @@
       docstrings: { mode: "off" },
       override_requested_reviewers_only: isGated(ctx),
     },
-    path_filters: [
-      // Vendored read-only reference checkouts of upstream Effect and Alchemy
+    path_filters: ["!.repos/**"],
-      // (see scripts/lib/reference-repos.ts). Nothing imports from them.
-      "!.repos/**",
-    ],
     path_instructions: [
       {
         path: "{apps,packages,infra}/**/*.ts",
```

## \.github/scripts/check-nightly-release.cjs

Status: modified; +0; −6

```diff
@@ -40,7 +40,6 @@
 
 const isNightlyTag = (tag) => /^v.*-nightly\./.test(tag) || tag.startsWith("nightly-v");
 
-// Newest published nightly by publication time, or undefined when none exists.
 async function findLatestNightly({ github, context }) {
   const releases = await github.paginate(github.rest.repos.listReleases, {
     ...context.repo,
@@ -51,7 +50,6 @@
     .sort((a, b) => Date.parse(b.published_at) - Date.parse(a.published_at))[0];
 }
 
-// Runs after the workflow acquires the nightly concurrency lock.
 async function shouldReleaseNightly({ github, context, core, now = Date.now() }) {
   const lastNightly = await findLatestNightly({ github, context });
 
@@ -81,9 +79,6 @@
   return true;
 }
 
-// Stable releases build the commit the latest nightly shipped, so the stable
-// build is one nightly users already ran. Returns the nightly tag, its commit,
-// and the stable version that nightly was a preview of.
 async function resolveLatestNightlyCommit({ github, context, core }) {
   const lastNightly = await findLatestNightly({ github, context });
   if (!lastNightly) {
@@ -91,7 +86,6 @@
   }
 
   const tag = lastNightly.tag_name;
-  // repos.getCommit dereferences annotated tags, so this is the commit either way.
   const { data: commit } = await github.rest.repos.getCommit({ ...context.repo, ref: tag });
   const version = /^(?:nightly-)?v(\d+\.\d+\.\d+)-nightly\./.exec(tag)?.[1];
   if (!version) {
```

## \.github/scripts/mirror-play-apk.cjs

Status: modified; +0; −1

```diff
@@ -18,7 +18,6 @@
   return value;
 }
 
-// Service account key -> OAuth access token via a self-signed JWT grant.
 async function playAccessToken(key) {
   const now = Math.floor(Date.now() / 1000);
   const encode = (value) => Buffer.from(JSON.stringify(value)).toString("base64url");
```

## AGENTS.md

Status: modified; +1; −1

```diff
@@ -154,7 +154,7 @@
 - Server features are services; transports stay thin. A `ws.ts` RPC handler, HTTP route, or MCP tool decodes input, calls one service method, and maps errors. See [Effect services](docs/internals/effect-services.md).
 - `apps/web/src/components/ui` exports own their look. Pick a `variant` or `size`; do not restyle one with `className`. If none fits and the look is a generic concept, add a variant to the component; a look that belongs to one feature stays in that feature's own component, not in `components/ui`. Layout classes (width, flex, margin, position) belong on the parent. `shadcn/no-restyle` fails lint on violations. See [Web UI](docs/internals/web-ui.md).
 - Inferred types over annotations. `any` is the enemy.
-- Comments describe how a thing is used, and move when the code moves. To be used mostly to describe functions, not to annotate every line of behavior.
+- Comments say why: a constraint, an external quirk, or an invariant the code can't show. Don't restate names or signatures, narrate steps, or record history. `t3code/no-low-value-comments` catches the mechanical cases.
 - Our users drive agents all day and notice a dropped frame, a lying spinner, and a stale label. No continuously repainting animations; they peg the GPU on high-refresh displays.
 - If a rule here fights the task in front of you, say so loudly and get a human sign-off before breaking it.
 
```

## apps/desktop/gnome-extension/captureFeedback.js

Status: modified; +0; −2

```diff
@@ -6,7 +6,6 @@
 import * as Main from "resource:///org/gnome/shell/ui/main.js";
 import { captureDestinationFrame, findCaptureDestination } from "./feedbackGeometry.js";
 
-/** A single, bounded, sender-owned flight. No live window clone or per-frame JS work. */
 export class CaptureFeedback {
   begin(sender, pid, snapshot, options) {
     this.dispose();
@@ -54,7 +53,6 @@
         });
       }
     } catch (error) {
-      // Optional decoration must not prevent attaching a successfully captured image.
       this._clearActors();
       console.warn(`T3 capture effects unavailable: ${error.message}`);
     }
```

## apps/desktop/gnome-extension/captureService.js

Status: modified; +0; −1

```diff
@@ -1,4 +1,3 @@
-// This policy is independent of Shell so lifecycle and authorization can be tested without a desktop.
 export const CLIENT_NAMES = [
   "com.t3tools.T3Code.SnapShot",
   "com.t3tools.T3Code.Development.SnapShot",
```

## apps/desktop/scripts/build-browser-secret.mjs

Status: modified; +1; −3

```diff
@@ -31,9 +31,7 @@
           NodeFS.statSync(source).mtimeMs,
           NodeFS.statSync(NodeURL.fileURLToPath(import.meta.url)).mtimeMs,
         ) && matchesArchitecture(output);
-  } catch {
-    /* The first build has no output yet. */
-  }
+  } catch {}
   if (!current) {
     let flags;
     try {
```

## apps/desktop/scripts/dev-electron.mjs

Status: modified; +0; −1

```diff
@@ -225,7 +225,6 @@
     return;
   }
 
-  // Kill direct children as a final fallback in case normal shutdown leaves stragglers.
   NodeChildProcess.spawnSync("pkill", [`-${signal}`, "-P", String(process.pid)], {
     stdio: "ignore",
   });
```

## apps/desktop/scripts/electron-launcher.mjs

Status: modified; +4; −7

```diff
@@ -1,5 +1,3 @@
-// This file mostly exists because we want dev mode to say "T3 Code (Dev)" instead of "electron"
-
 import * as NodeChildProcess from "node:child_process";
 import * as NodeFS from "node:fs";
 import * as NodeModule from "node:module";
@@ -402,11 +400,10 @@
   );
   patchHelperBundleInfoPlists(targetAppBundlePath);
   if (isDevelopment) {
+    // Launching the node_modules copy makes macOS associate the process (and Dock label) with
+    // Electron.app even though this bundle's Info.plist has the T3 Code name. Its conventional
+    // executable name also keeps Electron's default-app runtime in development mode instead of
+    // making app.isPackaged report true.
-    // Keep Electron's native executable inside the branded bundle. Launching the
-    // node_modules copy makes macOS associate the process (and Dock label) with
-    // Electron.app even though this bundle's Info.plist has the T3 Code name.
-    // Its conventional executable name also keeps Electron's default-app runtime
-    // in development mode instead of making app.isPackaged report true.
     writeDevelopmentEnvironmentScript();
     writeDevelopmentLauncherScript(launcherBinaryPath, runtimeElectronBinaryPath);
   }
```

## apps/desktop/scripts/electron-launcher.test.mjs

Status: modified; +0; −1

```diff
@@ -145,7 +145,6 @@
     const development = resolveMacLauncherIconPaths("/runtime", true);
     const production = resolveMacLauncherIconPaths("/runtime", false);
 
-    // The source icons are real repo paths, joined for the host.
     assert.match(development.sourceIconPath, /assets[\\/]dev[\\/]blueprint-macos-1024\.png$/);
     assert.equal(development.generatedIconPath, "/runtime/icon-dev.icns");
     assert.match(production.sourceIconPath, /assets[\\/]prod[\\/]black-macos-1024\.png$/);
```

## apps/desktop/src/app/DesktopApp.ts

Status: modified; +0; −13

```diff
@@ -149,8 +149,6 @@
 
 export const stopAllPoolInstances = Effect.fn("desktop.app.stopAllPoolInstances")(
   function* (): Effect.fn.Return<void, never, DesktopBackendPool.DesktopBackendPool> {
-    // Stop every backend in the pool with a timeout to guarantee the quit
-    // path makes progress even if a backend hangs during teardown.
     const pool = yield* DesktopBackendPool.DesktopBackendPool;
     const instances = yield* pool.list;
     yield* Effect.forEach(
@@ -171,8 +169,6 @@
   yield* logBootstrapInfo("bootstrap start");
 
   const settings = yield* desktopSettings.get;
-  // The renderer is served from the bundled client (or Vite in development)
-  // rather than through the local backend, so the window can open without one.
   const electronProtocol = yield* ElectronProtocol.ElectronProtocol;
   yield* electronProtocol.registerDesktopProtocol({
     scheme: ElectronProtocol.getDesktopScheme(environment.isDevelopment),
@@ -243,11 +239,6 @@
   }
 
   if (!(yield* Ref.get(state.quitting))) {
-    // The main window waits for the primary backend. In wsl-only mode that is
-    // the WSL backend, which can be slow to cold-boot — show a "Connecting to
-    // WSL" splash immediately so the app feels responsive instead of presenting
-    // no window until WSL is ready. (Dual mode opens fast off the Windows
-    // primary, so no splash there.)
     if (settings.wslOnly === true && settings.wslBackendEnabled === true) {
       yield* desktopWindow.showConnectingSplash;
     }
@@ -257,10 +248,6 @@
       Effect.tap(() => logBootstrapInfo("desktop app control socket ready")),
       Effect.catch((error) => logStartupError("desktop app control socket unavailable", { error })),
     );
-    // Bring up the WSL backend if the user previously enabled it. The
-    // primary is already starting; reconcile fires off the WSL register
-    // in parallel rather than blocking primary readiness on a possibly
-    // slow first wsl.exe spawn.
     yield* Effect.forkScoped(wslBackend.reconcile);
   }
 }).pipe(Effect.withSpan("desktop.bootstrap"));
```

## apps/desktop/src/app/DesktopAppActivation.test.ts

Status: modified; +0; −1

```diff
@@ -159,7 +159,6 @@
     }),
   );
 
-  // Two desktop apps can share one state dir, such as nightly and a preview build.
   it.effect("keeps a newer app's socket when an older app on the same state dir quits", () =>
     Effect.gen(function* () {
       const platform = yield* HostProcess.Platform;
```

## apps/desktop/src/app/DesktopAppActivation.ts

Status: modified; +3; −17

```diff
@@ -47,7 +47,6 @@
 }
 
 interface RunningControlServer {
-  /** Binds the address again if its socket file is gone. Directory changes run this too. */
   readonly reclaim: () => Promise<void>;
   readonly close: () => Promise<void>;
 }
@@ -75,7 +74,6 @@
   return "invalid-request";
 }
 
-/** Makes sure the socket directory is safe to use. Returns true when it had to create it. */
 async function prepareUnixDirectory(input: {
   readonly directory: string;
   readonly userId: number | undefined;
@@ -106,16 +104,6 @@
   return new Promise((resolve) => server.close(() => resolve()));
 }
 
-/**
- * Serves `t3 app` requests on the local control address until `close`.
- *
- * Two desktop apps can share one state dir, for example nightly and a preview
- * build. They share one socket path, so on Unix:
- * - The newest app takes the path over.
- * - `close` removes the socket file only while it is still this app's socket.
- * - An app binds the path again when it is gone, for example after the app that
- *   took it over quits.
- */
 export async function startDesktopAppControlServer(input: {
   readonly address: string;
   readonly directory: string | null;
@@ -201,8 +189,8 @@
   // Closing a Unix socket server unlinks the path it was bound to, even when
   // another app's socket lives there now. Bind a staging path and move it onto
   // the address instead, so a later close only unlinks the staging path, which
+  // is already gone.
-  // is already gone. `rename` takes the address over in one step. `link` claims
-  // it only while it is free, and fails with EEXIST otherwise.
+
   const bindUnix = async (directory: string, mode: "take-over" | "claim-free") => {
     const staging = NodePath.join(directory, `${NodeCrypto.randomBytes(6).toString("hex")}.tmp`);
     const server = await listen(staging);
@@ -242,7 +230,6 @@
     }
     const next = await bindUnix(input.directory, "claim-free").catch(
       (error: NodeJS.ErrnoException) => {
-        // Another app bound the address first.
         if (error.code === "EEXIST") return null;
         throw error;
       },
@@ -268,7 +255,6 @@
       });
       watcher.on("error", input.onReclaimError);
     } catch (error) {
-      // The socket still works without a watcher. It only cannot recover after removal.
       input.onReclaimError(error);
     }
   };
@@ -309,7 +295,7 @@
 
 const { logWarning } = makeComponentLogger("desktop-app-activation");
 
-/** @public Service construction is part of the canonical Effect module API. */
+/** @public */
 export const make = Effect.gen(function* () {
   const desktopEnvironment = yield* DesktopEnvironment.DesktopEnvironment;
   const desktopWindow = yield* DesktopWindow.DesktopWindow;
```

## apps/desktop/src/app/DesktopAppActivationBroker.ts

Status: modified; +0; −1

```diff
@@ -29,7 +29,6 @@
   };
 }
 
-/** Holds CLI requests until the real desktop renderer is ready to handle them. */
 export class DesktopAppActivationBroker {
   readonly #pending = new Map<string, PendingActivation>();
   readonly #requestTimeoutMs: number;
```

## apps/desktop/src/app/DesktopAppIdentity.test.ts

Status: modified; +0; −5

```diff
@@ -221,8 +221,6 @@
         assert.equal(calls.setAboutPanelOptions[0]?.applicationName, "T3 Code (Beta)");
         assert.equal(calls.setAboutPanelOptions[0]?.applicationVersion, "1.2.3");
         assert.equal(calls.setAboutPanelOptions[0]?.version, "0123456789ab");
-        // Packaged: the bundle's own icon stands, so a custom one the user
-        // attached survives.
         assert.deepEqual(calls.setDockIcon, []);
       }),
       {
@@ -262,7 +260,6 @@
         const runtimeName = calls.setName[0];
         assert.isDefined(runtimeName);
         assert.equal(runtimeName, `T3 Code ${stage}`);
-        // RFC 9110's token grammar, after Electron removes ASCII spaces.
         assert.match(runtimeName.replaceAll(" ", ""), /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/);
         assert.equal(calls.setAboutPanelOptions[0]?.applicationName, `T3 Code (${stage})`);
       }),
@@ -282,8 +279,6 @@
         const identity = yield* DesktopAppIdentity.DesktopAppIdentity;
         yield* identity.configure;
 
-        // Electron shows a generic icon for an unpackaged run, which is the
-        // reason this call exists at all.
         assert.deepEqual(calls.setDockIcon, ["/icon.png"]);
       }),
       {
```

## apps/desktop/src/app/DesktopAssets.ts

Status: modified; +1; −1

```diff
@@ -119,7 +119,7 @@
   return yield* resolveResourcePath(`icon.${ext}`);
 });
 
-/** @public Service construction is part of the canonical Effect module API. */
+/** @public */
 export const make = Effect.gen(function* () {
   const context = yield* Effect.context<
     FileSystem.FileSystem | DesktopEnvironment.DesktopEnvironment
```

## apps/desktop/src/app/DesktopClerk.test.ts

Status: modified; +0; −6

```diff
@@ -39,7 +39,6 @@
 import * as DesktopEnvironment from "./DesktopEnvironment.ts";
 import * as DesktopPreReadyFileSystem from "./DesktopPreReadyFileSystem.ts";
 
-/** Clerk forwards web links; tests that are not about links ignore them. */
 const ignoreWebLinks = DesktopWebLinks.DesktopWebLinks.of({
   receive: () => Effect.void,
   setRendererReady: () => Effect.void,
@@ -144,8 +143,6 @@
         events.push("createClerkBridge");
         return { cleanup: vi.fn(), isPrimaryInstance: true };
       });
-      // runSync throws if the layer ever suspends, which would let Electron emit
-      // ready before the bridge exists. main.ts provides the same FileSystem.
       // oxlint-disable-next-line t3code/no-manual-effect-runtime-in-tests -- The assertion IS that the layer builds synchronously; it.effect would mask a regression to async.
       Effect.runSync(
         Effect.scoped(
@@ -417,13 +414,10 @@
         listeners.get("open-url")!(event, url);
         return event.preventDefault.mock.calls.length;
       };
-      // macOS hands the default browser every web link.
       assert.strictEqual(open("https://example.com/page"), 1);
       assert.strictEqual(open("http://localhost:3000/"), 1);
-      // Prompt and thread links ride the same queue; the renderer routes them in the app.
       assert.strictEqual(open("t3code://new?prompt=hi"), 1);
       assert.strictEqual(open("t3code://threads/env-1/thread-1"), 1);
-      // Anything else is not a web page; Electron keeps its own handling.
       assert.strictEqual(open("mailto:hello@example.com"), 0);
       assert.strictEqual(open("t3code://somewhere-else"), 0);
       yield* Effect.yieldNow;
```

## apps/desktop/src/app/DesktopClerk.ts

Status: modified; +0; −5

```diff
@@ -100,7 +100,6 @@
   const electronApp = yield* ElectronApp.ElectronApp;
   const shell = yield* ElectronShell.ElectronShell;
 
-  // The SDK bridge acquires Electron's profile-scoped single-instance lock.
   // Must not yield: the bridge registers a scheme Electron rejects once ready.
   const userDataPath = yield* DesktopUserData.resolveUserDataPath(environment);
   yield* electronApp.setPath("userData", userDataPath);
@@ -189,8 +188,6 @@
         );
         return true;
       };
-      // Prompt links and thread links (`t3code://new?…`, `t3code://threads/…`) reach the
-      // renderer through the same queue as web links; it routes them in the app.
       const openAppLink = (value: string | undefined) => {
         if (!value || promptLinkAppPath(value) === null) return false;
         void runPromise(webLinks.receive(value));
@@ -198,7 +195,6 @@
       };
       const args = yield* HostProcess.Arguments;
       args.some((value) => startProviderAuthHandoff(value) || openAppLink(value));
-      // As the default browser, macOS hands T3 Code every web link through the same event.
       const openWebLink = (url: string) => {
         if (!DesktopWebLinks.isWebLink(url)) return false;
         void runPromise(webLinks.receive(url));
@@ -213,7 +209,6 @@
         )
           event.preventDefault();
       });
-      // A browser opens HTML files too, which macOS hands over by path.
       yield* electronApp.on("open-file", (event: { preventDefault: () => void }, path: string) => {
         if (!DesktopWebLinks.isWebPageFile(path)) return;
         event.preventDefault();
```

## apps/desktop/src/app/DesktopCliCommand.test.ts

Status: modified; +0; −8

```diff
@@ -27,7 +27,6 @@
     appImagePath: Option.none(),
   } as unknown as DesktopEnvironment.DesktopEnvironment["Service"]);
 
-/** The service for a packaged app; the launcher is written on Install. */
 const commandIn = (
   input: { home: string; baseDir?: string; platform?: NodeJS.Platform; isPackaged?: boolean },
   spawner?: ChildProcessSpawner.ChildProcessSpawner["Service"],
@@ -48,7 +47,6 @@
       : make;
   });
 
-/** A PowerShell that keeps the user's PATH in memory and can be told to fail reads. */
 const fakePowerShell = (initial: string) => {
   const registry = { path: initial, failReads: false, writes: 0 };
   const spawner = ChildProcessSpawner.make((command) =>
@@ -104,7 +102,6 @@
       const link = path.join(home, ".local", "bin", "t3");
 
       expect(yield* command.state).toEqual({ supported: true, installedPath: null, onPath: false });
-      // Install writes the launcher itself, even when no local backend ever did.
       const installed = yield* command.install;
       expect(installed.installedPath).toBe(link);
       expect(yield* fs.readLink(link)).toBe(path.join(home, ".t3", "bin", "t3"));
@@ -112,7 +109,6 @@
 
       expect((yield* command.uninstall).installedPath).toBeNull();
       expect(yield* fs.exists(link)).toBe(false);
-      // The launcher itself stays for setup commands.
       expect(yield* fs.exists(path.join(home, ".t3", "bin", "t3"))).toBe(true);
     }).pipe(Effect.scoped),
   );
@@ -126,7 +122,6 @@
       const theirs = path.join(home, ".local", "bin", "t3");
       yield* fs.makeDirectory(path.dirname(theirs), { recursive: true });
       yield* fs.writeFileString(theirs, "npm's t3\n");
-      // Even a broken link in the next folder is someone else's.
       yield* fs.makeDirectory(path.join(home, "bin"), { recursive: true });
       yield* fs.symlink(path.join(home, "gone"), path.join(home, "bin", "t3"));
 
@@ -148,7 +143,6 @@
 
       const after = yield* commandIn({ home, baseDir: path.join(home, "new-t3") });
       expect((yield* after.state).installedPath).toBe(link);
-      // Installing again points the link at this home's launcher.
       expect((yield* after.install).installedPath).toBe(link);
       expect(yield* fs.readLink(link!)).toBe(path.join(home, "new-t3", "bin", "t3"));
       yield* after.uninstall;
@@ -162,7 +156,6 @@
       const fs = yield* FileSystem.FileSystem;
       const path = yield* Path.Path;
       const home = yield* fs.makeTempDirectoryScoped();
-      // A big executable that happens to contain the marker text is still not ours.
       const binary = path.join(home, "native-t3");
       yield* fs.writeFileString(binary, `${"\0".repeat(64 * 1024)}${DesktopCliShim.MARKER}`);
       yield* fs.makeDirectory(path.join(home, ".local", "bin"), { recursive: true });
@@ -187,7 +180,6 @@
       const command = yield* commandIn({ home });
       const theirs = path.join(shadow, "t3");
       expect((yield* command.state).shadowedBy).toBe(theirs);
-      // A link behind it would never run, so nothing is created.
       const error = yield* Effect.flip(command.install);
       expect(error.message).toContain(theirs);
       expect(yield* fs.exists(path.join(home, ".local", "bin", "t3"))).toBe(false);
```

## apps/desktop/src/app/DesktopCliCommand.ts

Status: modified; +0; −25

```diff
@@ -12,19 +12,11 @@
 import * as DesktopCliShim from "./DesktopCliShim.ts";
 import * as DesktopEnvironment from "./DesktopEnvironment.ts";
 
-// Settings → Install `t3` command, like VS Code's "Install 'code' command".
-// The app's launcher (see DesktopCliShim) lives in the T3 home and is off PATH
-// by default. Installing links it into a folder on the user's PATH, or on
-// Windows adds the launcher's folder to the user's PATH. Removing undoes only
-// what installing did: a link that points at one of the app's launchers, or a
-// PATH entry the app recorded adding.
-
 export class DesktopCliCommandError extends Schema.TaggedError<DesktopCliCommandError>()(
   "DesktopCliCommandError",
   { message: Schema.String },
 ) {}
 
-/** User-writable folders that login shells commonly put on PATH, in preference order. */
 const unixCandidates = (home: string, platform: NodeJS.Platform) =>
   platform === "darwin"
     ? ["/opt/homebrew/bin", "/usr/local/bin", `${home}/.local/bin`, `${home}/bin`]
@@ -33,7 +25,6 @@
 const pathEntries = (value: string | undefined, separator: string) =>
   (value ?? "").split(separator).filter((entry) => entry.length > 0);
 
-/** Windows paths compare without case or a trailing separator. */
 const sameWindowsPath = (left: string, right: string) =>
   left.replace(/[\\/]+$/, "").toLowerCase() === right.replace(/[\\/]+$/, "").toLowerCase();
 
@@ -82,7 +73,6 @@
   const windows = environment.platform === "win32";
   const launcher = DesktopCliShim.launcherPath(environment);
   const binDirectory = path.dirname(launcher);
-  /** Records that Install added `binDirectory` to the Windows PATH, so Remove takes out only that. */
   const ownedPathMarker = path.join(environment.stateDir, "cli-command-path-entry");
 
   const fail = (message: string) => new DesktopCliCommandError({ message });
@@ -93,11 +83,6 @@
       Effect.orElseSucceed(() => false),
     );
 
-  /**
-   * A link to one of the app's launchers, by the marker the launcher carries.
-   * This also finds links made under a previous T3 home, so Remove can clean
-   * them up and Install does not add a second.
-   */
   const isOurLink = (link: string) =>
     Effect.gen(function* () {
       yield* fs.readLink(link);
@@ -137,7 +122,6 @@
       Effect.mapError(() => fail("Could not update your PATH.")),
     );
 
-  /** The `t3` a new shell runs, by PATH order, or none. */
   const firstOnPath = Effect.gen(function* () {
     for (const directory of pathEntries(process.env.PATH, ":")) {
       const candidate = path.join(directory, "t3");
@@ -146,7 +130,6 @@
     return Option.none<string>();
   });
 
-  /** The `t3` a new shell runs when it is not this app's, on Unix. */
   const foreignFirstOnPath = Effect.gen(function* () {
     if (windows) return Option.none<string>();
     const first = yield* firstOnPath;
@@ -154,7 +137,6 @@
     return first;
   });
 
-  /** Where this app's command is installed now, if anywhere. */
   const installedAt = Effect.gen(function* () {
     if (windows) {
       if (!(yield* exists(ownedPathMarker))) return Option.none<string>();
@@ -180,14 +162,11 @@
     if (Option.isNone(installed)) {
       return { supported: true, installedPath: null, onPath: false, ...shadow };
     }
-    // On Windows only terminals opened after the change see it. On Unix the
-    // first `t3` on PATH must be ours; a `t3` earlier on PATH would shadow it.
     const first = yield* firstOnPath;
     const onPath = windows || (Option.isSome(first) && (yield* isOurLink(first.value)));
     return { supported: true, installedPath: installed.value, onPath, ...shadow };
   }).pipe(Effect.orElseSucceed(() => ({ supported: false, installedPath: null, onPath: false })));
 
-  /** Writes the launcher if the app has not yet, e.g. when no local backend runs. */
   const ensureLauncher = DesktopCliShim.install.pipe(
     Effect.provideService(DesktopEnvironment.DesktopEnvironment, environment),
     Effect.provideService(FileSystem.FileSystem, fs),
@@ -216,12 +195,10 @@
     if (Option.isSome(existing)) {
       const target = yield* fs.readLink(existing.value).pipe(Effect.option);
       if (Option.getOrUndefined(target) === launcher) return yield* state;
-      // A link to a previous T3 home's launcher: point it at this one instead.
       yield* fs
         .remove(existing.value)
         .pipe(Effect.mapError(() => fail(`Could not replace ${existing.value}.`)));
     }
-    // A link behind another `t3` never runs, so installing one would only hide the problem.
     const shadowedBy = yield* foreignFirstOnPath;
     if (Option.isSome(shadowedBy)) {
       return yield* fail(
@@ -230,7 +207,6 @@
     }
     const onPath = pathEntries(process.env.PATH, ":");
     const candidates = unixCandidates(environment.homeDirectory, environment.platform);
-    // Prefer a folder already on PATH that the user can write to without admin rights.
     for (const directory of [
       ...candidates.filter((candidate) => onPath.includes(candidate)),
       ...candidates.filter((candidate) => !onPath.includes(candidate)),
@@ -243,7 +219,6 @@
             Effect.orElseSucceed(() => false),
           );
       if (!created) continue;
-      // symlink fails if anything, even a broken link, is already there.
       const linked = yield* fs.symlink(launcher, link).pipe(
         Effect.as(true),
         Effect.orElseSucceed(() => false),
```

[Next page](https://git.cafe/pingdotgg/t3code/pull/19559/diffs?after=ImFwcHMvZGVza3RvcC9zcmMvYXBwL0Rlc2t0b3BDbGlDb21tYW5kLnRzIg&expectedVersion=4&format=markdown)