Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

27.8 KB
Raw Blame
// Dev-server port discovery: which TCP ports each node's session is LISTENING on.
//
// Ownership, never probing. A port is attributed to a node only when its listening socket belongs
// to a process inside that node's tmux pane tree (the same tree session memory rolls up). Nothing
// is ever connected to, and another user's or another program's port is never reported.
//
// ONE generated POSIX sh script answers the whole question in one round trip — the panes of every
// nodeterm tmux socket, the process table, and the listening sockets with their owning pids — and
// the SAME script runs for a local project (`/bin/sh -c`) and over an SSH project's ControlMaster.
// One script, one parser: a local leg written separately would drift from the remote one, which is
// what this repo's session-memory ledger records happening three times.
//
// Which listener tool answers, in order:
//   - `ss -ltnp` (Linux, iproute2): only listeners, with `users:(("node",pid=123,fd=21))` for
//     sockets of processes we own — a few lines of output.
//   - `lsof -nP -iTCP -sTCP:LISTEN -Fpcn` (macOS, and Linux hosts without ss). lsof exits 1 when
//     nothing matched, which is an ANSWER here, not a failure.
//   - `/proc/net/tcp{,6}` + `ls -l /proc/<pid>/fd` (a Linux host with neither): the socket inode
//     joins the two. One `ls` process, not one `readlink` per descriptor.

import { execFile } from 'child_process'
import { promisify } from 'util'
import { DEV_PORT_EPHEMERAL_MIN, type DevPort, type DevPortsReport } from '../shared/dev-ports'
import { REMOTE_TMUX_PATH_DIRS } from '../shared/ssh'
import { shellSingleQuote } from '../shared/shell-quote'
import { indexProcesses, type PaneRef } from './session-memory'
import { fencedListPanesCommand, parseFencedPanes } from './session-memory-remote'
import { TMUX_SOCKET } from './tmux-naming'
import { LEGACY_RMT_TMUX_SOCKET } from './remote-ssh/control-master'
import type { SessionHostListing } from './session-host-client'
import { cimRows, powershellArgs, powershellExe } from './win32-powershell'

const runAsync = promisify(execFile)

const PANES = '##PANES'
const PROCS = '##PROCS'
const LISTEN = '##LISTEN'
const FD = '##FD'
const END = '##END'

/** The sockets nodeterm's sessions live on — `node-terminal` for local AND SSH projects (one
 *  socket per host since the 2026-11 unification) plus the legacy SSH-remote socket an older build
 *  may have left sessions on. Both are listed on either machine, like session memory. */
export const DEV_PORT_SOCKETS: readonly string[] = [TMUX_SOCKET, LEGACY_RMT_TMUX_SOCKET]

export interface DevPortsProbeOptions {
  /** tmux sockets to list. Tests pass a private one; production uses DEV_PORT_SOCKETS. */
  sockets?: readonly string[]
  /** Root of the proc filesystem for the last-resort branch. Tests point it at a fake tree. */
  procRoot?: string
  /**
   * An absolute tmux binary to ask. The LOCAL leg passes the app's own (`PtyManager.getTmuxBin()`,
   * the same one session memory is given): a Mac whose only tmux is the bundled one, or a Linux
   * box whose tmux is only on the login-shell PATH (nix, linuxbrew), has NO `tmux` on this
   * process's PATH, so a bare `tmux` answered 127 on both sockets and the chip never appeared —
   * and a different tmux CLIENT against the app's server can hit a protocol mismatch. Omitted on
   * an SSH host, where the host's own tmux is found through the PATH append.
   */
  tmuxBin?: string
}

/**
 * The generated script. Load-bearing details:
 *  - Every marker is QUOTED: an unquoted `#` at the start of a word begins a comment in POSIX sh,
 *    so `echo ##PANES` prints an empty line (measured under dash in session-memory-remote.ts).
 *  - `##END` is printed last and unconditionally; a missing one means the stream was cut short.
 *  - PATH is APPENDED with the tmux dirs (Homebrew — issue #449) and `/usr/sbin:/sbin`, where `ss`
 *    and `lsof` live on some distributions and macOS, and which an ssh exec channel's non-login
 *    PATH often lacks. Append, never prepend: the host's own binaries win.
 *  - `ps -eo pid=,ppid=,comm=` is POSIX (`=` suppresses the header) and works on macOS.
 */
export function devPortsProbeCommand(opts: DevPortsProbeOptions = {}): string {
  const sockets = opts.sockets ?? DEV_PORT_SOCKETS
  const proc = opts.procRoot ?? '/proc'
  const tmux = opts.tmuxBin ? shellSingleQuote(opts.tmuxBin) : 'tmux'
  return [
    `PATH="$PATH:${REMOTE_TMUX_PATH_DIRS}:/usr/sbin:/sbin"`,
    `echo '${PANES}'`,
    ...sockets.map((s) => fencedListPanesCommand(s, tmux)),
    `echo '${PROCS}'`,
    `ps -eo pid=,ppid=,comm= 2>/dev/null`,
    `echo '${LISTEN}'`,
    `if command -v ss >/dev/null 2>&1; then`,
    `  echo '##VIA ss'`,
    `  ss -ltnp 2>/dev/null`,
    `  echo "##LISTENRC $?"`,
    `elif command -v lsof >/dev/null 2>&1; then`,
    `  echo '##VIA lsof'`,
    `  lsof -nP -iTCP -sTCP:LISTEN -Fpcn 2>/dev/null`,
    `  echo "##LISTENRC $?"`,
    `elif [ -r '${proc}/net/tcp' ]; then`,
    `  echo '##VIA proc'`,
    `  cat '${proc}/net/tcp' '${proc}/net/tcp6' 2>/dev/null`,
    `  echo '${FD}'`,
    // `-q`: a non-printable in a link target prints as `?`. Without it GNU ls prints a NEWLINE in
    // an fd's target raw, and a file named `a\n/proc/100/fd:\nl -> socket:[999]` forges a pid
    // header and hands socket 999 to pid 100 (reproduced).
    `  ls -lq '${proc}'/[0-9]*/fd 2>/dev/null`,
    `  echo '##LISTENRC 0'`,
    `else`,
    `  echo '##VIA none'`,
    `fi`,
    `echo '${END}'`
  ].join('\n')
}

/** A process holding a listening socket, with the name the listener tool printed for it ('' when
 *  the tool names none — the /proc branch). */
export interface SocketOwner {
  pid: number
  command: string
}

/** One listening socket and the process(es) that hold it. */
export interface Listener {
  owners: SocketOwner[]
  address: string
  port: number
}

export interface ProcRow {
  pid: number
  ppid: number
  command: string
}

/** `ps -eo pid=,ppid=,comm=`. `comm` is a full path on macOS; only its basename is kept. */
export function parseProcRows(text: string): ProcRow[] {
  const out: ProcRow[] = []
  for (const line of text.split('\n')) {
    const m = /^\s*(\d+)\s+(\d+)\s*(.*)$/.exec(line)
    if (!m) continue
    const command = m[3].trim()
    out.push({ pid: Number(m[1]), ppid: Number(m[2]), command: command.split('/').pop() ?? command })
  }
  return out
}

/**
 * Split `host:port` as ss and lsof print it: `127.0.0.1:5173`, `*:3000`, `[::1]:5173`, `[::]:80`,
 * the old ss spelling `:::8080`, and a scoped `127.0.0.53%lo:53`. Returns null for anything whose
 * port is not a plain number (a peer column's `*`).
 */
export function splitHostPort(token: string): { address: string; port: number } | null {
  const i = token.lastIndexOf(':')
  if (i < 0) return null
  const portText = token.slice(i + 1)
  if (!/^\d{1,5}$/.test(portText)) return null
  const port = Number(portText)
  if (port < 1 || port > 65535) return null
  let address = token.slice(0, i)
  if (address.startsWith('[') && address.endsWith(']')) address = address.slice(1, -1)
  const pct = address.indexOf('%')
  if (pct >= 0) address = address.slice(0, pct)
  if (address === '::' || address === '') address = '::'
  // An IPv4-mapped bind (`::ffff:127.0.0.1`) IS its IPv4 address — the /proc decoder already says
  // so, and leaving it mapped made `forwardTarget` answer null for an ordinary loopback server.
  const mapped = /^::ffff:(\d{1,3}(?:\.\d{1,3}){3})$/i.exec(address)
  if (mapped) address = mapped[1]
  return { address, port }
}

/**
 * `ss -ltnp`. The local address is the first `addr:port` token with a numeric port — the peer
 * column (`0.0.0.0:*`) never has one, which also makes this indifferent to whether the installed
 * ss prints a State column.
 *
 * **The owner column is attacker-influenced text.** ss prints each holder as
 * `("<name>",pid=N,fd=M)` with the process NAME raw — any process can rename itself (15 bytes of
 * comm), and a name of `vite",pid=12345` printed `users:(("vite",pid=12345",pid=219072,fd=3))`
 * (reproduced as root against a listener owned by `nobody`). Collecting every `pid=N` on the line
 * handed that stranger's port to whichever node's tree holds 12345 — pane pids are visible to every
 * user through `ps` — and the forward then served the attacker's page on `localhost`, where it
 * reads the cookies of every other localhost dev app. So each group is parsed on its own and only
 * the LAST `,pid=N,fd=M` before its closing `)` is the pid: ss cannot print `)` inside a name
 * (it would end the group), so a greedy `[^)]*` cannot be steered past it. `assembleDevPorts`
 * then cross-checks that name against `ps` for that pid.
 */
export function parseSsListeners(text: string): Listener[] {
  const out: Listener[] = []
  for (const line of text.split('\n')) {
    let hp: { address: string; port: number } | null = null
    for (const tok of line.trim().split(/\s+/)) {
      hp = splitHostPort(tok)
      if (hp) break
    }
    if (!hp) continue
    const owners: SocketOwner[] = []
    for (const group of line.matchAll(/\("([^)]*)",pid=(\d+),fd=\d+\)/g)) {
      owners.push({ pid: Number(group[2]), command: group[1] })
    }
    out.push({ owners, ...hp })
  }
  return out
}

/** `lsof -Fpcn`: `p<pid>` opens a process, `c<cmd>` names it, each `n<addr:port>` is one socket. */
export function parseLsofListeners(text: string): Listener[] {
  const out: Listener[] = []
  let pid = 0
  let command = ''
  for (const line of text.split('\n')) {
    const tag = line[0]
    const val = line.slice(1).trim()
    if (tag === 'p') {
      pid = Number(val) || 0
      command = ''
    } else if (tag === 'c') {
      command = val
    } else if (tag === 'n' && pid > 0) {
      // An established connection prints `a->b`; LISTEN never does, but be explicit.
      if (val.includes('->')) continue
      const hp = splitHostPort(val)
      if (hp) out.push({ owners: [{ pid, command }], ...hp })
    }
  }
  return out
}

/** Decode a `/proc/net/tcp{,6}` address word: each 32-bit group is in host (little-endian) order. */
export function decodeProcAddress(hex: string): string | null {
  const le = (h: string): number[] => [h.slice(6, 8), h.slice(4, 6), h.slice(2, 4), h.slice(0, 2)].map((b) => parseInt(b, 16))
  if (/^[0-9A-Fa-f]{8}$/.test(hex)) return le(hex).join('.')
  if (!/^[0-9A-Fa-f]{32}$/.test(hex)) return null
  const bytes: number[] = []
  for (let g = 0; g < 4; g++) bytes.push(...le(hex.slice(g * 8, g * 8 + 8)))
  // IPv4-mapped (::ffff:a.b.c.d) is reported as its IPv4 address.
  if (bytes.slice(0, 10).every((b) => b === 0) && bytes[10] === 0xff && bytes[11] === 0xff) {
    return bytes.slice(12).join('.')
  }
  const words: string[] = []
  for (let i = 0; i < 16; i += 2) words.push(((bytes[i] << 8) | bytes[i + 1]).toString(16))
  return compressIpv6(words)
}

function compressIpv6(words: string[]): string {
  // Longest run (≥ 2) of zero words becomes `::`.
  let best = -1
  let bestLen = 0
  for (let i = 0; i < words.length; ) {
    if (words[i] !== '0') {
      i++
      continue
    }
    let j = i
    while (j < words.length && words[j] === '0') j++
    if (j - i > bestLen && j - i >= 2) {
      best = i
      bestLen = j - i
    }
    i = j
  }
  if (best < 0) return words.join(':')
  return `${words.slice(0, best).join(':')}::${words.slice(best + bestLen).join(':')}`
}

/** LISTEN rows (`st == 0A`) of `/proc/net/tcp` + `tcp6`, keyed by socket inode. */
export function parseProcNetTcp(text: string): Map<string, { address: string; port: number }> {
  const out = new Map<string, { address: string; port: number }>()
  for (const line of text.split('\n')) {
    const f = line.trim().split(/\s+/)
    if (f.length < 10 || f[3] !== '0A') continue
    const [addrHex, portHex] = f[1].split(':')
    const address = decodeProcAddress(addrHex ?? '')
    const port = parseInt(portHex ?? '', 16)
    const inode = f[9]
    if (address === null || !Number.isInteger(port) || port < 1 || !/^\d+$/.test(inode) || inode === '0') continue
    out.set(inode, { address, port })
  }
  return out
}

/** `ls -l <proc>/[0-9]*\/fd`: directory headers name the pid, `-> socket:[N]` names the inode. */
export function parseProcFdSockets(text: string): Map<string, number[]> {
  const out = new Map<string, number[]>()
  let pid = 0
  for (const line of text.split('\n')) {
    const head = /\/(\d+)\/fd:\s*$/.exec(line)
    if (head) {
      pid = Number(head[1])
      continue
    }
    const sock = /->\s*socket:\[(\d+)\]/.exec(line)
    if (!sock || pid <= 0) continue
    const list = out.get(sock[1])
    if (list) {
      if (!list.includes(pid)) list.push(pid)
    } else out.set(sock[1], [pid])
  }
  return out
}

/**
 * Does the name a listener tool printed for a pid agree with `ps`'s name for it? Defence in depth
 * behind the per-group ss parse: a pid the tool attributes must be a process `ps` knows by that
 * name. Prefix-tolerant, because the tools truncate differently (Linux comm is 15 bytes, lsof's
 * default `c` field 9, macOS ps prints the full basename). A tool that names nothing ('' — the
 * /proc branch, where the pid comes from the kernel's fd table) is not checked.
 */
function namesAgree(toolName: string, psName: string | undefined): boolean {
  if (!toolName) return true
  if (psName === undefined || psName === '') return false
  return psName.startsWith(toolName) || toolName.startsWith(psName)
}

/** `node id → ports`, from the three facts. Pure. */
export function assembleDevPorts(
  panes: readonly PaneRef[],
  procs: readonly ProcRow[],
  listeners: readonly Listener[]
): Record<string, DevPort[]> {
  const { kids } = indexProcesses(procs.map((p) => ({ pid: p.pid, ppid: p.ppid, rssKb: 0 })))
  const commandOf = new Map(procs.map((p) => [p.pid, p.command]))
  // pid → owning node. Every pane of a session counts (a session can carry a lead pane), and a
  // `seen` set guards the walk against a cyclic ppid chain captured mid-recycle.
  const owner = new Map<number, string>()
  for (const pane of panes) {
    if (!pane.session.startsWith('nt-')) continue
    const nodeId = pane.session.slice('nt-'.length)
    if (!nodeId) continue
    const stack = [pane.panePid]
    while (stack.length > 0) {
      const pid = stack.pop() as number
      if (owner.has(pid)) continue
      owner.set(pid, nodeId)
      for (const k of kids.get(pid) ?? []) stack.push(k)
    }
  }
  const byNode = new Map<string, Map<number, DevPort>>()
  for (const l of listeners) {
    const holder = l.owners.find((o) => owner.has(o.pid) && namesAgree(o.command, commandOf.get(o.pid)))
    if (holder === undefined) continue
    const pid = holder.pid
    const nodeId = owner.get(pid) as string
    let ports = byNode.get(nodeId)
    if (!ports) byNode.set(nodeId, (ports = new Map()))
    const existing = ports.get(l.port)
    if (existing) {
      if (!existing.addresses.includes(l.address)) existing.addresses.push(l.address)
      continue
    }
    ports.set(l.port, {
      port: l.port,
      addresses: [l.address],
      command: holder.command || commandOf.get(pid) || '',
      ephemeral: l.port >= DEV_PORT_EPHEMERAL_MIN
    })
  }
  const out: Record<string, DevPort[]> = {}
  for (const [nodeId, ports] of byNode) out[nodeId] = [...ports.values()].sort((a, b) => a.port - b.port)
  return out
}

const fail = (reason: DevPortsReport['reason']): DevPortsReport => ({ ok: false, reason, nodes: {} })

/**
 * Parse the whole probe. Every failure reads as "could not look", never as "no ports":
 *  - a missing or out-of-order marker (a cut stream, an rc file that echoes into the channel);
 *  - an empty process table (a host always has processes, so `ps` never ran);
 *  - no tmux socket answered (see `parseFencedPanes` — "no server running" IS an answer);
 *  - a listener tool that failed (`ss` non-zero; `lsof` non-zero WITH output).
 */
export function parseDevPortsProbe(stdout: string, sockets: readonly string[] = DEV_PORT_SOCKETS): DevPortsReport {
  const lines = stdout.split('\n').map((l) => l.replace(/\r$/, ''))
  const iPanes = lines.indexOf(PANES)
  const iProcs = lines.indexOf(PROCS)
  const iListen = lines.indexOf(LISTEN)
  const iEnd = lines.lastIndexOf(END)
  if (iPanes < 0 || iProcs < 0 || iListen < 0 || iEnd < 0) return fail('unreachable')
  if (!(iPanes < iProcs && iProcs < iListen && iListen < iEnd)) return fail('unreachable')

  const { answered, panes } = parseFencedPanes(lines.slice(iPanes + 1, iProcs), sockets)
  if (answered === 0) return fail('unreachable')
  const procs = parseProcRows(lines.slice(iProcs + 1, iListen).join('\n'))
  if (procs.length === 0) return fail('unreachable')

  const listen = lines.slice(iListen + 1, iEnd)
  const via = /^##VIA (\w+)$/.exec(listen[0] ?? '')?.[1]
  if (via === 'none') return fail('no-listener-tool')
  const rcLine = listen.findIndex((l) => /^##LISTENRC \d+$/.test(l))
  if (!via || rcLine < 0) return fail('unreachable')
  const rc = Number(listen[rcLine].slice('##LISTENRC '.length))
  const body = listen.slice(1, rcLine).join('\n')

  let listeners: Listener[]
  if (via === 'ss') {
    if (rc !== 0) return fail('unreachable')
    listeners = parseSsListeners(body)
  } else if (via === 'lsof') {
    // lsof exits 1 when it matched nothing: with no output that is "no listeners", an answer.
    if (rc !== 0 && !(rc === 1 && body.trim() === '')) return fail('unreachable')
    listeners = parseLsofListeners(body)
  } else if (via === 'proc') {
    const fdAt = body.split('\n').indexOf(FD)
    const bodyLines = body.split('\n')
    if (fdAt < 0) return fail('unreachable')
    const sockets4 = parseProcNetTcp(bodyLines.slice(0, fdAt).join('\n'))
    const owners = parseProcFdSockets(bodyLines.slice(fdAt + 1).join('\n'))
    listeners = []
    for (const [inode, hp] of sockets4) {
      listeners.push({ owners: (owners.get(inode) ?? []).map((pid) => ({ pid, command: '' })), ...hp })
    }
  } else {
    return fail('unreachable')
  }

  // Both sockets print into one section; first pane of a (session, pid) is enough.
  return { ok: true, nodes: assembleDevPorts(panes, procs, listeners) }
}

/**
 * Which address the HOST side of a forward should connect to, from the addresses a port is bound
 * on. A server bound only to `::1` (common: `localhost` resolving to IPv6 first) refuses
 * `127.0.0.1`, so the target must follow the bind:
 *   - any IPv4 wildcard/loopback (`0.0.0.0`, `*`, `127.x`) → `127.0.0.1`;
 *   - else IPv6 loopback or wildcard → `::1`;
 *   - else the one specific address it is bound on.
 * Returns null for anything that is not a plain IPv4/IPv6 literal — the value came off another
 * machine's command output and lands in an ssh argument.
 */
export function forwardTarget(addresses: readonly string[]): string | null {
  const v4 = /^\d{1,3}(\.\d{1,3}){3}$/
  const v6 = /^[0-9A-Fa-f:]+$/
  if (addresses.some((a) => a === '0.0.0.0' || a === '*' || /^127\./.test(a))) return '127.0.0.1'
  if (addresses.some((a) => a === '::1' || a === '::')) return '::1'
  const specific = addresses.find((a) => v4.test(a) || (v6.test(a) && a.includes(':')))
  return specific ?? null
}

// ── Windows: the session host's panes + one PowerShell call ─────────────────────────────────────
//
// Windows has no `/bin/sh` and no tmux, so the POSIX script cannot run there. The three facts are
// the same, from different sources: the panes come from the session host (each session's pty pid —
// its `sessionDetails` listing), and the process table and listening sockets from ONE PowerShell
// call — `Win32_Process` and `Get-NetTCPConnection` (owning pid is a field, no name to forge), or
// `netstat -ano` where the NetTCPIP module is missing. The pure parsers below feed the very same
// `assembleDevPorts`, so ownership is decided by one tree walk on every platform.

/**
 * The Windows probe. Fenced like the POSIX one (`##PROCS`/`##LISTEN`/`##VIA`/`##END`), and any
 * error inside it exits 1 — which the exec seam reports as a rejection, i.e. `unreachable`. One
 * line, single quotes only: the whole script is one argv element and contains no `"` for Windows'
 * argv quoting to mangle.
 *
 * `Where-Object State -eq Listen` over the UNFILTERED cmdlet, not `-State Listen`: the filtered
 * form throws "no matching objects" when nothing listens, which would read as a failed probe.
 */
export const WIN32_DEV_PORTS_SCRIPT = [
  "$ErrorActionPreference = 'Stop'",
  'try {',
  `'${PROCS}';`,
  'Get-CimInstance Win32_Process | Select-Object ProcessId,ParentProcessId,Name | ConvertTo-Json -Compress;',
  `'${LISTEN}';`,
  'if (Get-Command Get-NetTCPConnection -ErrorAction SilentlyContinue) {',
  "'##VIA nettcp';",
  "Get-NetTCPConnection | Where-Object { $_.State -eq 'Listen' } | Select-Object LocalAddress,LocalPort,OwningProcess | ConvertTo-Json -Compress",
  '} else {',
  "'##VIA netstat';",
  'netstat.exe -ano;',
  "if ($LASTEXITCODE -ne 0) { throw ('netstat exited ' + $LASTEXITCODE) }",
  '};',
  `'${END}'`,
  '} catch { [Console]::Error.WriteLine($_.ToString()); exit 1 }'
].join(' ')

/** `Win32_Process` rows (ConvertTo-Json) → ProcRow. `Name` keeps its basename without `.exe`, the
 *  same shape `ps`'s comm gives the menu row. Null for unreadable JSON. */
export function parseWin32ProcRows(json: string): ProcRow[] | null {
  const rows = cimRows(json)
  if (rows === null) return null
  const out: ProcRow[] = []
  for (const r of rows) {
    const pid = Number(r.ProcessId)
    const ppid = Number(r.ParentProcessId)
    if (!Number.isSafeInteger(pid) || !Number.isSafeInteger(ppid)) continue
    const name = typeof r.Name === 'string' ? r.Name : ''
    out.push({ pid, ppid, command: name.replace(/\.exe$/i, '') })
  }
  return out
}

/** One address+port as the shared normalizer reads it (brackets for IPv6, mapped IPv4 unwrapped). */
function winHostPort(address: string, port: number): { address: string; port: number } | null {
  return splitHostPort(address.includes(':') ? `[${address}]:${port}` : `${address}:${port}`)
}

/** `Get-NetTCPConnection` listeners (ConvertTo-Json). The owning pid is a kernel FIELD, not text a
 *  process can rename itself into, so the owner carries no name to cross-check. Null for bad JSON. */
export function parseWinNetTcpListeners(json: string): Listener[] | null {
  const rows = cimRows(json)
  if (rows === null) return null
  const out: Listener[] = []
  for (const r of rows) {
    const pid = Number(r.OwningProcess)
    if (typeof r.LocalAddress !== 'string' || !Number.isSafeInteger(pid)) continue
    const hp = winHostPort(r.LocalAddress, Number(r.LocalPort))
    if (hp) out.push({ owners: [{ pid, command: '' }], ...hp })
  }
  return out
}

/**
 * `netstat -ano` → TCP listeners. The state column is LOCALIZED (`LISTENING`, `ABHÖREN`, …), so a
 * listener is recognised by what is language-neutral: a TCP row whose FOREIGN address has port 0
 * (`0.0.0.0:0`, `[::]:0`) — an established or waiting connection always has a real peer port.
 */
export function parseNetstatListeners(text: string): Listener[] {
  const out: Listener[] = []
  for (const line of text.split('\n')) {
    const m = /^\s*TCP\s+(\S+)\s+(\S+)\s+.*?(\d+)\s*$/i.exec(line.replace(/\r$/, ''))
    if (!m || !/:0$/.test(m[2])) continue
    const hp = splitHostPort(m[1])
    if (hp) out.push({ owners: [{ pid: Number(m[3]), command: '' }], ...hp })
  }
  return out
}

/** Parse the Windows probe for the given panes. Every failure is `unreachable`, never "no ports". */
export function parseWin32DevPortsProbe(stdout: string, panes: readonly PaneRef[]): DevPortsReport {
  const lines = stdout.split('\n').map((l) => l.replace(/\r$/, ''))
  const iProcs = lines.indexOf(PROCS)
  const iListen = lines.indexOf(LISTEN)
  const iEnd = lines.lastIndexOf(END)
  if (iProcs < 0 || iListen < 0 || iEnd < 0 || !(iProcs < iListen && iListen < iEnd)) return fail('unreachable')
  const procs = parseWin32ProcRows(lines.slice(iProcs + 1, iListen).join('\n'))
  if (!procs || procs.length === 0) return fail('unreachable')
  const listen = lines.slice(iListen + 1, iEnd)
  const via = /^##VIA (\w+)$/.exec(listen[0] ?? '')?.[1]
  const body = listen.slice(1).join('\n')
  let listeners: Listener[] | null
  if (via === 'nettcp') listeners = parseWinNetTcpListeners(body)
  else if (via === 'netstat') listeners = parseNetstatListeners(body)
  else return fail('unreachable')
  if (!listeners) return fail('unreachable')
  return { ok: true, nodes: assembleDevPorts(panes, procs, listeners) }
}

/**
 * The Windows local scan. The session host's listing decides everything before PowerShell runs:
 *  - a failed read, or a host too old to name its sessions' pids → `unreachable` ("could not look");
 *  - no host running, or no nt- session → ok with no ports (an answer), and NO PowerShell spawn;
 *  - otherwise one PowerShell call, whose non-zero exit (the exec rejects) is `unreachable`.
 */
export async function collectWin32DevPorts(
  listing: Promise<SessionHostListing | null>,
  exec: (bin: string, args: string[]) => Promise<string>
): Promise<DevPortsReport> {
  let read: SessionHostListing | null
  try {
    read = await listing
  } catch {
    read = null
  }
  if (!read) return fail('unreachable')
  if (!read.running) return { ok: true, nodes: {} }
  if (read.sessions === null) return fail('unreachable')
  const panes: PaneRef[] = read.sessions
    .filter((row) => row.name.startsWith('nt-'))
    .map((row) => ({ session: row.name, panePid: row.pid, command: '' }))
  if (panes.length === 0) return { ok: true, nodes: {} }
  try {
    return parseWin32DevPortsProbe(await exec(powershellExe(), powershellArgs(WIN32_DEV_PORTS_SCRIPT)), panes)
  } catch {
    return fail('unreachable')
  }
}

export interface LocalDevPortsOptions {
  /** The app's tmux (`PtyManager.getTmuxBin()`); null = no tmux, so there is no pane tree at all. */
  tmuxBin: () => string | null
  exec?: (command: string) => Promise<string>
  platformName?: NodeJS.Platform
  /**
   * Windows: the session host's listing (`PtyManager.sessionHostListing()`), `undefined` when the
   * session host is not the backend (tmux persistence switched off) — then honestly unsupported.
   */
  sessionHost?: () => Promise<SessionHostListing | null> | undefined
  /** Windows: the PowerShell exec seam. */
  execWin?: (bin: string, args: string[]) => Promise<string>
}

/** Runs the probe on this machine — the POSIX script, or on Windows the session-host leg above. */
export async function collectLocalDevPorts(opts: LocalDevPortsOptions): Promise<DevPortsReport> {
  const platformName = opts.platformName ?? process.platform
  if (platformName === 'win32') {
    const listing = opts.sessionHost?.()
    if (listing === undefined) return fail('unsupported')
    const execWin =
      opts.execWin ??
      (async (bin: string, args: string[]): Promise<string> => {
        const { stdout } = await runAsync(bin, args, {
          timeout: 15_000,
          maxBuffer: 16 * 1024 * 1024,
          windowsHide: true
        })
        return stdout
      })
    return collectWin32DevPorts(listing, execWin)
  }
  // No tmux means every terminal is a plain shell (PtyManager's fallback): no nt- pane tree exists
  // to own a port. Unsupported for this run rather than a "could not look" asked every 30 s.
  const tmuxBin = opts.tmuxBin()
  if (!tmuxBin) return fail('unsupported')
  const exec =
    opts.exec ??
    (async (command: string): Promise<string> => {
      const { stdout } = await runAsync('/bin/sh', ['-c', command], { timeout: 15_000, maxBuffer: 16 * 1024 * 1024 })
      return stdout
    })
  try {
    return parseDevPortsProbe(await exec(devPortsProbeCommand({ tmuxBin })))
  } catch {
    return fail('unreachable')
  }
}

/** Runs a POSIX sh command on the project's host; resolves stdout, or null if it could not run. */
export type RemoteDevPortsRunner = (projectId: string, command: string) => Promise<string | null>

export async function fetchRemoteDevPorts(projectId: string, run: RemoteDevPortsRunner): Promise<DevPortsReport> {
  let stdout: string | null
  try {
    stdout = await run(projectId, devPortsProbeCommand())
  } catch {
    return fail('unreachable')
  }
  if (stdout === null) return fail('unreachable')
  return parseDevPortsProbe(stdout)
}