spinuptui 1.0.0 → 1.1.1

package/CHANGELOG.md

@@ -11,6 +11,32 @@ version; such changes are called out here.
 
 ## [Unreleased]
 
+## [1.1.1] - 2026-10-01
+
+### Changed
+- **`spinuptui ssh-exec` allows `wp user list`, `wp user get` and `wp user list-caps`.** The read-only guard used to refuse everything under `wp user`, reads included, which got in the way of checking when an account was registered. Creating, deleting and changing users is still denied.
+
+### Fixed
+- **`spinuptui ssh-exec` no longer lets Redis writes through.** The read-only guard had no patterns for Redis, so `redis-cli CONFIG SET …`, `FLUSHALL`, `FLUSHDB`, `BGSAVE` and plain `SET`/`DEL` all ran as if they were diagnostics. `redis-cli` is now allowed only with a known read — `ping`, `info`, `dbsize`, `lastsave`, `config get`, `memory doctor|stats|usage`, `latency latest|history`, `slowlog get|len`, `client list|info` and a few key-inspection reads — and anything else is denied, including unrecognised options and a bare `redis-cli` fed from stdin. The denial message names the verb or option that was refused.
+- **`spinuptui ssh-exec` no longer lets unlisted WP-CLI writes through.** The guard denied a dozen named WP-CLI writes and allowed every other command, so `wp transient delete`, `wp search-replace`, `wp eval`, `wp plugin uninstall`, `wp cron event run` and more ran as diagnostics. `wp` is now allowed only with a known read (`plugin list`, `option get`, `core version`, `cache type`, `cron event list`, `db size` and the like), and the `--exec`, `--require`, `--ssh` and `--http` flags are refused on any command. Two reads that used to pass are now denied: `wp config get` and `wp config list`, because they print the database password into the audit log.
+- **The update command now actually updates.** The About panel (`?`) now suggests `bun add -g spinuptui@latest --no-cache`. Without `--no-cache`, Bun can answer `@latest` from its cached copy of npm's package list, which right after a release can still name the previous version, so the command reported success and left you where you were.
+
+## [1.1.0] - 2026-09-30
+
+### Added
+- **Clones match the source's SpinupWP settings.** Creating a site through SpinupWP's API only switches page caching on or off, so a clone used to come out with SpinupWP's defaults for everything else. The wizard now matches the source's page cache duration and exclusions, the security toggles (PHP in uploads, `xmlrpc.php`, multisite subdirectory rewrites), its path redirects, and the WP cron interval (read from the site's crontab, since the API doesn't report it). Only what differs is changed, so a retry changes nothing, and nothing the clone already has is removed. The verify pane (`v`) lists what it matched, and anything that didn't take, with `w` to open the new site in SpinupWP.
+- **Clones point out basic auth.** SpinupWP never reveals a site's basic-auth password, so a password-protected source can't be copied as-is. The verify pane says so and `w` opens the new site to set it.
+- **`spinuptui siblings <domain>` — who else is on this server.** Prints every site sharing a server with the one you name, as JSON, along with the server's own IP, SSH port, size and Ubuntu version. Each site says whether it's the server's vanity host, whether it's WordPress, what PHP it runs, whether page cache is on, and whether SpinupTUI set Uptime Kuma monitors up for it. This is for the case where a symptom belongs to the whole box rather than to one site: a vanity host's `?healthz` trips on whatever load the busiest co-tenant is making, and site isolation means the vanity site's own user can't see any of it — so the first question is always "who else lives here". `--probe` also SSHes into each site user and reports which ones this device's key is accepted for, which is the same question as "whose logs can I read". A site that comes back `permission_denied` is one key grant (`K` in the Browser view) away from being readable.
+
+### Changed
+- **Clones put the deploy script back themselves.** SpinupWP clears a deploy script set when a site is created, and until now you had to paste it back into the new site's Git settings. SpinupWP's API can now update a site's Git settings, so the clone wizard sets the source's script again once the site is done, and fixes push-to-deploy the same way if it came out different. The verify pane (`v`) says when it did. The `g` copy-and-open fallback only appears if the script still doesn't stick. A clone that finishes within about two minutes of creating the site waits out the rest first, since an earlier write would be cleared along with the original.
+
+### Fixed
+- **`spinuptui ssh` reports a hung connection as `connection_failed`.** When the connectivity probe ran past its 15-second limit, it came back as an unexplained `ssh_error` with the kill signal's exit code. It now says the connection didn't finish in time.
+
+### Notes
+- **Backups don't carry over to a clone yet.** SpinupWP stores backups per domain, so a clone backing up before DNS moves would write into the production site's folder. Switch backups on for the new site after cutover; having the wizard do it at the cutover step is planned.
+
 ## [1.0.0] - 2026-09-24
 
 ### Added
@@ -1453,7 +1479,9 @@ Initial tagged release.
 ### Notes
 - Read-only release: works with a SpinupWP **Read Only** API token.
 
-[Unreleased]: https://github.com/mwender/spinupwp-tui/compare/v1.0.0...HEAD
+[Unreleased]: https://github.com/mwender/spinupwp-tui/compare/v1.1.1...HEAD
+[1.1.1]: https://github.com/mwender/spinupwp-tui/compare/v1.1.0...v1.1.1
+[1.1.0]: https://github.com/mwender/spinupwp-tui/compare/v1.0.0...v1.1.0
 [1.0.0]: https://github.com/mwender/spinupwp-tui/compare/v0.28.0...v1.0.0
 [0.28.0]: https://github.com/mwender/spinupwp-tui/compare/v0.27.0...v0.28.0
 [0.27.0]: https://github.com/mwender/spinupwp-tui/compare/v0.26.1...v0.27.0

package/README.md

@@ -82,12 +82,14 @@
   if it's read-only — anything that looks like a write/restart/destructive
   action is denied rather than run, so any agent using it inherits that
   guarantee without building its own guard; `spinuptui incidents <domain>` /
-  `--all` surfaces Uptime Kuma's down/up history as JSON; `spinuptui pull files
-  <domain> [path]` and `spinuptui pull db <domain> --yes` set up a local working
-  copy from production without opening the TUI at all — the same engines the
-  guided flow drives. Built so another agent/script can go from just a domain to
-  "what's wrong and how do I get in", or to a working local copy, with no manual
-  lookup. → [CLI subcommands](#cli-subcommands)
+  `--all` surfaces Uptime Kuma's down/up history as JSON; `spinuptui siblings
+  <domain>` lists every site sharing that site's server, so a page on a server's
+  vanity host leads straight to the co-tenants that could be causing it;
+  `spinuptui pull files <domain> [path]` and `spinuptui pull db <domain> --yes`
+  set up a local working copy from production without opening the TUI at all —
+  the same engines the guided flow drives. Built so another agent/script can go
+  from just a domain to "what's wrong and how do I get in", or to a working local
+  copy, with no manual lookup. → [CLI subcommands](#cli-subcommands)
 - **Completion toasts** — a non-focus-stealing toast when a background write
   (PHP upgrade, reboot, DNS resolve, …) finishes.
 - **Release notes** — an in-app "what's new" after every update, sourced
@@ -163,10 +165,14 @@ to the version in the header (and in the `?` About panel).
 
 - **Homebrew:** `brew upgrade spinuptui` (the About panel shows the same
   command).
-- **Package install:** `bun add -g spinuptui@latest` (the About panel shows
-  the same command). Don't use `bun update -g` — while spinuptui is pre-1.0,
-  it records a caret range (e.g. `^0.22.2`) that excludes every later minor
-  release, so `update -g` reports success but silently doesn't update.
+- **Package install:** `bun add -g spinuptui@latest --no-cache` (the About
+  panel shows the same command). `--no-cache` matters: without it Bun can
+  answer `@latest` from its cached copy of the registry, which right after a
+  release may still name the previous version — the command reports success
+  and installs nothing new. Don't use `bun update -g` either — while spinuptui
+  was pre-1.0, it recorded a caret range (e.g. `^0.22.2`) that excludes every
+  later minor release, so `update -g` reports success but silently doesn't
+  update.
 - **Source checkout:** press **`u`** in the About panel to update in place
   (`git pull --ff-only`; refuses if you have uncommitted changes, and never
   merges/rebases). It can't hot-reload the already-running process, so it tells
@@ -199,6 +205,24 @@ spinuptui ssh-exec <domain> [--server <name>] -- <command>  Resolve the
                      attempt (allowed, denied, or unresolved) is appended to
                      <config dir>/logs/ssh-exec-audit.jsonl. Quote <command>
                      as one shell argument if it needs pipes or redirects.
+spinuptui siblings <domain> [--server <name>] [--probe]  Print every site
+                     sharing a server with this one, as JSON, with the
+                     server's own details (IP, SSH port, size, Ubuntu
+                     version). Each entry carries its site user and SSH
+                     target, whether it's WordPress, its PHP version, whether
+                     page cache is on, whether it's the server's vanity host
+                     (isVanity), whether SpinupTUI registered Uptime Kuma
+                     monitors for it (monitored), and whether it's the domain
+                     you asked about (isQuery). The vanity host sorts first,
+                     then the queried site, then the rest alphabetically.
+                     --probe additionally SSHes into each site user and
+                     reports ssh:"ok" | "permission_denied" |
+                     "connection_failed" | "ssh_error", which answers "whose
+                     logs can I actually read on this box" in one call.
+                     Written for whole-server symptoms: a vanity host's
+                     ?healthz trips on the load of whichever co-tenant is
+                     busy, and site isolation means the vanity user can't see
+                     it.
 spinuptui incidents <domain> | --all [--hours N]  Print Uptime Kuma down/up
                      incidents as JSON, scoped to sites SpinupTUI manages
                      monitoring for (config.json's kumaMonitors) — --all

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spinuptui",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "SpinupTUI — a terminal dashboard for browsing, monitoring, and managing your SpinupWP servers and sites.",
   "type": "module",
   "bin": {

package/src/api/client.ts

@@ -15,6 +15,10 @@ import type {
   CreateSitePayload,
   AdditionalDomain,
   AddDomainPayload,
+  UpdateSiteGitPayload,
+  PageCachePayload,
+  NginxSettings,
+  PathRedirect,
 } from "./types.ts"
 
 // The restartable services SpinupWP exposes (POST /servers/{id}/services/{svc}/restart).
@@ -84,6 +88,16 @@ export interface SpinupWPClientLike {
   listSites(serverId?: number): Promise<Site[]>
   getSite(id: number): Promise<Site>
   createSite(payload: CreateSitePayload): Promise<{ event_id: number }>
+  updateSiteGit(siteId: number, payload: UpdateSiteGitPayload): Promise<{ event_id: number | null } | undefined>
+  enablePageCache(siteId: number, payload?: PageCachePayload): Promise<{ event_id: number }>
+  updatePageCache(siteId: number, payload: PageCachePayload): Promise<{ event_id: number }>
+  disablePageCache(siteId: number): Promise<{ event_id: number }>
+  updateNginx(siteId: number, payload: NginxSettings): Promise<{ event_ids: number[] }>
+  listPathRedirects(siteId: number): Promise<PathRedirect[]>
+  addPathRedirect(siteId: number, payload: Omit<PathRedirect, "created_at">): Promise<{ event_id: number }>
+  enableWpCron(siteId: number, interval: number): Promise<{ event_id: number }>
+  updateWpCron(siteId: number, interval: number): Promise<{ event_id: number }>
+  disableWpCron(siteId: number): Promise<{ event_id: number }>
   enableHttps(siteId: number): Promise<{ event_id: number }>
   disableHttps(siteId: number): Promise<{ event_id: number } | undefined>
   purgePageCache(siteId: number): Promise<{ event_id: number }>
@@ -351,6 +365,57 @@ export class SpinupWPClient implements SpinupWPClientLike {
     return this.mutate<{ event_id: number }>(`/sites/${siteId}/domains`, "POST", payload)
   }
 
+  // Update a site's Git settings (at least one field). Changing only the deploy
+  // script or push-to-deploy needs no server work, so SpinupWP answers with a null
+  // event_id — the new values are in place when this resolves. Needs a Read/Write
+  // token.
+  updateSiteGit(siteId: number, payload: UpdateSiteGitPayload): Promise<{ event_id: number | null } | undefined> {
+    return this.mutate<{ event_id: number | null } | undefined>(`/sites/${siteId}/git`, "PUT", payload)
+  }
+
+  // Page cache on an existing site (the API added enable/disable/settings in
+  // 2026-09; before that only purge existed). Async → event_id. Lists in the
+  // payload are newline-separated. Needs a Read/Write token.
+  enablePageCache(siteId: number, payload: PageCachePayload = {}): Promise<{ event_id: number }> {
+    return this.mutate<{ event_id: number }>(`/sites/${siteId}/page-cache`, "POST", payload)
+  }
+  updatePageCache(siteId: number, payload: PageCachePayload): Promise<{ event_id: number }> {
+    return this.mutate<{ event_id: number }>(`/sites/${siteId}/page-cache`, "PUT", payload)
+  }
+  disablePageCache(siteId: number): Promise<{ event_id: number }> {
+    return this.mutate<{ event_id: number }>(`/sites/${siteId}/page-cache`, "DELETE")
+  }
+
+  // Nginx toggles (PHP in uploads, xmlrpc.php, multisite subdirectory rewrites;
+  // public_folder too, unused here). One event PER CHANGED SETTING comes back as
+  // `event_ids` — empty when nothing changed. Needs a Read/Write token.
+  updateNginx(siteId: number, payload: NginxSettings): Promise<{ event_ids: number[] }> {
+    return this.mutate<{ event_ids: number[] }>(`/sites/${siteId}/nginx`, "PUT", payload)
+  }
+
+  // Path redirects (nginx-level, per site). Adding a from+to pair the site already
+  // has is rejected. Async → event_id. Needs a Read/Write token.
+  async listPathRedirects(siteId: number): Promise<PathRedirect[]> {
+    return this.listAll<PathRedirect>(`/sites/${siteId}/path-redirects`)
+  }
+  addPathRedirect(siteId: number, payload: Omit<PathRedirect, "created_at">): Promise<{ event_id: number }> {
+    return this.mutate<{ event_id: number }>(`/sites/${siteId}/path-redirects`, "POST", payload)
+  }
+
+  // Server-level WP cron (a system cron job replacing WordPress's page-load cron).
+  // interval is minutes, one of WP_CRON_INTERVALS. The Site object doesn't report
+  // it — read the site user's crontab instead (wpCronInterval in serverClone.ts).
+  // Async → event_id. Needs a Read/Write token.
+  enableWpCron(siteId: number, interval: number): Promise<{ event_id: number }> {
+    return this.mutate<{ event_id: number }>(`/sites/${siteId}/cron`, "POST", { interval })
+  }
+  updateWpCron(siteId: number, interval: number): Promise<{ event_id: number }> {
+    return this.mutate<{ event_id: number }>(`/sites/${siteId}/cron`, "PUT", { interval })
+  }
+  disableWpCron(siteId: number): Promise<{ event_id: number }> {
+    return this.mutate<{ event_id: number }>(`/sites/${siteId}/cron`, "DELETE")
+  }
+
   // Enable HTTPS on a site. `type: "webroot"` requests a Let's Encrypt cert (the
   // domain must already resolve to the server for LE to issue, so this runs after
   // the DNS A record has propagated). Async → returns an event_id to poll. Needs a

package/src/api/types.ts

@@ -66,6 +66,24 @@ export interface AdditionalDomain {
   created_at: string
 }
 
+// Page cache as the Site object reports it. The exclusion lists come back as ONE
+// pipe-joined regex ("/wp-admin/|/wp-json/|…") but are WRITTEN newline-separated —
+// see splitCacheList in lib/cloneSettings.ts. Unset lists read back null.
+export interface PageCacheSettings {
+  enabled: boolean
+  duration?: number | null
+  duration_unit?: string | null
+  path_exclusions?: string | null
+  cookie_exclusions?: string | null
+  ignored_query_params?: string | null
+}
+
+export interface NginxSettings {
+  uploads_directory_protected?: boolean
+  xmlrpc_protected?: boolean
+  subdirectory_rewrite_in_place?: boolean
+}
+
 export interface Site {
   id: number
   server_id: number
@@ -75,9 +93,9 @@ export interface Site {
   php_version: string | null
   public_folder: string | null
   is_wordpress: boolean
-  page_cache?: { enabled: boolean }
+  page_cache?: PageCacheSettings
   https?: { enabled: boolean }
-  nginx?: Record<string, unknown>
+  nginx?: NginxSettings
   database?: {
     id: number | null
     user_id: number | null
@@ -193,6 +211,37 @@ export interface CreateSitePayload {
   }
 }
 
+// PUT /sites/{id}/git — at least one field. Unlike POST /sites, deploy_script sits
+// alongside the git settings here, and the write key is push_to_deploy.
+export interface UpdateSiteGitPayload {
+  repo?: string
+  branch?: string
+  deploy_script?: string
+  push_to_deploy?: boolean
+}
+
+// POST/PUT /sites/{id}/page-cache. Lists are newline-separated on write. PUT keeps
+// any omitted field.
+export interface PageCachePayload {
+  duration?: number
+  duration_unit?: string
+  path_exclusions?: string
+  cookie_exclusions?: string
+  ignored_query_params?: string
+}
+
+// A site's path redirect (GET /sites/{id}/path-redirects). type: "permanent" = 301,
+// "redirect" = 302. Delete is keyed by from + to — there's no id.
+export interface PathRedirect {
+  from: string
+  to: string
+  type: "permanent" | "redirect"
+  created_at?: string
+}
+
+// The server-level WP cron intervals SpinupWP accepts, in minutes.
+export const WP_CRON_INTERVALS = [1, 2, 5, 10, 15, 30, 60] as const
+
 export interface Event {
   id: number
   initiated_by: string | null

package/src/dev/mockClient.ts

@@ -132,6 +132,62 @@ export function createMockClient(): SpinupWPClientLike {
       return { event_id }
     },
 
+    async updateSiteGit(siteId, payload) {
+      const site = sites.find((s) => s.id === siteId)
+      if (site?.git) {
+        if (payload.repo != null) site.git.repo = payload.repo
+        if (payload.branch != null) site.git.branch = payload.branch
+        if (payload.deploy_script != null) site.git.deploy_script = payload.deploy_script
+        if (payload.push_to_deploy != null) site.git.push_enabled = payload.push_to_deploy
+      }
+      return { event_id: null }
+    },
+
+    async enablePageCache(siteId, payload = {}) {
+      const site = sites.find((s) => s.id === siteId)
+      if (site) site.page_cache = { ...site.page_cache, ...payload, enabled: true }
+      return { event_id: pushEvent("site.page_cache.enabled", site?.server_id ?? null, `Page cache enabled for ${site?.domain ?? siteId}`) }
+    },
+
+    async updatePageCache(siteId, payload) {
+      const site = sites.find((s) => s.id === siteId)
+      if (site) site.page_cache = { enabled: site.page_cache?.enabled ?? false, ...site.page_cache, ...payload }
+      return { event_id: pushEvent("site.page_cache.updated", site?.server_id ?? null, `Page cache updated for ${site?.domain ?? siteId}`) }
+    },
+
+    async disablePageCache(siteId) {
+      const site = sites.find((s) => s.id === siteId)
+      if (site) site.page_cache = { enabled: false }
+      return { event_id: pushEvent("site.page_cache.disabled", site?.server_id ?? null, `Page cache disabled for ${site?.domain ?? siteId}`) }
+    },
+
+    async updateNginx(siteId, payload) {
+      const site = sites.find((s) => s.id === siteId)
+      if (site) site.nginx = { ...site.nginx, ...payload }
+      return { event_ids: [pushEvent("site.nginx.updated", site?.server_id ?? null, `Nginx settings updated for ${site?.domain ?? siteId}`)] }
+    },
+
+    async listPathRedirects() {
+      return []
+    },
+
+    async addPathRedirect(siteId, payload) {
+      const site = sites.find((s) => s.id === siteId)
+      return { event_id: pushEvent("site.redirect.added", site?.server_id ?? null, `Redirect ${payload.from} added to ${site?.domain ?? siteId}`) }
+    },
+
+    async enableWpCron(siteId) {
+      return { event_id: pushEvent("site.cron.enabled", null, `WP cron enabled for site ${siteId}`) }
+    },
+
+    async updateWpCron(siteId) {
+      return { event_id: pushEvent("site.cron.updated", null, `WP cron updated for site ${siteId}`) }
+    },
+
+    async disableWpCron(siteId) {
+      return { event_id: pushEvent("site.cron.disabled", null, `WP cron disabled for site ${siteId}`) }
+    },
+
     async enableHttps(siteId) {
       const site = sites.find((s) => s.id === siteId)
       if (site) site.https = { enabled: true }

package/src/index.tsx

@@ -20,6 +20,7 @@ import { isDevMode } from "./dev/devMode.ts"
 import { SpinupWPClient } from "./api/client.ts"
 import { resolveSshAccess } from "./lib/cliSsh.ts"
 import { resolveIncidents } from "./lib/cliIncidents.ts"
+import { resolveSiblings } from "./lib/cliSiblings.ts"
 import { execSshCommand } from "./lib/sshExec.ts"
 import { runPullFiles, runPullDb } from "./lib/cliPull.ts"
 
@@ -72,6 +73,11 @@ Usage:
   spinuptui ssh-exec <domain> [--server <name>] -- <command>  Run a read-only
                        command over SSH (JSON); denies anything that looks
                        like a remote write
+  spinuptui siblings <domain> [--server <name>] [--probe]  List every site
+                       sharing a server with this one (JSON), flagging the
+                       server's vanity host and which sites Kuma watches.
+                       --probe also SSHes into each to report which ones this
+                       device's key can actually read.
   spinuptui incidents <domain> | --all [--hours N]  Print Uptime Kuma
                        down/up incidents for a site or the whole fleet (JSON)
   spinuptui pull files <domain> [path] [--url <local url>] [--server <name>]
@@ -163,6 +169,28 @@ if (command === "ssh-exec") {
   process.exit(result.ok ? 0 : 1)
 }
 
+if (command === "siblings") {
+  const parsed = parseFlags(args.slice(1))
+  const domain = parsed.positionals[0]
+  const server = parsed.flags.get("--server") ?? null
+  const probe = parsed.flags.has("--probe")
+  if (!domain || badFlagValue(parsed.flags, "--server")) {
+    console.error(
+      JSON.stringify({
+        ok: false,
+        reason: "usage",
+        message: "Usage: spinuptui siblings <domain> [--server <name>] [--probe]",
+      }),
+    )
+    process.exit(1)
+  }
+  const cfg = loadConfig()
+  const client = new SpinupWPClient(cfg)
+  const result = await resolveSiblings(domain, client, cfg, { server, probe })
+  console.log(JSON.stringify(result))
+  process.exit(result.ok ? 0 : 1)
+}
+
 if (command === "incidents") {
   const rest = args.slice(1)
   const hoursIdx = rest.indexOf("--hours")

package/src/lib/appUpdate.ts

@@ -162,7 +162,14 @@ export function updateCommand(): string | null {
 // hits the same wall until the following minor bump. Verified live against a
 // real stale install (0.22.2 -> 0.24.0): `update -g` exited 0 without updating,
 // `add -g spinuptui@latest` updated correctly.
-export const PACKAGE_UPDATE_CMD = "bun add -g spinuptui@latest"
+//
+// `--no-cache` because Bun answers `@latest` from its own cached copy of the
+// registry metadata when it has one. Right after a release that copy can still
+// name the previous version, so the add "succeeds" without contacting npm and
+// installs nothing new — seen live on 1.1.0's release day: two runs installed
+// 1.0.0 while the registry already served 1.1.0; the same command with
+// `--no-cache` installed 1.1.0 at once.
+export const PACKAGE_UPDATE_CMD = "bun add -g spinuptui@latest --no-cache"
 
 // The real checkout directory, resolved through Bun's module system rather
 // than process.cwd() — `spinuptui` is typically a global symlink invoked from

package/src/lib/cliIncidents.ts

@@ -35,6 +35,13 @@ const KIND_FIELDS: Array<[keyof KumaMonitorRef, IncidentKind]> = [
   ["bypassId", "bypass"],
 ]
 
+// Does this ref name at least one monitor `resolveIncidents` would query? A ref
+// can outlive its monitors (removing one deletes its id, not the entry), so an
+// entry's mere presence isn't the answer.
+export function hasIncidentMonitors(ref: KumaMonitorRef | undefined): boolean {
+  return !!ref && KIND_FIELDS.some(([field]) => typeof ref[field] === "number")
+}
+
 interface Target {
   domain: string
   kind: IncidentKind

package/src/lib/cliSiblings.ts

@@ -0,0 +1,181 @@
+// `spinuptui siblings <domain>` — every site sharing a server with this one,
+// for external tooling (e.g. an incident-diagnostics agent handed one domain).
+//
+// The motivating case: a server's vanity host pages on `?healthz`, but the
+// vanity site is an empty placeholder — the load is always a co-tenant, and
+// site isolation means the vanity user can't read the neighbour's logs. The
+// agent needs to know who else lives on the box, and which of them it can
+// actually SSH into, before it can find the request-level cause. Answering that
+// from the API takes two calls; discovering it by hand took weeks.
+
+import type { AppConfig } from "../config.ts"
+import type { Server, Site } from "../api/types.ts"
+import type { SpinupWPClientLike } from "../api/client.ts"
+import { ApiError } from "../api/client.ts"
+import {
+  resolveSiteByDomain,
+  probeSshTarget,
+  type SshAccessReason,
+  type SshAccessCandidate,
+  type SshProbeStatus,
+} from "./cliSsh.ts"
+import { hasIncidentMonitors } from "./cliIncidents.ts"
+import { resolveSiteSshTarget } from "./probe.ts"
+import { isVanityPair } from "./vanitySite.ts"
+
+// Why a co-tenant's logs may be out of reach. `ok` means this device's key is
+// accepted for that site user; `permission_denied` is the one worth acting on
+// (grant the key with K in the Browser view) and the usual reason a neighbour's
+// access log can't be read.
+export type SiblingSshStatus = SshProbeStatus
+
+export interface SiblingSite {
+  domain: string
+  siteUser: string | null
+  sshTarget: string
+  isWordPress: boolean
+  phpVersion: string | null
+  pageCache: boolean | null
+  // The site living at the server's own hostname — a placeholder whose monitors
+  // report on the whole box, so its pages are rarely about itself.
+  isVanity: boolean
+  // Has Uptime Kuma monitors registered through SpinupTUI, so `spinuptui
+  // incidents <domain>` will return something for it.
+  monitored: boolean
+  // The domain that was asked about, so a caller can tell itself apart from the
+  // neighbours without re-matching on additional domains.
+  isQuery: boolean
+  // Only present with --probe.
+  ssh?: SiblingSshStatus
+  sshMessage?: string
+}
+
+export interface SiblingsServer {
+  id: number
+  name: string
+  ip: string | null
+  // Needed alongside each site's sshTarget; null means the default, 22.
+  sshPort: number | null
+  provider: string | null
+  size: string | null
+  ubuntuVersion: string | null
+}
+
+export type SiblingsResult =
+  | {
+      ok: true
+      domain: string
+      primaryDomain: string
+      server: SiblingsServer
+      siteCount: number
+      sites: SiblingSite[]
+    }
+  | {
+      ok: false
+      domain: string
+      reason: SshAccessReason
+      message: string
+      remedy?: string
+      candidates?: SshAccessCandidate[]
+    }
+
+// Every probe hits the same sshd, so they're capped rather than all fired at
+// once: OpenSSH's default MaxStartups (10:30:100) starts dropping connections
+// that are still authenticating past 10, which would turn a big server's
+// result into random connection failures. A small burst of refused logins is
+// also gentler on any fail2ban-style guard watching that sshd.
+const PROBE_CONCURRENCY = 4
+
+async function mapLimit<T, R>(items: T[], limit: number, fn: (item: T) => Promise<R>): Promise<R[]> {
+  const out = new Array<R>(items.length)
+  let next = 0
+  const worker = async () => {
+    while (next < items.length) {
+      const i = next++
+      out[i] = await fn(items[i]!)
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker))
+  return out
+}
+
+function describe(site: Site, server: Server, cfg: AppConfig, queryId: number): SiblingSite {
+  return {
+    domain: site.domain,
+    siteUser: site.site_user,
+    sshTarget: resolveSiteSshTarget(site, server, cfg.sshUser),
+    isWordPress: site.is_wordpress,
+    phpVersion: site.php_version,
+    pageCache: site.page_cache ? site.page_cache.enabled : null,
+    isVanity: isVanityPair(site.domain, server.name),
+    monitored: hasIncidentMonitors(cfg.kumaMonitors[site.domain]),
+    isQuery: site.id === queryId,
+  }
+}
+
+export async function resolveSiblings(
+  domain: string,
+  client: SpinupWPClientLike,
+  cfg: AppConfig,
+  opts?: { server?: string | null; probe?: boolean },
+): Promise<SiblingsResult> {
+  const resolved = await resolveSiteByDomain(domain, client, cfg, { server: opts?.server ?? null })
+  if (!resolved.ok) return resolved.result
+
+  const { site, server } = resolved
+
+  let siteList: Site[]
+  try {
+    siteList = await client.listSites(server.id)
+  } catch (err) {
+    if (err instanceof ApiError && err.status === 401) {
+      return {
+        ok: false,
+        domain,
+        reason: "token_rejected",
+        message: "Saved API token was rejected (401) — it may be expired or revoked.",
+        remedy: "Run `spinuptui login` to save a fresh token.",
+      }
+    }
+    const message = err instanceof ApiError ? err.message : `Unexpected error: ${(err as Error).message}`
+    return { ok: false, domain, reason: "api_error", message }
+  }
+
+  // The vanity host first, then the queried site, then alphabetically: a reader
+  // scanning the list sees what the box calls itself before its tenants.
+  const sorted = [...siteList].sort((a, b) => {
+    const rank = (s: Site) =>
+      isVanityPair(s.domain, server.name) ? 0 : s.id === site.id ? 1 : 2
+    return rank(a) - rank(b) || a.domain.localeCompare(b.domain)
+  })
+
+  const sites = sorted.map((s) => describe(s, server, cfg, site.id))
+  const port = server.ssh_port && server.ssh_port !== 22 ? server.ssh_port : null
+
+  // resolveSiteByDomain has already refused a server with no IP, so every
+  // sshTarget here is a real user@ip.
+  if (opts?.probe) {
+    const probes = await mapLimit(sites, PROBE_CONCURRENCY, (s) => probeSshTarget(s.sshTarget, port))
+    probes.forEach((p, i) => {
+      sites[i]!.ssh = p.status
+      if (p.message) sites[i]!.sshMessage = p.message
+    })
+  }
+
+  return {
+    ok: true,
+    domain,
+    primaryDomain: site.domain,
+    server: {
+      id: server.id,
+      name: server.name,
+      ip: server.ip_address,
+      sshPort: port,
+      provider: server.provider_name,
+      size: server.size,
+      ubuntuVersion: server.ubuntu_version,
+    },
+    siteCount: sites.length,
+    sites,
+  }
+}