feat(desktop): open thread deep links via t3code://

[saphid]

Model: Claude Opus 5.5, with a later maintenance pass by GPT-6 Astra. Rebased onto current main with Claude Opus 5.5 on 2026-10-12.

1. Problem and reproduction

External tools and the app's own agent-awareness links cannot open a specific desktop thread. Open t3code://threads/<environmentId>/<threadId> while the desktop app is closed or already running; this PR routes the desktop renderer to that thread.

2. Cause

Scheme registration already exists on main, but thread links need main-process dispatch, buffering until a renderer subscribes, and navigation that is not overwritten by the index route's draft creation.

3. What changed

DesktopDeepLink accepts the threads and app hosts, a UUID environment ID, and one encoded thread-ID segment (including imported IDs). It handles early macOS open-url, cold-start argv, and second-instance argv. The newest link stays buffered until its subscribed renderer acknowledges the matching generation. Unsubscribe, stale replies, and renderer destruction preserve delivery to a subsequent subscriber. A root route listener navigates, and the index route reads the live path before starting a draft.

Merged main 7445aa733ada33e45289e5aa5055f79142556513 into the branch rather than rebasing to preserve existing review history. The channel conflict retains upstream's paste-as-text channel alongside the four deep-link channels. The deep-link sender shape now lives at its own boundary; the shared IPC event and existing IPC/snapshot tests are identical to main. The preload regression supplies the window mock needed by upstream's macOS inset handling.

4. Scope and exclusions

This remains desktop thread-link handling. It does not change OAuth callbacks, upstream paste-as-text, notification badges, protocol registration, provider adapters, or mobile navigation. The shared bridge hook is optional for older desktop clients. No unrelated formatting or generated files are added to the contribution.

5. Affected surfaces

Desktop OS URL dispatch and desktop-rendered web routing, including navigation from other screens and cold-start draft prevention. The IPC bridge contract is additive. Browser-only web and both mobile clients retain their existing behavior. Links select an environment; local/remote connectivity still uses existing environment handling. Windows/Linux argv paths have unit coverage, not real-client execution here.

6. Verification

Exact head: b06456ca725c11ade0e41d59748612604a22c5c5 (20 September 2026).

From apps/desktop:

vp test run src/app/DesktopDeepLink.test.ts src/ipc/DesktopIpc.test.ts src/ipc/methods/snapShot.test.ts src/app/DesktopLifecycle.test.ts src/window/DesktopWindow.test.ts src/ssh/DesktopSshPasswordPrompts.test.ts src/ipc/methods/window.test.ts src/window/DesktopApplicationMenu.test.ts src/ipc/methods/notificationBadge.test.ts

9 files, 111 tests passed, exit 0. Includes real-preload/IPC remount sequencing, ID-only sender rejection without consuming the buffered link, and upstream paste-as-text and notification-badge tests.

From the repository root:

• vp run --filter @t3tools/desktop typecheck: exit 0.
• vp run --filter @t3tools/web typecheck: exit 0 when run alone. The initial concurrent invocation exited 137 for web; the isolated retry passed.
• vp run --filter @t3tools/desktop --filter @t3tools/web --filter @t3tools/contracts typecheck: contracts passed; the initial desktop failures exposed the IPC compatibility issue fixed above. Final desktop and web results are the separate commands above.
• git diff --name-only origin/main HEAD supplied the 15 final contribution paths to vp fmt --check; exit 0. Its 14 TypeScript paths supplied vp lint; exit 0 with three warnings on unchanged upstream route lines (two effect dependency warnings and one render-ref warning).
• git diff origin/main HEAD --check: exit 0.

The first test attempt exposed the stale preload harness and a concurrent Electron runtime installation race. After adapting our harness and running node apps/desktop/scripts/ensure-electron-runtime.mjs, all selected suites passed. Commit hooks left the tested source tree unchanged.

7. Known gaps and risks

Not review-ready: current-head visual proof remains outstanding. No browser, desktop GUI, remote/relay/tunnel session, Windows/Linux client, or SwiftUI simulator build was exercised in this maintenance pass. Fresh light/dark before/after captures and cold/warm interaction video belong to the proof follow-up. Historical recordings below do not certify this head. CI on the pushed head must be evaluated separately; prior green checks or the earlier Release Smoke failure are not current-head results.

No fresh independent reviewer or visual inspector ran in this no-delegation pass. No review was re-requested.

8. Historical media — not current-head proof

These artifacts were recorded on an earlier revision. The cold-link comparison is a two-frame GIF, not a continuous interaction recording.

Historical warm-link recording · Historical annotated recording

9. Related work

Consumes thread links emitted by #9745. Maintenance tracking: saphid/t3code-personal#151; current-head capture follow-up: #150.

This maintenance pass: GPT-6 Astra in the Codex harness. Earlier implementation attribution remains in the branch history.

[coderabbitai]

Important

Review skipped

We couldn't safely recover the incremental review. No full review was started, and the last reviewed checkpoint was preserved. Retry later, or explicitly request a full review by commenting @coderabbitai full review.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

📝 Walkthrough

📝 Walkthrough

Walkthrough

The desktop app adds distribution-aware identity, validated thread deep links, custom GitHub update sources, connection-catalog migration, and stable macOS ad hoc signing.

Changes

Desktop platform and deep-link flow

Layer / File(s)	Summary
Distribution identity and catalog isolation packages/shared/src/desktopBuild.ts, apps/desktop/src/app/DesktopEnvironment.ts, apps/desktop/src/app/DesktopAppIdentity.ts, apps/desktop/src/app/DesktopConnectionCatalogStore.ts	Packaged identities determine product names, profile paths, catalog paths, legacy migration, and downstream branding. Catalog operations are serialized.
Packaged metadata and protocol registration apps/desktop/src/electron/*, apps/desktop/src/app/DesktopPreReadyPlatform.ts, apps/desktop/src/app/DesktopLinuxUrlHandler.ts, apps/desktop/src/window/DesktopWindow.ts	Packaged metadata is read synchronously. Distribution-specific schemes, Linux identifiers, and renderer URLs use the resolved identity.
Desktop deep-link delivery apps/desktop/src/app/DesktopDeepLink.ts, apps/desktop/src/main.ts, apps/desktop/src/app/DesktopApp.ts, apps/desktop/src/preload.ts, apps/web/src/routes/*	Validated thread links are captured from OS events and cold-start arguments, buffered until subscription, delivered through IPC, acknowledged by generation, and routed to the requested environment and thread.

Custom desktop update sources

Layer / File(s)	Summary
Update repository contracts and persistence packages/contracts/src/ipc.ts, apps/desktop/src/settings/DesktopAppSettings.ts, apps/desktop/src/ipc/methods/updates.ts	Update state includes a normalized nullable repository. Repository changes are persisted and exposed through IPC.
Updater repository execution apps/desktop/src/updates/DesktopUpdates.ts, apps/desktop/src/electron/ElectronUpdater.ts	The updater supports custom feeds, repository-specific locking and errors, feed reset, and macOS bundle validation.
Web update settings and links apps/web/src/components/settings/SettingsPanels.tsx, apps/web/src/components/desktopUpdate.logic.ts, apps/web/src/components/sidebar/SidebarUpdateReleaseNotes.tsx	Web settings expose Stable, Nightly, and Custom tracks. Release links use the selected repository.

Desktop build and signing

Layer / File(s)	Summary
Build identity propagation scripts/build-desktop-artifact.ts, packages/shared/src/desktopBuild.ts, packages/shared/package.json	Builds derive validated distribution identities and propagate them to package metadata, platform artifacts, and protocol schemes.
Stable macOS ad hoc signing scripts/sign-macos.ts	Unsigned stable macOS builds validate an ad hoc bundle identifier and apply the configured signing requirements.

Priority: ⬇️ Low

Estimated code review effort: 5 (Critical) | ~120 minutes

Suggested reviewers: juliusmarminge, t3dotgg

Sequence Diagram(s)

sequenceDiagram
  participant OperatingSystem
  participant DesktopApp
  participant DesktopDeepLink
  participant PreloadBridge
  participant WebRouter
  OperatingSystem->>DesktopApp: open-url or second-instance URL
  DesktopApp->>DesktopDeepLink: configure before Electron readiness
  DesktopDeepLink->>PreloadBridge: send validated thread payload with generation
  PreloadBridge->>DesktopDeepLink: acknowledge delivered generation
  PreloadBridge->>WebRouter: invoke onDeepLink listener
  WebRouter->>WebRouter: navigate to environment/thread route

Loading

---

---

---

---

Merge Risk: 🟡 Moderate · up to c0367

Migrating catalogs can retain unreachable connection profiles and credentials. Filter dependent records against the retained targets before merge.

Pre-merge checks | 4 | 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 21.57% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 51 functions across 55 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.
Title check		The title clearly identifies the primary change: desktop support for opening thread deep links through t3code://.
Description check		The description is detailed and covers the problem, implementation, scope, affected surfaces, verification results, known gaps, and related work. It also records missing current-head visual and integr…

---

---

---

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

---

---

---

---

---

_{Comment @coderabbitai help to get the list of available commands.}

[macroscopeapp]

Effect service conventions review: two findings in apps/desktop/src/app/DesktopDeepLink.ts, both about inputs to the service that never appear in the Effect environment. The service shape, make/layer naming, dependency acquisition via yield* Foo.Foo, and the native-callback runPromiseWith bridge all match the existing DesktopClerk/DesktopWindow patterns.

^{Posted via Macroscope — Effect Service Conventions}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit ddae088e7a678c890a16e6f1936ab6d37a169366. Configure here.}

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR introduces a cross-platform desktop deep-link workflow spanning OS dispatch, main/preload IPC buffering, window focusing, and renderer navigation, along with a guard that changes index draft behavior. It also adds a static-analysis suppression in the test suite, so the scope and diagnostic override require human review.

^{You can add or adjust custom eligibility rules. Learn more.}

[macroscopeapp]

Effect service conventions: the two earlier findings (ambient process.argv, module-global early capture) are addressed — HostProcessArguments and the EarlyOpenUrlCapture reference are both injected now. One remaining item, on the new requeue channel.

^{Posted via Macroscope — Effect Service Conventions}

[cursor]

Bugbot is paused — on-demand spend limit reached

Bugbot uses usage-based billing for this team and has hit its on-demand spend limit.

A team admin can raise the spend limit in the Cursor dashboard, or wait for the next billing cycle to continue.

[cursor]

Bugbot is paused — on-demand spend limit reached

Bugbot uses usage-based billing for this team and has hit its on-demand spend limit.

A team admin can raise the spend limit in the Cursor dashboard, or wait for the next billing cycle to continue.

[macroscopeapp]

All clear

^{Posted via Macroscope — Effect Service Conventions}

[t3-code]

reviewed 03fb83e59de393240f9ce45a3a4b6bfbd4234dc9. no new standalone code blocker found.

all 27 DesktopDeepLink tests passed. standalone desktop typecheck reported TS2883 in updatesTestHarness.ts; the same errors reproduce on base 8b2838e0e8a73d3fa6476940445c372e47b99db4.

the documented #8976 integration step is still required. current heads conflict in DesktopClerk.ts and DesktopClerk.test.ts. after retaining #8976's clerk side in a temporary combined tree, desktop typecheck reproduces TS2554 at apps/desktop/src/app/DesktopDeepLink.ts:147. pass environment.distributionId to getDesktopScheme, preserve the distribution-specific clerk behavior, and rerun downstream cold/warm-link verification on the final resolved head. existing evidence for a different combined commit does not certify this current pair.

required checks are successful or skipped; github reports a clean individual merge into main. no fresh packaged macos/linux os-link run was performed here. leaving a comment pending integration, not requesting changes to the standalone one-argument call before its dependency lands.

[coderabbitai]

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.

[genr8r]

Testing note, in case it saves a reviewer some time.

On a machine with the released build installed, /Applications/T3 Code (Alpha).app declares both t3code: and t3code-dev: in its CFBundleURLSchemes. LaunchServices therefore routes t3code-dev:// URLs to the release build, which has no deep link handler, so someone testing this branch sees nothing happen and may conclude the feature is broken.

Dispatching at the dev bundle explicitly avoids it:

open -a "apps/desktop/.electron-runtime/T3 Code (Dev).app" \
  "t3code-dev://app/<environmentId>/<threadId>"

What I verified on macOS 26.6 (Apple silicon), branch at 367240d9:

• pnpm install completes cleanly (43s).
• apps/desktop/src/app/DesktopDeepLink.test.ts passes 28/28.
• The wiring comes up at startup: the desktop:deep-link:{subscribe,unsubscribe,ack,requeue} IPC channels register and desktop.deepLink.configure completes.

I did not get as far as confirming navigation end to end. My dev profile was still on the onboarding wizard with no threads yet, which I take to be the queue-until-acknowledged path described in the PR body rather than a failure. Flagging the LaunchServices behaviour mainly because it is easy to mistake for one.

[shivamhwp]

Note: GPT-6 on behalf of shivam (@shivamhwp).

Send the unsubscribe request during listener cleanup, before a replacement listener subscribes. The current subscribed.finally(...) lets an old delayed reply unregister the replacement listener on the same webContents. A subscription-specific token would also let the main process reject stale cleanup.

Accept the existing t3code://threads/<environmentId>/<threadId> shape alongside the new t3code://app/... shape. Shared agent awareness produces /threads/..., and the mobile widget turns it into t3code://threads/...; the current parser rejects that emitted URL. This leaves #9745 only partly addressed. Its legacy primary alias also needs an explicit compatibility decision.

Cover the remount with the real preload and main subscription handlers, using gates for the delayed reply and an awaited delivery operation. The two nested setImmediate calls in settleDelivery do not establish that the delivery fiber finished.

[genr8r]

Corroborating the second point, since it decides whether this closes #9745.

The /threads/... shape is not hypothetical, it is what the app emits today:

• packages/shared/src/agentAwareness.ts:50 returns `/threads/${environmentId}/${threadId}`, shipped as deepLink on the agent awareness state (line 73).
• apps/mobile/src/widgets/AgentActivity.test.ts asserts widgetURL: "t3code://threads/env-1/thread-2".
• The repro in [Bug]: Desktop ignores t3code://threads/… deep links the app itself generates (#4996 closed as completed, never merged) #9745 is open "t3code://threads/primary/<THREAD_ID>".

parseThreadDeepLink requires host app plus two UUIDs, so all three are rejected. As written, this PR handles a URL shape nothing currently produces, while the links the app and mobile already generate keep doing nothing. Accepting threads alongside app closes that, and it has the side benefit of keeping deep links off the host that doubles as the renderer origin in DESKTOP_RENDERER_ORIGINS.

The primary alias needs its own explicit call. It is not a UUID, so the exact repro in #9745 still fails even once the host is accepted. Either resolve primary to the default environment id ahead of the UUID check, or state that the alias is out of scope and the fix covers UUID environment ids only.

On the unsubscribe ordering: agreed, and it is reachable on an ordinary remount rather than a rare race. Cleanup and the replacement mount run in the same commit, so the new SUBSCRIBE goes out synchronously while the previous subscribed.finally(...) unsubscribe lands a microtask later and removes the same webContents. subscribers is then empty with a listener mounted, so the next link takes the latestLiveSubscriber() === null branch and buffers indefinitely. A subscription-specific token makes the ordering irrelevant.

On coverage: worth noting apps/desktop/src has no preload.test.ts on main, so exercising the real preload here means new test infrastructure, not one more case in the existing file. Probably worth it, given the bug above is precisely what a main-handler-only harness cannot see.

[saphid]

Pushed ba7662532b addressing the three points from @shivamhwp's review and @genr8r's corroboration:

• Unsubscribe ordering. The preload no longer defers DEEP_LINK_UNSUBSCRIBE_CHANNEL behind the in-flight subscribe promise. Cleanup invokes it immediately, so on a setup → cleanup → setup replay the main process sees subscribe → unsubscribe → subscribe in send order and the replacement listener is never unregistered. A subscription token turned out to be unnecessary once cleanup cannot overtake a newer subscribe.
• t3code://threads/... accepted. The parser now accepts the threads host alongside app, matching what agent awareness emits and the mobile widget wraps. Decision on primary: rejected explicitly. Environment ids in emitted links are always server-generated UUIDs; primary is a local-backend bootstrap id, not an environment id, so accepting it would mean guessing. This is covered by a test and called out in docs/user/deep-links.md.
• Remount coverage with the real preload. New test imports the actual preload.ts bridge and drives it against the real IPC handlers with a gated subscribe reply — verifies the delayed reply cannot unregister the replacement, and that a stale buffered reply cannot navigate back over a newer push (per-subscription generation dedup in the preload).

An independent review (GPT-5.6 Sol, high) then caught one more real gap: the UUID-only thread segment rejected import:<provider>:<session> thread ids that AgentSessionImporter creates and agent awareness ships URI-encoded. The thread segment now accepts any single encoded segment that decodes to a non-empty string; the environment segment stays UUID-only.

On the earlier testing note from @genr8r: correct, LaunchServices routes t3code-dev:// to whichever installed bundle claims it, so dispatching at the dev bundle explicitly is the reliable way to test. That is a macOS scheme-registration quirk rather than something this PR can fix.

All 87 focused desktop tests pass; desktop/web/contracts typecheck clean.

[saphid]

Note on the Release Smoke failure: it fails at vp install --lockfile-only with ERR_PNPM_UNUSED_PATCH: expo-audio@57.0.4, and the identical failure is on other branches' CI runs right now (e.g. run 34692592725). The patch declaration and dependency are unchanged on this branch — pre-existing breakage on main, not from this PR.

[genr8r]

Two things on b06456c, one of which I think the last round of changes introduced.

The "already on this thread" short circuit misses imported thread ids.

apps/web/src/routes/__root.tsx:336:

if (readPathname() === `/${environmentId}/${threadId}`) {
  return;
}

threadId arrives decoded, since parseThreadDeepLink runs decodeURIComponent before the payload crosses IPC. useLocation().pathname is encoded. TanStack encodes named path params with encodeURIComponent (encodeParam in @tanstack/router-core, and this repo sets no pathParamsAllowedCharacters to undo it), so an imported thread renders as /<env>/import%3Aclaude%3A<session> while the comparison builds /<env>/import:claude:<session>. Those never match.

For UUID thread ids the two forms are identical, so the guard works. For the import:<provider>:<session> ids the thread segment was just widened to accept, it never fires, and a link to the thread you are already viewing re-navigates. docs/user/deep-links.md says "If you are already looking at the thread, nothing changes."

Comparing params rather than the rendered path sidesteps the encoding question:

const params = useParams({ strict: false });
if (params.environmentId === environmentId && params.threadId === threadId) {
  return;
}

Both changed web files are untested.

The desktop side gets 812 lines of new coverage. apps/web/src/routes/__root.tsx and apps/web/src/routes/_chat.index.tsx get none, and they are where the navigation, the guard above, and the index draft suppression actually live. The repo already has the pattern: apps/web/src/lib/assistantCitationNavigation.test.ts and apps/web/src/components/settings/settingsScopeNavigation.test.ts both build a router and assert where a navigation lands. A test in that shape would have caught the above.

Related and smaller: the index guard reads router.state.location.pathname === "/", which only sees a navigation that has committed. The subscribe handshake is an IPC round trip, so on a cold start the index effect can flush first, start the draft, and then have the deep link navigate over it. isTransitioning or pendingMatches would cover the in-flight window. If that residual race is understood and accepted, a comment saying so would save the next reader the trip.

Checked, and not worth anyone's time:

• Widening the thread segment to [^/?#]+ does not turn the scheme into an arbitrary-navigation primitive. Named params go through encodeURIComponent, no pathParamsAllowedCharacters override exists here to reverse it, and resolvePath returns an absolute to verbatim rather than collapsing ... The comment on parseThreadDeepLink is accurate as written.
• useEffectEvent is fine, apps/web is on React 19.2.6.
• Release Smoke is green on this head, so the earlier ERR_PNPM_UNUSED_PATCH note no longer has to stand on its own.

One merge note: the repro in #9745 is t3code://threads/primary/<THREAD_ID>. Rejecting primary is a defensible call, but it does mean that exact command still does nothing, so I would not close #9745 on this merge.

[juliusmarminge]

Note

This comment is posted by Julius' dot

The description says current-head visual proof is still outstanding and identifies the supplied cold/warm link media as historical. I inspected that media, but the linked capture follow-up in saphid/t3code-personal#150 returns 404 to this account, so I cannot establish whether newer proof exists. To complete the verification assessment, please attach accessible before/after screenshots and a short recording showing cold and warm thread navigation for the current implementation, or link existing evidence that reviewers can access.

[saphid]

Review requested

Date (UTC)	Reviewer	Where
2026-09-25	Maria	Discord DM

_{Logged so this PR shows when a maintainer was asked to review it.}

[saphid]

Review requested

Date (UTC)	Reviewer	Where
2026-10-06	Julius	Discord DM

_{Logged so this PR shows when a maintainer was asked to review it.}

[Goobles]

Current-head verification on macOS, for the evidence requested above.

Before is main at 17c0878, this PR's merge base. After is this head, 4d8139c. Both are dev desktop builds (vp run dev:desktop with T3CODE_BUNDLED_DEV=1) with the same isolated home and threads, on macOS 27.0 (Apple silicon). In the after clips, Playwright clicks a link on a local page in Chrome. For the before clips, I opened the same links with open -a "<path>/T3 Code (Dev).app" "t3code-dev://threads/<environmentId>/<threadId>".

Case	Before (main)	After (this head)
Warm: app running, link to another thread	Window comes to the front, thread doesn't change	Opens the linked thread
Cold: app quit, the link launches it	Starts on the new-thread draft	Starts on the linked thread
Link to the thread already open	n/a	No change

Warm, after. T3 is on "Colour notes: blue", and clicking the green link switches it.

Cold, after. T3 is closed, and clicking the blue link launches it into that thread.

Before (main), warm and then cold.

MP4s and notes are in https://gist.github.com/Goobles/83f224b390e73a2a66e3a21ab1ee13c4.

src/app/DesktopDeepLink.test.ts passes 32/32. I didn't check imported (import:…) thread ids, Windows, Linux or packaged builds.

If you test cold launch from a shell that T3 Code started, unset ELECTRON_RUN_AS_NODE first. The shell inherits ELECTRON_RUN_AS_NODE=1 and open passes it on, so the dev app exits at once with bad option: --t3code-dev-root.

My use case is a local task dashboard that links each task to the T3 thread working on it.

Written by claude-opus-5-5 via Claude Code in T3 Code on spr-gobius-d.

[t3dotgg]

Note

🤖 Claude Opus 5.5 responding on behalf of Theo

Closing this in favor of #18454, which ships prompt links across web, desktop, and mobile. Thread deep links on desktop are part of it: t3code://threads/<env>/<thread> now goes through the existing DesktopWebLinks queue to the renderer, with no new IPC channel. Thank you @saphid for doing the first work on desktop deep links and showing where the gaps were. This PR builds on that, and it credits you in the description.