diff --git a/cloud/apps/relay/src/assignment-placed-marker.test.ts b/cloud/apps/relay/src/assignment/assignment-placed-marker.test.ts
similarity index 93%
rename from cloud/apps/relay/src/assignment-placed-marker.test.ts
rename to cloud/apps/relay/src/assignment/assignment-placed-marker.test.ts
index d6c129ab616..183411ce39a 100644
--- a/cloud/apps/relay/src/assignment-placed-marker.test.ts
+++ b/cloud/apps/relay/src/assignment/assignment-placed-marker.test.ts
@@ -1,7 +1,7 @@
-import { ASSIGNMENT_LIMITS } from '@orca-cloud/relay-contract'
+import { ASSIGNMENT_LIMITS } from '@orca-cloud/relay-contract/assignment-invariants'
 import { afterEach, describe, expect, it } from 'vitest'
-import { RelayAssignmentStore } from './assignment/assignment-store.js'
-import { openInMemoryRelayDatabase, type RelayDatabase } from './database.js'
+import { RelayAssignmentStore } from './assignment-store.js'
+import { openInMemoryRelayDatabase, type RelayDatabase } from '../database.js'
 
 const CELL = { id: 'cell-a', url: 'https://relay-a.example.com', capacityRequests: 10 }
 const IDENTITY = { userId: 'user-a', relayHostId: 'host000000000001' }
diff --git a/cloud/apps/relay/src/assignment-reserve-mode-evacuation.test.ts b/cloud/apps/relay/src/assignment/assignment-reserve-mode-evacuation.test.ts
similarity index 95%
rename from cloud/apps/relay/src/assignment-reserve-mode-evacuation.test.ts
rename to cloud/apps/relay/src/assignment/assignment-reserve-mode-evacuation.test.ts
index f4e736a9331..e48d2b76346 100644
--- a/cloud/apps/relay/src/assignment-reserve-mode-evacuation.test.ts
+++ b/cloud/apps/relay/src/assignment/assignment-reserve-mode-evacuation.test.ts
@@ -1,7 +1,7 @@
 import { afterEach, describe, expect, it } from 'vitest'
-import { RelayAssignmentStore } from './assignment/assignment-store.js'
-import type { RelayCellConfig } from './config.js'
-import { openInMemoryRelayDatabase, type RelayDatabase } from './database.js'
+import { RelayAssignmentStore } from './assignment-store.js'
+import type { RelayCellConfig } from '../config.js'
+import { openInMemoryRelayDatabase, type RelayDatabase } from '../database.js'
 
 const CELLS: RelayCellConfig[] = [
   { id: 'cell-a', url: 'https://relay-a.example.com', capacityRequests: 10 },
diff --git a/cloud/apps/relay/src/assignment-reserve-mode.test.ts b/cloud/apps/relay/src/assignment/assignment-reserve-mode.test.ts
similarity index 98%
rename from cloud/apps/relay/src/assignment-reserve-mode.test.ts
rename to cloud/apps/relay/src/assignment/assignment-reserve-mode.test.ts
index b5614aab0c3..2a4d3cd86dc 100644
--- a/cloud/apps/relay/src/assignment-reserve-mode.test.ts
+++ b/cloud/apps/relay/src/assignment/assignment-reserve-mode.test.ts
@@ -1,8 +1,8 @@
-import { ASSIGNMENT_LIMITS } from '@orca-cloud/relay-contract'
+import { ASSIGNMENT_LIMITS } from '@orca-cloud/relay-contract/assignment-invariants'
 import { afterEach, describe, expect, it, vi } from 'vitest'
-import { RelayAssignmentStore, RelayCellInReserveModeError } from './assignment/assignment-store.js'
-import type { RelayCellConfig } from './config.js'
-import { openInMemoryRelayDatabase, type RelayDatabase } from './database.js'
+import { RelayAssignmentStore, RelayCellInReserveModeError } from './assignment-store.js'
+import type { RelayCellConfig } from '../config.js'
+import { openInMemoryRelayDatabase, type RelayDatabase } from '../database.js'
 
 const CELLS: RelayCellConfig[] = [
   { id: 'cell-a', url: 'https://relay-a.example.com', capacityRequests: 10 },
diff --git a/cloud/apps/relay/src/assignment-reserve-spill.test.ts b/cloud/apps/relay/src/assignment/assignment-reserve-spill.test.ts
similarity index 95%
rename from cloud/apps/relay/src/assignment-reserve-spill.test.ts
rename to cloud/apps/relay/src/assignment/assignment-reserve-spill.test.ts
index 63085c3bde0..e82468562d1 100644
--- a/cloud/apps/relay/src/assignment-reserve-spill.test.ts
+++ b/cloud/apps/relay/src/assignment/assignment-reserve-spill.test.ts
@@ -1,19 +1,19 @@
-import { ASSIGNMENT_LIMITS } from '@orca-cloud/relay-contract'
+import { ASSIGNMENT_LIMITS } from '@orca-cloud/relay-contract/assignment-invariants'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import {
   RelayAssignmentStore,
   type AssignOptions,
   type RelayAssignment
-} from './assignment/assignment-store.js'
-import type { RelayCellConfig } from './config.js'
+} from './assignment-store.js'
+import type { RelayCellConfig } from '../config.js'
 import {
   openInMemoryRelayDatabase,
   type RelayDatabase,
   type RelayLockOptions,
   type RelayTransactionOptions,
   type SqlRow
-} from './database.js'
-import { ReservePaceError } from './reserve-assignment.js'
+} from '../database.js'
+import { ReservePaceError } from '../reserve-assignment.js'
 
 const CELLS: RelayCellConfig[] = [
   { id: 'us-c1', url: 'https://us-c1.relay.example.com', region: 'us-central1', capacityRequests: 100 },
diff --git a/cloud/apps/relay/src/assignment-roll-replaced-cell.test.ts b/cloud/apps/relay/src/assignment/assignment-roll-replaced-cell.test.ts
similarity index 98%
rename from cloud/apps/relay/src/assignment-roll-replaced-cell.test.ts
rename to cloud/apps/relay/src/assignment/assignment-roll-replaced-cell.test.ts
index c33bbea0792..26ea4dedc58 100644
--- a/cloud/apps/relay/src/assignment-roll-replaced-cell.test.ts
+++ b/cloud/apps/relay/src/assignment/assignment-roll-replaced-cell.test.ts
@@ -3,14 +3,14 @@ import { afterEach, describe, expect, it } from 'vitest'
 import {
   RelayAssignmentStore,
   RelayHomeCellUnavailableError
-} from './assignment/assignment-store.js'
+} from './assignment-store.js'
 import {
   encodeMembership,
   type CellAdmissionMembership,
   type CellAdmissionState
-} from './cell-admission-selector.js'
-import type { RelayCellConfig } from './config.js'
-import { openInMemoryRelayDatabase, type RelayDatabase } from './database.js'
+} from '../cell-admission-selector.js'
+import type { RelayCellConfig } from '../config.js'
+import { openInMemoryRelayDatabase, type RelayDatabase } from '../database.js'
 
 // 2026-10-24, production-gce-c15: offline hosts redialed during the ~45s gap between draining a same-cap roll and replacement readiness.
 const HEARTBEAT_TTL_MS = 45_000
diff --git a/config/direct-link-open-baseline.txt b/config/direct-link-open-baseline.txt
index 580755c96b7..8113b5af389 100644
--- a/config/direct-link-open-baseline.txt
+++ b/config/direct-link-open-baseline.txt
@@ -31,6 +31,6 @@
 1 src/renderer/src/components/star-nag/StarNagToastHost.tsx
 1 src/renderer/src/components/tab-bar/BrowserTab.tsx
 1 src/renderer/src/lib/http-link-routing.ts
-1 src/renderer/src/lib/workspace-port-actions.ts
+1 src/renderer/src/lib/workspace-ports/workspace-port-actions.ts
 1 src/renderer/src/runtime/antigravity-chat-sign-in-status.ts
 3 src/renderer/src/web/preload-api/web-shell-api.ts
diff --git a/config/scripts/ci-shard-timings.json b/config/scripts/ci-shard-timings.json
index 1345db6d357..8f0022b0761 100644
--- a/config/scripts/ci-shard-timings.json
+++ b/config/scripts/ci-shard-timings.json
@@ -10127,10 +10127,10 @@
       "src/renderer/src/lib/workspace-file-browser-open-target.test.ts": 183,
       "src/renderer/src/lib/workspace-file-drag-source-runtime.test.ts": 36,
       "src/renderer/src/lib/workspace-file-drag.test.ts": 47,
-      "src/renderer/src/lib/workspace-port-groups.test.ts": 30,
-      "src/renderer/src/lib/workspace-port-host-scoped-scan.test.ts": 689,
-      "src/renderer/src/lib/workspace-port-scan-debounce.test.ts": 55,
-      "src/renderer/src/lib/workspace-port-scan-publish.test.ts": 380,
+      "src/renderer/src/lib/workspace-ports/workspace-port-groups.test.ts": 30,
+      "src/renderer/src/lib/workspace-ports/workspace-port-host-scoped-scan.test.ts": 689,
+      "src/renderer/src/lib/workspace-ports/workspace-port-scan-debounce.test.ts": 55,
+      "src/renderer/src/lib/workspace-ports/workspace-port-scan-publish.test.ts": 380,
       "src/renderer/src/lib/workspace-session-browser-history.test.ts": 248,
       "src/renderer/src/lib/workspace-session-editor-drafts.test.ts": 348,
       "src/renderer/src/lib/workspace-session-folder-host-twin.test.ts": 59,
diff --git a/src/renderer/src/components/browser-pane/new-tab/browser-new-tab-server-row.tsx b/src/renderer/src/components/browser-pane/new-tab/browser-new-tab-server-row.tsx
index ceed78ff5b6..f27aabaaeed 100644
--- a/src/renderer/src/components/browser-pane/new-tab/browser-new-tab-server-row.tsx
+++ b/src/renderer/src/components/browser-pane/new-tab/browser-new-tab-server-row.tsx
@@ -2,12 +2,12 @@ import { toast } from 'sonner'
 import { translate } from '@/i18n/i18n'
 import { useAppStore } from '@/store'
 import { BrowserFavicon } from '@/components/browser-favicon'
-import { useLocalhostLabelRouteForPort } from '@/lib/workspace-port-localhost-label-selector'
-import { addressForPort } from '@/lib/workspace-port-urls'
+import { useLocalhostLabelRouteForPort } from '@/lib/workspace-ports/workspace-port-localhost-label-selector'
+import { addressForPort } from '@/lib/workspace-ports/workspace-port-urls'
 import {
   openWorkspacePortInBrowser,
   resolveWorkspacePortBrowserUrl
-} from '@/lib/workspace-port-actions'
+} from '@/lib/workspace-ports/workspace-port-actions'
 import type { RuntimeClientTarget } from '../../../../../shared/runtime-client-target'
 import { BrowserNewTabRow } from './browser-new-tab-row'
 import type { BrowserNewTabServer } from './use-browser-new-tab-servers'
diff --git a/src/renderer/src/components/browser-pane/new-tab/use-browser-new-tab-servers.ts b/src/renderer/src/components/browser-pane/new-tab/use-browser-new-tab-servers.ts
index 5b46b1275a3..c58bf8e5e2b 100644
--- a/src/renderer/src/components/browser-pane/new-tab/use-browser-new-tab-servers.ts
+++ b/src/renderer/src/components/browser-pane/new-tab/use-browser-new-tab-servers.ts
@@ -1,9 +1,9 @@
 import { useEffect, useMemo, useState } from 'react'
 import { useAppStore } from '@/store'
-import { getWorkspacePortsByWorktreeId } from '@/lib/workspace-port-groups'
-import { workspacePortScanKeyForTarget } from '@/lib/workspace-port-actions'
-import { refreshWorkspacePortScanForTarget } from '@/lib/workspace-port-scan-refresh'
-import { probeWorkspacePortPageForTarget } from '@/lib/workspace-port-scan-client'
+import { getWorkspacePortsByWorktreeId } from '@/lib/workspace-ports/workspace-port-groups'
+import { workspacePortScanKeyForTarget } from '@/lib/workspace-ports/workspace-port-actions'
+import { refreshWorkspacePortScanForTarget } from '@/lib/workspace-ports/workspace-port-scan-refresh'
+import { probeWorkspacePortPageForTarget } from '@/lib/workspace-ports/workspace-port-scan-client'
 import type { RuntimeClientTarget } from '../../../../../shared/runtime-client-target'
 import type {
   WorkspacePort,
diff --git a/src/renderer/src/components/ports/WorkspacePortScanner.test.tsx b/src/renderer/src/components/ports/WorkspacePortScanner.test.tsx
index ca8e8de05cf..6aa1a87bc59 100644
--- a/src/renderer/src/components/ports/WorkspacePortScanner.test.tsx
+++ b/src/renderer/src/components/ports/WorkspacePortScanner.test.tsx
@@ -14,7 +14,7 @@ import {
   clearRuntimeCompatibilityCache,
   markRuntimeEnvironmentCompatible
 } from '@/runtime/runtime-rpc-client'
-import { getWorkspacePortsByWorktreeId } from '@/lib/workspace-port-groups'
+import { getWorkspacePortsByWorktreeId } from '@/lib/workspace-ports/workspace-port-groups'
 import { useAppStore } from '@/store'
 import { WorkspacePortScanner } from './WorkspacePortScanner'
 
diff --git a/src/renderer/src/components/ports/WorkspacePortScanner.tsx b/src/renderer/src/components/ports/WorkspacePortScanner.tsx
index 705fe6f2b42..4e09b827595 100644
--- a/src/renderer/src/components/ports/WorkspacePortScanner.tsx
+++ b/src/renderer/src/components/ports/WorkspacePortScanner.tsx
@@ -8,13 +8,13 @@ import {
   WORKSPACE_PORT_ALL_HOSTS_SCAN_KEY,
   scanWorkspacePortsForTarget,
   workspacePortScanKeyForTarget
-} from '@/lib/workspace-port-actions'
+} from '@/lib/workspace-ports/workspace-port-actions'
 import { runtimeRpcTargetForAuthorityKey } from '@/runtime/runtime-client-target'
 import { installWindowVisibilityInterval, isWindowVisible } from '@/lib/window-visibility-interval'
 import {
   reconcileTransientPortScanFailures,
   type PortScanDebounceState
-} from '@/lib/workspace-port-scan-debounce'
+} from '@/lib/workspace-ports/workspace-port-scan-debounce'
 import type { WorkspacePortScanResult } from '../../../../shared/workspace-ports'
 import { buildExecutionHostRegistry } from '../../../../shared/execution-host-registry'
 
diff --git a/src/renderer/src/components/right-sidebar/PortsPanel.test.tsx b/src/renderer/src/components/right-sidebar/PortsPanel.test.tsx
index 2d2a2e56f9a..482b2a5b6d2 100644
--- a/src/renderer/src/components/right-sidebar/PortsPanel.test.tsx
+++ b/src/renderer/src/components/right-sidebar/PortsPanel.test.tsx
@@ -11,7 +11,7 @@ import {
   addressForPortForwardEntry,
   browserUrlForPort,
   browserUrlForPortForwardEntry
-} from '@/lib/workspace-port-urls'
+} from '@/lib/workspace-ports/workspace-port-urls'
 
 const { activateAndRevealWorktreeMock } = vi.hoisted(() => ({
   activateAndRevealWorktreeMock: vi.fn()
@@ -31,7 +31,7 @@ import {
   refreshWorkspacePortScanAfterStop,
   resolvePortOpenInOrcaBrowser,
   scanWorkspacePortsForTarget
-} from '@/lib/workspace-port-actions'
+} from '@/lib/workspace-ports/workspace-port-actions'
 
 const workspacePort: WorkspacePort = {
   id: '127.0.0.1:63468:1234',
diff --git a/src/renderer/src/components/right-sidebar/PortsPanel.tsx b/src/renderer/src/components/right-sidebar/PortsPanel.tsx
index 18483ddb9fc..b51434aedc1 100644
--- a/src/renderer/src/components/right-sidebar/PortsPanel.tsx
+++ b/src/renderer/src/components/right-sidebar/PortsPanel.tsx
@@ -17,7 +17,7 @@ export {
   killWorkspacePortForTarget,
   openWorkspacePortInBrowser,
   scanWorkspacePortsForTarget
-} from '@/lib/workspace-port-actions'
+} from '@/lib/workspace-ports/workspace-port-actions'
 
 export default function PortsPanel({ isVisible }: { isVisible: boolean }): React.JSX.Element {
   const activeWorktree = useActiveWorktree()
diff --git a/src/renderer/src/components/right-sidebar/host-scoped-ports-panel.tsx b/src/renderer/src/components/right-sidebar/host-scoped-ports-panel.tsx
index ae25d63a072..c591fb24a59 100644
--- a/src/renderer/src/components/right-sidebar/host-scoped-ports-panel.tsx
+++ b/src/renderer/src/components/right-sidebar/host-scoped-ports-panel.tsx
@@ -7,7 +7,7 @@ import {
   killWorkspacePortOnExecutionHost,
   scanWorkspacePortsOnExecutionHost,
   type HostScopedPortHost
-} from '@/lib/workspace-port-scan-client'
+} from '@/lib/workspace-ports/workspace-port-scan-client'
 import { Button } from '@/components/ui/button'
 import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'
 import type { WorkspacePort, WorkspacePortHostScanResult } from '../../../../shared/workspace-ports'
diff --git a/src/renderer/src/components/right-sidebar/local-port-details-dialog.tsx b/src/renderer/src/components/right-sidebar/local-port-details-dialog.tsx
index 141f15d4d96..985e1d167f2 100644
--- a/src/renderer/src/components/right-sidebar/local-port-details-dialog.tsx
+++ b/src/renderer/src/components/right-sidebar/local-port-details-dialog.tsx
@@ -6,7 +6,7 @@ import {
   DialogHeader,
   DialogTitle
 } from '@/components/ui/dialog'
-import { addressForPort } from '@/lib/workspace-port-urls'
+import { addressForPort } from '@/lib/workspace-ports/workspace-port-urls'
 import type { WorkspacePort } from '../../../../shared/workspace-ports'
 import { translate } from '@/i18n/i18n'
 
diff --git a/src/renderer/src/components/right-sidebar/local-port-row.tsx b/src/renderer/src/components/right-sidebar/local-port-row.tsx
index 3e72f7db42a..3075fa488ef 100644
--- a/src/renderer/src/components/right-sidebar/local-port-row.tsx
+++ b/src/renderer/src/components/right-sidebar/local-port-row.tsx
@@ -1,7 +1,7 @@
 import React, { useCallback } from 'react'
 import { Box, Copy, ExternalLink, Info, Server, Trash2 } from 'lucide-react'
-import { getPortOpenBrowserTooltipLabel } from '@/lib/workspace-port-actions'
-import { addressForPort } from '@/lib/workspace-port-urls'
+import { getPortOpenBrowserTooltipLabel } from '@/lib/workspace-ports/workspace-port-actions'
+import { addressForPort } from '@/lib/workspace-ports/workspace-port-urls'
 import { Button } from '@/components/ui/button'
 import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '@/components/ui/tooltip'
 import {
diff --git a/src/renderer/src/components/right-sidebar/local-workspace-ports-panel.tsx b/src/renderer/src/components/right-sidebar/local-workspace-ports-panel.tsx
index f67a23818da..cbfec0a70a2 100644
--- a/src/renderer/src/components/right-sidebar/local-workspace-ports-panel.tsx
+++ b/src/renderer/src/components/right-sidebar/local-workspace-ports-panel.tsx
@@ -13,8 +13,8 @@ import {
   resolvePortOpenInOrcaBrowser,
   scanWorkspacePortsForTarget,
   workspacePortRuntimeTargetKey
-} from '@/lib/workspace-port-actions'
-import { resolveLocalhostLabelRouteForPort } from '@/lib/workspace-port-localhost-label-selector'
+} from '@/lib/workspace-ports/workspace-port-actions'
+import { resolveLocalhostLabelRouteForPort } from '@/lib/workspace-ports/workspace-port-localhost-label-selector'
 import { Button } from '@/components/ui/button'
 import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'
 import type { WorkspacePort } from '../../../../shared/workspace-ports'
diff --git a/src/renderer/src/components/right-sidebar/ssh-detected-port-row.tsx b/src/renderer/src/components/right-sidebar/ssh-detected-port-row.tsx
index 3991ce9c4dc..6ab4b7232e8 100644
--- a/src/renderer/src/components/right-sidebar/ssh-detected-port-row.tsx
+++ b/src/renderer/src/components/right-sidebar/ssh-detected-port-row.tsx
@@ -1,5 +1,5 @@
 import React from 'react'
-import { advertisedBrowserUrlForDetectedPort } from '@/lib/workspace-port-urls'
+import { advertisedBrowserUrlForDetectedPort } from '@/lib/workspace-ports/workspace-port-urls'
 import type { EnrichedDetectedPort } from '../../../../shared/ssh-types'
 import { translate } from '@/i18n/i18n'
 
diff --git a/src/renderer/src/components/right-sidebar/ssh-forwarded-port-row.tsx b/src/renderer/src/components/right-sidebar/ssh-forwarded-port-row.tsx
index 5463f69df91..e68e9c19f50 100644
--- a/src/renderer/src/components/right-sidebar/ssh-forwarded-port-row.tsx
+++ b/src/renderer/src/components/right-sidebar/ssh-forwarded-port-row.tsx
@@ -2,11 +2,11 @@ import React, { useCallback, useState } from 'react'
 import { Copy, ExternalLink, Pencil, Trash2 } from 'lucide-react'
 import { cn } from '@/lib/utils'
 import { useMountedRef } from '@/hooks/useMountedRef'
-import { getPortOpenBrowserTooltipLabel } from '@/lib/workspace-port-actions'
+import { getPortOpenBrowserTooltipLabel } from '@/lib/workspace-ports/workspace-port-actions'
 import {
   addressForPortForwardEntry,
   advertisedBrowserUrlForForwardedRow
-} from '@/lib/workspace-port-urls'
+} from '@/lib/workspace-ports/workspace-port-urls'
 import type { PortForwardEntry } from '../../../../shared/ssh-types'
 import { translate } from '@/i18n/i18n'
 
diff --git a/src/renderer/src/components/right-sidebar/ssh-forwarded-ports-section.tsx b/src/renderer/src/components/right-sidebar/ssh-forwarded-ports-section.tsx
index 91b27d09112..a9cb6e34762 100644
--- a/src/renderer/src/components/right-sidebar/ssh-forwarded-ports-section.tsx
+++ b/src/renderer/src/components/right-sidebar/ssh-forwarded-ports-section.tsx
@@ -8,7 +8,7 @@ import { translate } from '@/i18n/i18n'
 import { SshForwardedPortRow } from './ssh-forwarded-port-row'
 import { SshUnrestoredPortRow } from './ssh-unrestored-port-row'
 import { SshPortForwardDialog, type PortForwardDialogState } from './ssh-port-forward-dialog'
-import { browserUrlForPortForwardEntry } from '@/lib/workspace-port-urls'
+import { browserUrlForPortForwardEntry } from '@/lib/workspace-ports/workspace-port-urls'
 
 const NO_FORWARDS: readonly PortForwardEntry[] = []
 const NO_UNRESTORED: readonly UnrestoredPortForward[] = []
diff --git a/src/renderer/src/components/right-sidebar/ssh-ports-panel.tsx b/src/renderer/src/components/right-sidebar/ssh-ports-panel.tsx
index 8a39c5f3c2f..14d4a5220c2 100644
--- a/src/renderer/src/components/right-sidebar/ssh-ports-panel.tsx
+++ b/src/renderer/src/components/right-sidebar/ssh-ports-panel.tsx
@@ -4,8 +4,8 @@ import { toast } from 'sonner'
 import { useAppStore } from '@/store'
 import { useActiveWorktree } from '@/store/selectors'
 import { cn } from '@/lib/utils'
-import { resolvePortOpenInOrcaBrowser } from '@/lib/workspace-port-actions'
-import { browserUrlForPortForwardEntry } from '@/lib/workspace-port-urls'
+import { resolvePortOpenInOrcaBrowser } from '@/lib/workspace-ports/workspace-port-actions'
+import { browserUrlForPortForwardEntry } from '@/lib/workspace-ports/workspace-port-urls'
 import type {
   EnrichedDetectedPort,
   PortForwardEntry,
diff --git a/src/renderer/src/components/sidebar/WorktreeCardPorts.tsx b/src/renderer/src/components/sidebar/WorktreeCardPorts.tsx
index 3b1b18b684a..43b01b36fc0 100644
--- a/src/renderer/src/components/sidebar/WorktreeCardPorts.tsx
+++ b/src/renderer/src/components/sidebar/WorktreeCardPorts.tsx
@@ -12,9 +12,9 @@ import {
   openWorkspacePortInBrowser,
   refreshWorkspacePortScanAfterStop,
   resolvePortOpenInOrcaBrowser
-} from '@/lib/workspace-port-actions'
-import { useLocalhostLabelRouteForPort } from '@/lib/workspace-port-localhost-label-selector'
-import { addressForPort } from '@/lib/workspace-port-urls'
+} from '@/lib/workspace-ports/workspace-port-actions'
+import { useLocalhostLabelRouteForPort } from '@/lib/workspace-ports/workspace-port-localhost-label-selector'
+import { addressForPort } from '@/lib/workspace-ports/workspace-port-urls'
 import type { WorkspacePort } from '../../../../shared/workspace-ports'
 import {
   WorktreeCardDetailSection,
diff --git a/src/renderer/src/components/sidebar/use-worktree-card-foundation.ts b/src/renderer/src/components/sidebar/use-worktree-card-foundation.ts
index 0b66acbb2b9..db78c66c805 100644
--- a/src/renderer/src/components/sidebar/use-worktree-card-foundation.ts
+++ b/src/renderer/src/components/sidebar/use-worktree-card-foundation.ts
@@ -8,7 +8,7 @@ import {
   toRuntimeExecutionHostId
 } from '../../../../shared/execution-host'
 import { getHostDisplayLabelOverrides } from '../../../../shared/host-setting-overrides'
-import { getWorkspacePortsByWorktreeId } from '@/lib/workspace-port-groups'
+import { getWorkspacePortsByWorktreeId } from '@/lib/workspace-ports/workspace-port-groups'
 import { runtimeEnvironmentIdUnlessTwin } from '@/lib/resolve-owner'
 import { hydrateRuntimeEnvironmentSshState } from '@/runtime/runtime-environment-ssh-state'
 import { useRuntimeHostDisconnected } from '@/store/use-runtime-status-view'
diff --git a/src/renderer/src/components/status-bar/PortsStatusSegment.host-routing.test.tsx b/src/renderer/src/components/status-bar/PortsStatusSegment.host-routing.test.tsx
index 72681a1cc81..1d629cb2b28 100644
--- a/src/renderer/src/components/status-bar/PortsStatusSegment.host-routing.test.tsx
+++ b/src/renderer/src/components/status-bar/PortsStatusSegment.host-routing.test.tsx
@@ -61,7 +61,7 @@ vi.mock('@/runtime/runtime-rpc-client', async () => {
   }
 })
 
-vi.mock('@/lib/workspace-port-scan-client', () => ({
+vi.mock('@/lib/workspace-ports/workspace-port-scan-client', () => ({
   runWorkspacePortScanForTarget: runWorkspacePortScanForTargetMock
 }))
 
diff --git a/src/renderer/src/components/status-bar/PortsStatusSegment.tsx b/src/renderer/src/components/status-bar/PortsStatusSegment.tsx
index 4c4bf6f192a..b1883139acb 100644
--- a/src/renderer/src/components/status-bar/PortsStatusSegment.tsx
+++ b/src/renderer/src/components/status-bar/PortsStatusSegment.tsx
@@ -3,14 +3,17 @@ import { Plug, ChevronDown, ChevronRight, LoaderCircle } from 'lucide-react'
 import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover'
 import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'
 import { useAppStore } from '@/store'
-import { refreshWorkspacePortScanForTarget } from '@/lib/workspace-port-scan-refresh'
+import { refreshWorkspacePortScanForTarget } from '@/lib/workspace-ports/workspace-port-scan-refresh'
 import { useWorktreeRuntimeTarget } from '@/runtime/use-worktree-runtime-target'
 import {
   getUnavailableWorkspacePortHosts,
   type WorkspacePortHostRef
-} from '@/lib/workspace-port-host-availability'
+} from '@/lib/workspace-ports/workspace-port-host-availability'
 import { getLocalExecutionHostLabel } from '../../../../shared/execution-host'
-import { getExternalWorkspacePorts, getWorkspacePortGroups } from '@/lib/workspace-port-groups'
+import {
+  getExternalWorkspacePorts,
+  getWorkspacePortGroups
+} from '@/lib/workspace-ports/workspace-port-groups'
 import { SelectedTextCopyMenu } from '@/components/SelectedTextCopyMenu'
 import { STATUS_BAR_CONTEXT_MENU_EXEMPT_PROPS } from './status-bar-context-menu-policy'
 import { PortRow, WorkspaceGroupRows } from './ports-status-popover-rows'
diff --git a/src/renderer/src/components/status-bar/ports-status-popover-rows.test.tsx b/src/renderer/src/components/status-bar/ports-status-popover-rows.test.tsx
index fba6d311141..039cfd7d2c1 100644
--- a/src/renderer/src/components/status-bar/ports-status-popover-rows.test.tsx
+++ b/src/renderer/src/components/status-bar/ports-status-popover-rows.test.tsx
@@ -79,7 +79,7 @@ vi.mock('sonner', () => ({
 }))
 
 import { PortRow } from './ports-status-popover-rows'
-import { mergeWorkspacePortScans } from '@/lib/workspace-port-actions'
+import { mergeWorkspacePortScans } from '@/lib/workspace-ports/workspace-port-actions'
 
 const externalPort: WorkspacePort = {
   id: '127.0.0.1:63468:1234',
diff --git a/src/renderer/src/components/status-bar/ports-status-popover-rows.tsx b/src/renderer/src/components/status-bar/ports-status-popover-rows.tsx
index 749f5e122aa..1567eeb4823 100644
--- a/src/renderer/src/components/status-bar/ports-status-popover-rows.tsx
+++ b/src/renderer/src/components/status-bar/ports-status-popover-rows.tsx
@@ -3,8 +3,8 @@ import { Copy, ExternalLink, FolderOpen, Trash2 } from 'lucide-react'
 import { toast } from 'sonner'
 import { Button } from '@/components/ui/button'
 import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'
+import { addressForPort } from '@/lib/workspace-ports/workspace-port-urls'
 import {
-  addressForPort,
   canStopWorkspacePort,
   getPortOpenBrowserTooltipLabel,
   goToWorkspacePortOwner,
@@ -12,9 +12,9 @@ import {
   openWorkspacePortInBrowser,
   refreshWorkspacePortScanAfterStop,
   resolvePortOpenInOrcaBrowser
-} from '@/lib/workspace-port-actions'
-import type { WorkspacePortGroup } from '@/lib/workspace-port-groups'
-import { useLocalhostLabelRouteForPort } from '@/lib/workspace-port-localhost-label-selector'
+} from '@/lib/workspace-ports/workspace-port-actions'
+import type { WorkspacePortGroup } from '@/lib/workspace-ports/workspace-port-groups'
+import { useLocalhostLabelRouteForPort } from '@/lib/workspace-ports/workspace-port-localhost-label-selector'
 import { useWorktreeRuntimeTarget } from '@/runtime/use-worktree-runtime-target'
 import { useAppStore } from '@/store'
 import type { WorkspacePort } from '../../../../shared/workspace-ports'
diff --git a/src/renderer/src/components/worktree-jump-palette-document-index.ts b/src/renderer/src/components/worktree-jump-palette-document-index.ts
index dccfdfcea57..b1c6c3a38ac 100644
--- a/src/renderer/src/components/worktree-jump-palette-document-index.ts
+++ b/src/renderer/src/components/worktree-jump-palette-document-index.ts
@@ -1,6 +1,6 @@
 import { getPaletteHostBadge } from '@/components/cmd-j/palette-host-badge'
 import type { SidebarHostOption } from '@/components/sidebar/sidebar-host-options'
-import { getWorkspacePortsByWorktreeId } from '@/lib/workspace-port-groups'
+import { getWorkspacePortsByWorktreeId } from '@/lib/workspace-ports/workspace-port-groups'
 import { buildWorktreePaletteDocuments } from '@/lib/worktree-palette-document'
 import {
   getPaletteWorktreeIdentity,
diff --git a/src/renderer/src/lib/workspace-port-actions.ts b/src/renderer/src/lib/workspace-ports/workspace-port-actions.ts
similarity index 95%
rename from src/renderer/src/lib/workspace-port-actions.ts
rename to src/renderer/src/lib/workspace-ports/workspace-port-actions.ts
index 5a6881dc6f0..a50bea7cdee 100644
--- a/src/renderer/src/lib/workspace-port-actions.ts
+++ b/src/renderer/src/lib/workspace-ports/workspace-port-actions.ts
@@ -1,23 +1,21 @@
 import { translate } from '@/i18n/i18n'
 import { activateAndRevealWorktree } from '@/lib/worktree-activation'
-import type { useAppStore } from '@/store'
+import type { useAppStore } from '@/store/index'
 import { assertRuntimeEnvironmentCapability, callRuntimeRpc } from '@/runtime/runtime-rpc-client'
 import { RuntimeRpcCallError } from '@/runtime/runtime-rpc-result'
-import type { RuntimeClientTarget } from '../../../shared/runtime-client-target'
+import type { RuntimeClientTarget } from '../../../../shared/runtime-client-target'
 import { toRuntimeWorktreeSelector } from '@/runtime/runtime-worktree-selector'
 import type {
   WorkspacePort,
   WorkspacePortKillResult,
   WorkspacePortScanResult
-} from '../../../shared/workspace-ports'
-import type { LocalhostWorktreeLabelRoute } from '../../../shared/localhost-worktree-labels'
+} from '../../../../shared/workspace-ports'
+import type { LocalhostWorktreeLabelRoute } from '../../../../shared/localhost-worktree-labels'
 import { runWorkspacePortScanForTarget } from './workspace-port-scan-client'
 import { browserUrlForPort } from './workspace-port-urls'
-import { createBrowserUuid } from './browser-uuid'
-import { BROWSER_SCREENCAST_RUNTIME_CAPABILITY } from '../../../shared/protocol-version'
-import { RUNTIME_BROWSER_UNAVAILABLE_MESSAGE } from './client-creation-action-policy'
-
-export { addressForPort } from './workspace-port-urls'
+import { createNonSecureContextUuid as createBrowserUuid } from '../../../../shared/non-secure-context-uuid'
+import { BROWSER_SCREENCAST_RUNTIME_CAPABILITY } from '../../../../shared/browser-runtime-capabilities'
+import { RUNTIME_BROWSER_UNAVAILABLE_MESSAGE } from '../client-creation-action-policy'
 
 const WORKSPACE_PORT_STOP_SETTLE_MS = 500
 const WORKSPACE_PORT_TARGET_UNAVAILABLE_REASON =
diff --git a/src/renderer/src/lib/workspace-port-groups.test.ts b/src/renderer/src/lib/workspace-ports/workspace-port-groups.test.ts
similarity index 100%
rename from src/renderer/src/lib/workspace-port-groups.test.ts
rename to src/renderer/src/lib/workspace-ports/workspace-port-groups.test.ts
diff --git a/src/renderer/src/lib/workspace-port-groups.ts b/src/renderer/src/lib/workspace-ports/workspace-port-groups.ts
similarity index 98%
rename from src/renderer/src/lib/workspace-port-groups.ts
rename to src/renderer/src/lib/workspace-ports/workspace-port-groups.ts
index 92010ffe287..8270610c736 100644
--- a/src/renderer/src/lib/workspace-port-groups.ts
+++ b/src/renderer/src/lib/workspace-ports/workspace-port-groups.ts
@@ -1,4 +1,4 @@
-import type { WorkspacePort, WorkspacePortScanResult } from '../../../shared/workspace-ports'
+import type { WorkspacePort, WorkspacePortScanResult } from '../../../../shared/workspace-ports'
 
 export type WorkspacePortGroup = {
   worktreeId: string
diff --git a/src/renderer/src/lib/workspace-port-host-availability.ts b/src/renderer/src/lib/workspace-ports/workspace-port-host-availability.ts
similarity index 95%
rename from src/renderer/src/lib/workspace-port-host-availability.ts
rename to src/renderer/src/lib/workspace-ports/workspace-port-host-availability.ts
index f9b1f06a3bc..4d2abf71404 100644
--- a/src/renderer/src/lib/workspace-port-host-availability.ts
+++ b/src/renderer/src/lib/workspace-ports/workspace-port-host-availability.ts
@@ -1,4 +1,4 @@
-import type { WorkspacePortScanResult } from '../../../shared/workspace-ports'
+import type { WorkspacePortScanResult } from '../../../../shared/workspace-ports'
 
 /** Distinguish unknown scan keys from local so leaked projection keys cannot become local-host failures. */
 export type WorkspacePortHostRef =
diff --git a/src/renderer/src/lib/workspace-port-host-scoped-scan.test.ts b/src/renderer/src/lib/workspace-ports/workspace-port-host-scoped-scan.test.ts
similarity index 99%
rename from src/renderer/src/lib/workspace-port-host-scoped-scan.test.ts
rename to src/renderer/src/lib/workspace-ports/workspace-port-host-scoped-scan.test.ts
index fd14def583d..fd42f11a1ef 100644
--- a/src/renderer/src/lib/workspace-port-host-scoped-scan.test.ts
+++ b/src/renderer/src/lib/workspace-ports/workspace-port-host-scoped-scan.test.ts
@@ -17,7 +17,7 @@ import {
   WORKSPACE_PORTS_SERVER_SSH_UPDATE_REASON,
   type HostScopedPortHost
 } from './workspace-port-scan-client'
-import { WORKSPACE_PORTS_HOST_SCOPED_RUNTIME_CAPABILITY } from '../../../shared/protocol-version'
+import { WORKSPACE_PORTS_HOST_SCOPED_RUNTIME_CAPABILITY } from '../../../../shared/workspace-ports-runtime-capabilities'
 
 const host: HostScopedPortHost = {
   route: { target: { kind: 'environment', environmentId: 'env-e' }, at: 'ssh:t' },
diff --git a/src/renderer/src/lib/workspace-port-localhost-label-selector.ts b/src/renderer/src/lib/workspace-ports/workspace-port-localhost-label-selector.ts
similarity index 81%
rename from src/renderer/src/lib/workspace-port-localhost-label-selector.ts
rename to src/renderer/src/lib/workspace-ports/workspace-port-localhost-label-selector.ts
index d893d76afe9..422bf188b8a 100644
--- a/src/renderer/src/lib/workspace-port-localhost-label-selector.ts
+++ b/src/renderer/src/lib/workspace-ports/workspace-port-localhost-label-selector.ts
@@ -1,9 +1,9 @@
-import type { LocalhostWorktreeLabelRoute } from '../../../shared/localhost-worktree-labels'
-import type { GlobalSettings } from '../../../shared/global-settings-types'
-import type { Project } from '../../../shared/project-types'
-import type { Repo } from '../../../shared/repo-types'
-import type { WorkspacePort } from '../../../shared/workspace-ports'
-import { useAppStore } from '@/store'
+import type { LocalhostWorktreeLabelRoute } from '../../../../shared/localhost-worktree-labels'
+import type { GlobalSettings } from '../../../../shared/global-settings-types'
+import type { Project } from '../../../../shared/project-types'
+import type { Repo } from '../../../../shared/repo-types'
+import type { WorkspacePort } from '../../../../shared/workspace-ports'
+import { useAppStore } from '@/store/index'
 import { localhostWorktreeLabelRouteForPort } from './workspace-port-localhost-label'
 
 // Share port → repo → workspace → project routing across reactive and imperative surfaces.
diff --git a/src/renderer/src/lib/workspace-port-localhost-label.ts b/src/renderer/src/lib/workspace-ports/workspace-port-localhost-label.ts
similarity index 70%
rename from src/renderer/src/lib/workspace-port-localhost-label.ts
rename to src/renderer/src/lib/workspace-ports/workspace-port-localhost-label.ts
index 86f2e97ab26..1238cb0e8cb 100644
--- a/src/renderer/src/lib/workspace-port-localhost-label.ts
+++ b/src/renderer/src/lib/workspace-ports/workspace-port-localhost-label.ts
@@ -1,8 +1,8 @@
-import type { LocalhostWorktreeLabelRoute } from '../../../shared/localhost-worktree-labels'
-import type { GlobalSettings } from '../../../shared/global-settings-types'
-import type { Project } from '../../../shared/project-types'
-import type { Repo } from '../../../shared/repo-types'
-import type { WorkspacePort } from '../../../shared/workspace-ports'
+import type { LocalhostWorktreeLabelRoute } from '../../../../shared/localhost-worktree-labels'
+import type { GlobalSettings } from '../../../../shared/global-settings-types'
+import type { Project } from '../../../../shared/project-types'
+import type { Repo } from '../../../../shared/repo-types'
+import type { WorkspacePort } from '../../../../shared/workspace-ports'
 import { browserUrlForPort } from './workspace-port-urls'
 
 export function localhostWorktreeLabelRouteForPort({
diff --git a/src/renderer/src/lib/workspace-port-scan-client.ts b/src/renderer/src/lib/workspace-ports/workspace-port-scan-client.ts
similarity index 96%
rename from src/renderer/src/lib/workspace-port-scan-client.ts
rename to src/renderer/src/lib/workspace-ports/workspace-port-scan-client.ts
index fc048ee923b..a5a11f3d469 100644
--- a/src/renderer/src/lib/workspace-port-scan-client.ts
+++ b/src/renderer/src/lib/workspace-ports/workspace-port-scan-client.ts
@@ -1,6 +1,6 @@
 import { callRuntimeRpc, runtimeEnvironmentSupportsCapability } from '@/runtime/runtime-rpc-client'
 import { RuntimeRpcCallError } from '@/runtime/runtime-rpc-result'
-import type { RuntimeClientTarget } from '../../../shared/runtime-client-target'
+import type { RuntimeClientTarget } from '../../../../shared/runtime-client-target'
 import { callHostRoute } from '@/runtime/host-route-call'
 import type { HostRoute } from '@/runtime/runtime-client-target'
 import { toRuntimeWorktreeSelector } from '@/runtime/runtime-worktree-selector'
@@ -11,9 +11,9 @@ import type {
   WorkspacePortPageProbeRequest,
   WorkspacePortPageProbeResult,
   WorkspacePortScanResult
-} from '../../../shared/workspace-ports'
-import { normalizeExecutionHostId } from '../../../shared/execution-host'
-import { WORKSPACE_PORTS_HOST_SCOPED_RUNTIME_CAPABILITY } from '../../../shared/protocol-version'
+} from '../../../../shared/workspace-ports'
+import { normalizeExecutionHostId } from '../../../../shared/execution-host'
+import { WORKSPACE_PORTS_HOST_SCOPED_RUNTIME_CAPABILITY } from '../../../../shared/workspace-ports-runtime-capabilities'
 
 export const WORKSPACE_PORTS_SERVER_SSH_UPDATE_REASON =
   'Update the server to see ports on its SSH hosts.'
diff --git a/src/renderer/src/lib/workspace-port-scan-debounce.test.ts b/src/renderer/src/lib/workspace-ports/workspace-port-scan-debounce.test.ts
similarity index 98%
rename from src/renderer/src/lib/workspace-port-scan-debounce.test.ts
rename to src/renderer/src/lib/workspace-ports/workspace-port-scan-debounce.test.ts
index d0b8221f564..dbaf50def7f 100644
--- a/src/renderer/src/lib/workspace-port-scan-debounce.test.ts
+++ b/src/renderer/src/lib/workspace-ports/workspace-port-scan-debounce.test.ts
@@ -4,7 +4,7 @@ import {
   type KeyedPortScan,
   type PortScanDebounceState
 } from './workspace-port-scan-debounce'
-import type { WorkspacePortScanResult } from '../../../shared/workspace-ports'
+import type { WorkspacePortScanResult } from '../../../../shared/workspace-ports'
 
 function good(portIds: string[]): WorkspacePortScanResult {
   return {
diff --git a/src/renderer/src/lib/workspace-port-scan-debounce.ts b/src/renderer/src/lib/workspace-ports/workspace-port-scan-debounce.ts
similarity index 95%
rename from src/renderer/src/lib/workspace-port-scan-debounce.ts
rename to src/renderer/src/lib/workspace-ports/workspace-port-scan-debounce.ts
index add2abc4f70..d3c2a7e5f80 100644
--- a/src/renderer/src/lib/workspace-port-scan-debounce.ts
+++ b/src/renderer/src/lib/workspace-ports/workspace-port-scan-debounce.ts
@@ -1,4 +1,4 @@
-import type { WorkspacePortScanResult } from '../../../shared/workspace-ports'
+import type { WorkspacePortScanResult } from '../../../../shared/workspace-ports'
 
 export type KeyedPortScan = { key: string; result: WorkspacePortScanResult }
 
diff --git a/src/renderer/src/lib/workspace-port-scan-publish.test.ts b/src/renderer/src/lib/workspace-ports/workspace-port-scan-publish.test.ts
similarity index 98%
rename from src/renderer/src/lib/workspace-port-scan-publish.test.ts
rename to src/renderer/src/lib/workspace-ports/workspace-port-scan-publish.test.ts
index 0e611fc71c2..d9030aad12c 100644
--- a/src/renderer/src/lib/workspace-port-scan-publish.test.ts
+++ b/src/renderer/src/lib/workspace-ports/workspace-port-scan-publish.test.ts
@@ -1,7 +1,7 @@
 // @vitest-environment happy-dom
 
 import { beforeEach, describe, expect, it, vi } from 'vitest'
-import type { WorkspacePortScanResult } from '../../../shared/workspace-ports'
+import type { WorkspacePortScanResult } from '../../../../shared/workspace-ports'
 
 vi.mock('@/lib/worktree-activation', () => ({
   activateAndRevealWorktree: vi.fn()
diff --git a/src/renderer/src/lib/workspace-port-scan-refresh.ts b/src/renderer/src/lib/workspace-ports/workspace-port-scan-refresh.ts
similarity index 88%
rename from src/renderer/src/lib/workspace-port-scan-refresh.ts
rename to src/renderer/src/lib/workspace-ports/workspace-port-scan-refresh.ts
index fa79ac3fd86..e49cf1a15fd 100644
--- a/src/renderer/src/lib/workspace-port-scan-refresh.ts
+++ b/src/renderer/src/lib/workspace-ports/workspace-port-scan-refresh.ts
@@ -1,6 +1,6 @@
 import { translate } from '@/i18n/i18n'
-import type { RuntimeClientTarget } from '../../../shared/runtime-client-target'
-import type { WorkspacePortScanResult } from '../../../shared/workspace-ports'
+import type { RuntimeClientTarget } from '../../../../shared/runtime-client-target'
+import type { WorkspacePortScanResult } from '../../../../shared/workspace-ports'
 import {
   publishWorkspacePortScanForHost,
   scanWorkspacePortsForTarget,
diff --git a/src/renderer/src/lib/workspace-port-urls.ts b/src/renderer/src/lib/workspace-ports/workspace-port-urls.ts
similarity index 97%
rename from src/renderer/src/lib/workspace-port-urls.ts
rename to src/renderer/src/lib/workspace-ports/workspace-port-urls.ts
index eff4c5aff00..a110023aa0c 100644
--- a/src/renderer/src/lib/workspace-port-urls.ts
+++ b/src/renderer/src/lib/workspace-ports/workspace-port-urls.ts
@@ -1,5 +1,5 @@
-import type { PortForwardEntry, EnrichedDetectedPort } from '../../../shared/ssh-types'
-import type { WorkspacePort } from '../../../shared/workspace-ports'
+import type { PortForwardEntry, EnrichedDetectedPort } from '../../../../shared/ssh-types'
+import type { WorkspacePort } from '../../../../shared/workspace-ports'
 
 const HTTPS_PORTS = new Set([443, 8443])
 const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '::1', '0.0.0.0', '::'])