Skip to content

feat: apps add linked environments automatically - #88

Merged
nullStack65 merged 4 commits into
release/native-0.1.10from
feat/native-0.1.10-auto-add-linked
Nov 19, 2026
Merged

nullStack65 merged 4 commits into
release/native-0.1.10from
feat/native-0.1.10-auto-add-linked

Conversation

@nullStack65

Copy link
Copy Markdown
Owner

Stacked on #80 (the app and its server see the same environments). Base: feat/app-server-same-environments.

A machine that a connected server links, but this app lacks, only showed Add to this app in Settings → Linked environments. You had to click it on every device, and again for each machine that came online later.

How it works

  • linkedEnvironmentsToAutoAdd in packages/client-runtime/src/linkRequest.ts is a pure selector. From one host's known-environments rows, it returns the entries to add now: action add-to-app, link reachable, a usable app address, not in the catalog, not dismissed, and not already being added from any host. An entry that failed is skipped until its link state changes. That state is status, addresses and session (linkedAt); a new lastReachedAt alone does not count. The selector also returns failures whose state has moved, so a peer that goes down and comes back is tried again. Each try spends a single-use code, so a down peer is never retried in a loop.
  • AutoAddLinkedEnvironments (apps/web/src/state/knownEnvironments.tsx, mounted in the root route) renders one child per connected host where this client holds access:write. Each child reads that host's peerLinks.environments list and runs the selector when the list, the catalog or the dismissals change. The query reruns when the host reconnects. There are no timers or polling. It waits for client settings to hydrate and for the catalog to be ready, so a machine that is already held or dismissed never looks addable at startup.
  • The automatic add and the button share addLinkedEnvironmentToApp (apps/web/src/state/peerLinks.ts), which is the button's old flow moved out of the component. On success there is one toast: " added from 's links", noting read-only when the link caps it there. A failure shows no toast; the row keeps offering Add to this app.

Reverse path

  • These removals record the environmentId in the new client-local setting dismissedLinkedEnvironmentIds, in the existing ClientSettings schema and persistence:
    • Settings → Connections remove, when any connected host links the machine.
    • The Linked environments "also remove from this app" path.
  • The dismissal is written as a patch before removal starts. The settings snapshot updates at once, so the automatic add never sees the removed machine as missing and not dismissed.
  • A dismissed machine still shows Add to this app. A successful click clears the dismissal. Unlinking does not clear it.
  • Mobile is out of scope; a comment in apps/mobile/src/state/peerLinks.ts says so.
  • Docs: two sentences in "Link another environment" in docs/user/remote-access.md.

Tests

Run with the pinned Node 26.13.1:

  • vp test run packages/client-runtime/src/linkRequest.test.ts packages/contracts/src/settings.test.ts: 59 passed across 2 files. This includes 8 new linkedEnvironmentsToAutoAdd tests: addable, read-only link, dismissed, already in catalog, unreachable / can't pair / loopback-only address, in flight, failed at the same state vs. changed addresses or session (and not changed by lastReachedAt), and down-then-up.
  • vp test run --project browser src/components/settings/LinkedEnvironmentsSettings.browser.test.tsx: 2 passed.
  • effect-tsgo tsrs --noEmit passes in packages/client-runtime and apps/web.
  • vp lint is clean on the touched files.

Model: claude-opus-5-5
Task: feature

🤖 Generated with Claude Code

A machine a connected server links, but this app lacks, is added without a
click once its link is reachable, at no more than the link's access. A
failed add waits for the link's status, addresses or session to change, so
a down peer never burns single-use codes. Removing a linked machine from the
app keeps it out until the user chooses Add to this app.

Model: claude-opus-5-5
Task: feature
Agent: claude-code
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@nullStack65

Copy link
Copy Markdown
Owner Author

Bot review round 1 (Claude Opus 5.5, independent) @ 7b23515

Scope: git diff e697aeb..7b23515 only. That is this PR (auto-adding linked machines) against its base branch feat/app-server-same-environments, which is PR #80 ("Add to this app"). I read the code myself and did not rely on the PR description.

Verdict: blocking. Finding 1 means the founder's main requirement, that offline machines appear once they come online, is not met. Finding 2 lets a removed machine come back on its own. Findings 3 to 7 are non-blocking.

1. High (blocking): nothing adds a machine when it comes online; it waits for an unrelated event

apps/web/src/state/knownEnvironments.tsx:52-55, 115-127, with packages/client-runtime/src/state/peerLinks.ts:20-24 and runtime.ts:576-599

The auto-add only runs when its snapshot changes. The snapshot includes link.status, which comes from the host's peerLinks.environments query. That query has no refreshTrigger, no interval and no server push (the server's PeerLinks.environments at apps/server/src/peer/PeerLinks.ts:695 is a plain request/response listing). revalidateOnMount only refetches the first time the node is built, and AutoAddFromHost keeps the node mounted for the whole session. So after startup the list is re-read only when:

  • the host's own connection to this client changes (it reconnects),
  • this app's catalog changes (AppConnectionReporter → reportAppConnections.onSuccess refreshes environments),
  • the Linked environments settings panel is shown or the window regains focus while that panel is open (useLiveRefresh with refreshOnShow),
  • a link, unlink or link-request answer succeeds.

None of these fires because the peer machine came online. The docstring "Runs when a host's list changes, which includes its reconnecting" is true, but the list does not change when the peer comes online.

Failure scenario: the desktop app is open with host H connected. H links VPS M, which is off. M boots an hour later. Nothing happens until the user opens Settings → Linked environments or some other app connection changes. That is "Add to this app" with extra steps, which is the click the founder wanted to avoid.

Suggested fix (no timers): decide which event means "the peer is back", then wire it in.

  • (a) Cheapest client-side option: refresh each writable host's environments query on visibilitychange (shown) and online at the root, which useLiveRefresh({ intervalMs: null, refreshOnShow: true }) already does. This catches "I came back to the app", but not a peer that comes online while the app stays in front.
  • (b) Complete option: the host learns a link's status whenever it probes or calls the peer. Have it push a status change on an existing subscription so clients can refresh environments from that event.

My view: (a) is enough for the first cut if the PR text and docs stop saying "once their link is reachable" and say "the next time you return to the app". Otherwise it needs (b). Either way, this is the founder's call.

2. High (blocking): removing from Settings → Connections does not record a dismissal when the linking host is offline or not loaded

apps/web/src/components/settings/ConnectionsSettings.tsx:694-696

const linkingHosts = hostsLinking(peerLinkHosts, environmentId);
if (linkingHosts.length > 0) void dismissLinkedEnvironment(environmentId);

hostsLinking only looks at hosts that are connected and readable now, and only at a cached environments result already in the registry. Read-scope hosts never get that query mounted by the auto-add, and a connected host's query may still be loading.

Failure scenario: host H links M. H is offline, or its list has not loaded yet. The user removes M under Connections, linkingHosts is [], and no dismissal is written. Later H connects, the auto-add sees M as missing and not dismissed, and adds it back. The reverse path is broken in exactly the case this PR targets.

Suggested fix: dismiss unconditionally on every user-initiated remove. It costs one ID in client settings. Keep linkingHosts only for the "also forget the link" prompt. The LinkedEnvironmentsSettings.tsx:210 path already dismisses unconditionally, so this also makes the two remove paths consistent.

3. Medium: a manual "Add to this app" can race an in-flight auto-add, spending two single-use codes and leaving two authorized clients

apps/web/src/components/settings/LinkedEnvironmentsSettings.tsx:216-224, apps/web/src/state/knownEnvironments.tsx:48, 91-93, apps/web/src/state/peerLinks.ts:207

The autoAdding guard only covers the auto-add. The button calls addLinkedEnvironmentToApp directly, the row still shows "Add to this app" while the auto-add runs, and connectPairing's singleFlight key includes the pairing code, so two different codes never dedupe. The reverse can also happen: while a manual add is in flight, any snapshot change (a host reconnect or a report refresh) starts an auto-add for the same machine.

Failure scenario: at app start the auto-add for M tries M's first address, which hangs until it times out. The user opens Settings and clicks "Add to this app". M mints a second code, both pairings can succeed, registerPairing re-registers the same environmentId, and M now lists two sessions for this app under Authorized clients. One of them is orphaned.

Suggested fix: move single-flight into addLinkedEnvironmentToApp, keyed by the target environmentId and returning the in-flight promise, and drop the module-level autoAdding. Have the row read the in-flight state so it shows busy. That way one guard covers both entry points and two hosts.

4. Medium: dismissal is cleared only by the Linked environments button, not by other ways of adding the machine back

apps/web/src/state/peerLinks.ts:257-268, LinkedEnvironmentsSettings.tsx:232

Failure scenario: the user removes M (now dismissed), then adds it back through Connections → Add environment or a pairing URL. M stays dismissed. If it is removed again later by a non-user path (for example removeRelayEnvironments on T3 Connect sign-out), it is never auto-added, and nothing in the UI shows why. Similarly, if removeEnvironment fails after the void dismiss…, M stays in the app but dismissed.

Suggested fix: clear the dismissal whenever an environment successfully enters the catalog through a user action, for example on connectPairing / catalog add success, rather than only in the one button. Alternatively, write the dismissal only after removal succeeds, while keeping the snapshot ordering the comment relies on.

5. Medium (performance): the app now starts with one peerLinks.environments call per writable connected host, and each one makes the host probe every linked peer

apps/web/src/state/knownEnvironments.tsx:56-67, 78

Previously this listing ran only when the Linked environments panel was open. The settings code itself says it is too costly for a timer ("Listing probes every linked environment"). It now runs at startup and on every reconnect, for every host. The client-side render cost is small: one JSON.stringify per useEnvironments change. The new cost is network work at startup, which can be slow for unreachable peers.

Suggested fix: acceptable if it is a deliberate trade-off, but say so in the PR. Consider deferring the first query until after the first idle period or first paint, or skip hosts with no links using the cheaper list (or a link count in server config).

6. Low: a failed auto-add is silent and is retried once per page load

apps/web/src/state/knownEnvironments.tsx:94-99

autoAddFailures lives only in memory, so each reload spends one code per still-failing (host, machine) pair. That is bounded and not a loop, so it is fine. However, the user gets no signal that an auto-add was tried and failed, and the Linked environments row looks the same as one that was never tried. Consider showing the last failure reason on the row.

7. Low / nits

  • docs/user/remote-access.md:400-403 left one line unwrapped. The sentence "appear … once their link is reachable" overstates the behavior given finding 1.
  • dismissedLinkedEnvironmentIds is never pruned. That is harmless, but forgetting the last link to a machine could drop its entry.

Checked and fine

  • Pairing-code loops: none found. A failure is recorded against [status, urls, linkedAt], so repeated snapshots at the same link state do not retry. Each retry needs a real state change. A link that keeps flipping between reachable and unreachable spends one code per flip, which is bounded by events, not by a timer.
  • Two hosts at once: the shared autoAdding set is checked and filled synchronously inside each effect, so two hosts in the same commit add once. If one host fails, the other host may still try, which spends one code per host. That is acceptable.
  • Startup ordering: ready waits for isReady (catalog), useClientSettingsHydrated() and the host list. Write scope gates the hosts. persistClientSettingsPatch updates the snapshot synchronously once hydrated, so void dismiss… before remove is ordered correctly on the settings page.
  • Credentials: the minted code goes only to connectPairing. Auto-add failure messages are dropped, not logged or toasted, and the success toast holds only labels. I found no new exposure to logs, toasts, telemetry or agents in this diff. Not checked: whether anything outside this diff logs the connectPairing singleFlight key, which contains the code.
  • Surfaces: web and desktop are covered by the root component. Mobile is explicitly not covered (a comment, and the docs say "desktop and web"). The command palette has no add or remove entry. The only environmentCatalog.remove callers are the two that were edited; removeRelayEnvironments (Connect sign-out) does not dismiss.
  • Tests: 8 new pure-function cases for linkedEnvironmentsToAutoAdd, which are meaningful. The risky parts are the effect wiring (findings 1 to 3) and the dismissal round trip, and none of them is tested. A test that removes a machine while the host is disconnected, then reconnects and checks that nothing is re-added, would have caught finding 2. A test with one add in flight plus a click would have caught finding 3.
  • Complexity: it is proportionate. Folding autoAdding into the shared add function (finding 3) removes a module-level guard instead of adding one.

What I ran

  • git fetch origin pull/88/head; confirmed head 7b23515f196ae6a7cfa6e4deae9a5403fd182134; reviewed git diff e697aeb..7b23515 and read the surrounding query, onboarding and settings code.
  • vp i, then vp test run packages/client-runtime/src/linkRequest.test.ts under Node 26.13.1: 1 file, 26 tests passed. No repo-wide checks, no dev servers, no real-client run.

… removed

Repair round 1 for the auto-add review on 7b23515.

- Each writable host's linked-environment list is read again on window
  focus, the document becoming visible, the browser online event and a
  network path change (useLiveRefresh refreshOnReconnect), with the
  existing 10 s floor and no timer. The key is shared with the Linked
  environments panel.
- Removing under Connections always records the dismissal, whether or
  not a host's list is loaded. A remove that fails rolls it back.
- addLinkedEnvironmentToApp is single-flight per linked environment
  across the button and the auto-add; the row shows "Adding…" while one
  runs.
- Adding a machine back by any path (pairing, SSH, T3 Connect, Add to
  this app) clears its dismissal.
- Docs no longer claim a machine appears as soon as its link is
  reachable.

Model: claude-opus-5-5
Task: fix
Agent: claude-code
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@nullStack65

Copy link
Copy Markdown
Owner Author

Repair round 1 @ 6002bdd

Fixes the bot review round 1 findings on 7b23515. One commit on top: 7b23515..6002bdd. Base is unchanged (feat/app-server-same-environments @ e697aeb).

Finding 1: a machine that comes online later is not added

Fix (a), events only, with no interval, polling or server push. AutoAddFromHost now calls useLiveRefresh for each writable host's peerLinks.environments query with intervalMs: null and a new opt-in refreshOnReconnect option. The list is read again when:

  • the window gains focus or the document becomes visible (existing useLiveRefresh listeners)
  • the browser online event fires (new)
  • the network path changes (new). This reuses the navigator.connection type-change signal that feeds the connection supervisor's network-changed wakeup. It is extracted to apps/web/src/lib/networkPathChanges.ts and used by both connection/platform.ts and the hook. There is no separate desktop bridge network event. Desktop gets the same signal through the renderer.

Bursts are limited by the existing 10 s floor (LIVE_REFRESH_MIN_INTERVAL_MS, which matches the query's staleTimeMs: 10_000). The refresh key is shared with the Linked environments panel (linkedEnvironmentsRefreshKey), so a read by either one counts for both.
Test: useLiveRefresh.browser.test.tsx, a new case, "with refreshOnReconnect, reads when the browser comes back online, outside the floor". It checks that a burst inside the floor reads once and that a view without the option never reads.

Finding 2: removing under Connections does not always record a dismissal

ConnectionsSettings.removeSavedBackend now dismisses on every user remove, the same as the Linked environments path. hostsLinking is used only for the "also forget the link" prompt.
Test: no new test. This is a one-line wiring change with no new logic. The existing LinkedEnvironmentsSettings.browser.test.tsx still passes.

Finding 3: a button click can race an auto-add

addLinkedEnvironmentToApp is now single-flight per linked environmentId across every host, the button and the auto-add. It uses a new pure helper, singleFlightByKey in client-runtime/linkRequest.ts. The helper publishes the in-flight set to addingLinkedEnvironmentsAtom synchronously. The auto-add reads that atom in place of the old module-level autoAdding set, which is removed. While an add runs, the row's button is disabled, set to aria-busy and labelled "Adding…". This uses the existing disabled state, since Button has no loading variant. Forget is also disabled while an add runs.
Test: linkRequest.test.ts, 2 new cases under singleFlightByKey. They cover sharing one run per key and reporting the in-flight set before run returns. They also cover keys staying separate and a failed run clearing its key.

Finding 4: only the button clears a dismissal; a failed remove keeps it

Dismissal helpers moved to apps/web/src/state/linkedEnvironmentDismissals.ts. The dismissal is now cleared whenever the machine is added back by any path:

  • connectPairing success. This covers Add environment with a pairing URL or code, the /pair route, t3code://pair and Add to this app.
  • connectSshEnvironment success
  • T3 Connect register success in CloudEnvironmentConnectList
  • the relay route offer in AddEnvironmentDialog

Setting a value it already has is a no-op, so this writes nothing in the common case. dismissLinkedEnvironment now resolves to an undo that clears only a dismissal that call wrote. Both remove paths call it when the remove fails. An interrupted remove keeps the dismissal, so an interruption never re-adds the machine unasked.
Test: no new test. This is wiring on success and failure results; the pure part is the no-op check in setDismissed.

Finding 7: docs

docs/user/remote-access.md is rewrapped. It now says that a machine that comes online later "appears the next time you return to the app or your network changes", and that removing it keeps it out "until you add it back, by Add to this app or any other way". The dismissedLinkedEnvironmentIds schema comment is updated to match.

Not fixed

  • Finding 5 (startup cost): left as is. Link lists are already cached for the stale time (10 s), and the new event refreshes respect that floor. Probe cost is bounded by the number of links on each host.
  • Finding 6 (silent auto-add failure, retried once per page load): left as is, by the same reasoning. Each retry needs a real link-state change or a reload, and its cost is bounded by the number of links. The reviewer rated it fine as a bounded, non-looping cost.
  • The finding 7 nit about pruning dismissedLinkedEnvironmentIds is also left as is. It is harmless, and it was outside this round's scope.

What I ran (Node 26.13.1, vp)

  • vp test run packages/client-runtime/src/linkRequest.test.ts packages/contracts/src/settings.test.ts: 2 files, 61 tests passed. linkRequest alone had 28, up from 26.
  • vp test run --project browser src/components/settings/LinkedEnvironmentsSettings.browser.test.tsx (in apps/web): 2 passed.
  • vp test run --project browser src/hooks/useLiveRefresh.browser.test.tsx (in apps/web): 3 passed, 1 of them new.
  • Typecheck: packages/client-runtime vpr typecheck passed, 0 errors. apps/web effect-tsgo tsrs --noEmit -p tsconfig.json passed, exit 0.
  • vp fmt and vp lint on the touched files: clean.

Not run: repo-wide checks, dev servers, a real-client pass. No test drives the remove-while-host-offline flow or the click-during-auto-add flow end to end.

This is a conversation comment, not a review or approval.

@nullStack65
nullStack65 changed the base branch from feat/app-server-same-environments to release/native-0.1.10 November 18, 2026 23:58
@nullStack65
nullStack65 merged commit 4f4c0fb into release/native-0.1.10 Nov 19, 2026
2 checks passed
@nullStack65

Copy link
Copy Markdown
Owner Author

Fleet build artifacts from release/native-0.1.10 at 4f4c0fbb93 (this PR's merge, which contains 4e1e59682b, 682bce5a9e, 328c68b5ca and c540875353). Same recipe as the earlier builds. Not installed anywhere; installs belong to the fleet cutover owner.

Artifact Built on Staged at (same path on R720 and ASUS) sha256 Checks
Linux x64 headless server (t3 serve) R720, nice -n 19 ionice -c3 ~/.local/share/closura/t3-release-staging/closura-fleet-server-0.1.10-4f4c0fbb/t3-0.1.10-linux-x64.tar.gz 7e0cd377aed1e6cbea1259d993ea34c827c7889c185800255168fc7acdef8685 smoke-cli-archive.ts --expect-version 0.1.10 passes. Max GLIBC 2.34. Linked environments is on by default. manifest.json is next to it. The sha256 matches on both hosts.
Linux x64 desktop AppImage (optional, laptop) ASUS ~/.local/share/closura/t3-release-staging/closura-fleet-desktop-0.1.10-4f4c0fbb/T3-Code-0.1.10-x86_64.AppImage (ASUS only) 2580bdd10b5ae58128c66a49e6d4f62807211fbcd22510b14b0cf29b39bed33a No app-update.yml. Bundled server reports 0.1.10. The committed qualify script gives failed_gates: [].
Linux x64 desktop .deb ASUS same folder, T3-Code-0.1.10-amd64.deb 7f26a36d69c5e3f241eeb6901817c1baf0e899182cda9749373789ca3867ca23 Same build.

R720 build inputs were copied from the ASUS builds: Node 26.13.1, the noble gcc-13 sysroot from noble-desktop-toolchain.lock, patchelf 0.18.0, and the official v0.1.10 resource monitor (56523ef8…). The work tree is /mnt/arc-nvme/t3-build-primary.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant