# Proof audit, pass 1: server process labels

[#32931](https://git.cafe/pingdotgg/t3code/pull/32931), mirrored as [#32931](https://github.com/pingdotgg/t3code/pull/32931); issue [#32918](https://git.cafe/pingdotgg/t3code/issues/32918).

Read-only source audit in the supplied review checkout. Reviewed local branch `pr-32931`, requested unpublished head `f0899db4914be90c85974ef97aa427702dd13e5c`, against local `origin/main` (`b48b8ea2a0019b3d38de09406fe8be820dd8df15`). No worktree changes, fixture process launches, captures, tests, pushes, or PR comments made in this pass. All fixture values below are synthetic. This file is a plan and evidence inventory, not a visual verification claim.

## Findings

1. **Missing runnable visual evidence:** Linux can run the reporter's two titled servers through the real app and render both affected label consumers. The supplied Linux transcript reports process output, not a rendered app. No captures exist. Required rows L1 and L2 are missing; `cannot-verify macos` does not exempt them.
2. **Two consumers, not just Servers:** `ThreadServersPanel` renders `Terminal · <processName>` or `Agent · <processName>`; `PreviewLocalServerCard` renders the same value as its primary title, falling back to `Listening`. The latter is mounted by the Browser panel's empty/idle view. UI files are unchanged, but their displayed text is the output of this fix.
3. **Native boundary remains unverified:** Only darwin reads the new title query. Linux's native titles prove unchanged behavior and real UI rendering; they do not prove Darwin argv handling, lsof fallback, or cache lifetime. Keep those rows explicitly `cannot-verify macos`. A labelled harness could cover assumed data and rendering, but cannot verify native command behavior.
4. **Published evidence is stale for the requested head:** The forge currently reports an older pushed head. Its body describes `ps -E` and a combined launch cache; the requested local diff instead uses a separate no-`-E` title query/cache and includes `(name)` fallback. Published checks, reviews, and test counts cannot be attributed to this local revision. This is a provenance caveat, separate from the visual verdict.

## Source-derived render paths and branches

Paths refer to the supplied local checkout, since the reviewed head is not yet published.

- Producer: `apps/server/src/preview/PortScanner.ts`. `scan`/retained polling -> `scanUnlocked` -> Linux `/proc`, Windows discovery, or lsof fallback. On the lsof path only, `hostPlatform === "darwin"` adds `readTitles(pids)`; the other platforms pass no title map. `parseLsofOutput` uses a non-null title for that PID, otherwise its lsof `c` name. A missing PID/title or null title retains lsof's name, which itself may be null. Listener deduplication, sorting, owner selection, configured URL projection, and stop operations remain unchanged.
- Darwin parser branches: valid nonempty first space-delimited token; path token containing `/`; token containing `=`; token starting `(`; empty first token; malformed/missing PID line; process-probe failure/empty output. Only the valid token changes the displayed label. `my api` displays `my`; `python3 app.py` displays `python3`. Paths (including paths with spaces), `@workspace/api`, assignments, `(nginx)`, failures, and missing data collapse into the same fallback visual when their lsof name is identical. No secret-shaped real data is required.
- Cache/time branches: no listeners/no unread PIDs avoids title ps; known PID reuses the first parsed title or null; missing/failed reads remain unread and can retry; next PID set drops absent listeners; releasing the last scanner retention clears titles. Poll interval is three seconds while retained. A live process retitled after caching need not change its label until invalidation. No dedicated UI title-loading/error spinner exists: a failed title lookup displays the lsof fallback.
- Transport: `apps/server/src/ws.ts` `subscribeDiscoveredLocalServers` retains the scanner, emits an initial `scan`, and streams changed snapshots. `packages/contracts/src/preview.ts` allows `processName: string | null`; no contract changed. `packages/client-runtime/src/state/preview.ts` exposes `discoveredServers`; `apps/web/src/portDiscoveryState.ts` maps query data or an empty list and filters terminal/agent owners by the active thread for Servers. A configured URL with a matching listener preserves its process name; a configured-only response without a PID/name gives the null-label branch.
- Servers caller chain: `ChatView` -> `ThreadDetailsPanel` -> `ThreadServersPanel` -> `ThreadServersList`. Embedded chat omits the details panel. Servers mounts only for full density, a non-draft thread, and the enabled Servers visibility setting. The details card can be inline or a popover; compact/essential density hides Servers. Props `environmentId` and `threadId` select the data and key/reset pagination. Empty/initial-loading/error-without-data gives no section; there is no dedicated discovery error row.
- Servers row shapes: zero rows hidden; one through four shown without pagination; more than four shows four initially, then pages by four, finally `Show less`. A ten-row fixture covers 4 -> 8 -> 10 -> 4 and partial final page. `pid:port` is the row key. `port` affects the first line; terminal presence chooses `Terminal` versus `Agent`; nonempty name adds ` · name`, null omits the separator/name. Names and port lines truncate, never wrap. Stop capability + permission + non-null PID reserves right padding and enables the separate stop control; otherwise no stop control/padding. Open permission disables the main row. Stop is revealed by hover/focus, or stays visible for coarse/no-hover input. Pending stop shows a spinner for that row and disables all stop buttons; success removes the listener, failure produces a toast, interruption omits failure toast.
- Servers interactions: plain click opens the Browser panel, modifier or middle click opens externally, higher mouse buttons are ignored. Client navigator platform changes tooltip text to Command-click or Ctrl-click independently of the server's OS. Delayed open/stop tooltips, hover/focus, page expansion/collapse, thread/environment switch reset, permission denial, open failure, stop failure, and pending/removal states are unchanged. Any proof asserting their transitions is a recording.
- Browser caller chain: `ChatView`/right-panel browser surfaces -> `PreviewView` -> `PreviewEmptyState` -> `PreviewLocalServerCard` -> `DiscoveryListRow`. The empty view renders for no snapshot or Idle navigation, rather than an active/loading/failed page. `threadRef`, environment, and configured URLs select the list; cards use process name or `Listening`, host/port as the second line, and requested URL for navigation/favicon. Unlike Servers, this list is environment-wide, not filtered to the current thread. Configured-matching entries sort before scanner-only entries, then by port, without changing the name presentation. Host/port identify card keys. No list pagination.
- Browser states: neither servers nor valid recents -> `No preview yet`; recents only -> Recently used; servers only -> Local servers; both -> both groups. Invalid recent URLs are omitted; valid recents are capped at eight. Card names/addresses truncate inside a list with maximum content width; long lists scroll. No per-card stop control. Favicon image, image-error fallback, and no-image fallback occupy the same fixed icon box. Opening a server navigates away; removing a recent can change which groups remain. Preview navigation loading/failure, desktop browser ownership notice, reload, and moving a tab are adjacent states; the name change does not alter them.
- Width/theme/surfaces: theme uses existing light/dark tokens, with no new theme branch. Details card is normally 280 CSS pixels wide, with full/compact/essential density governed by available height; Browser list is fluid up to `max-w-xl`. Resizing can move details inline/popover, hide Servers by density, change ellipsis and introduce scrolling. Desktop renders the same web components; remote/relay/tunnel transport preserves `processName`, so the scanner host OS, not client OS, selects the new behavior. No process-name discovery consumer was found in native mobile or a separate desktop UI. Settings/command/keybinding entry points control the same panel visibility/navigation; they do not add a label renderer. No provider-specific UI branch was added.

## Fixture matrix

Scope is collapsed by visual output rather than multiplying unrelated unchanged dimensions. Static label rows require settled captures; merely opening a panel to reach a fixture does not make its assertion temporal. Rows whose assertion is an interaction or time transition are explicitly **recording**. `Excluded` means inventoried but unchanged, not falsely verified. Optional harness rows are not native acceptance evidence and are not added as mandatory production machinery for this small server fix.

| ID / fixture | Synthetic data and expected visual | Diff affected? | Real-app seed / feasibility | Minimum capture or recording | Existing evidence / status |
| --- | --- | --- | --- | --- | --- |
| L1 Linux terminal titles | Same real thread, terminal-owned Node listeners on 4321/4322 titled `api`/`web`; Servers shows `localhost:4321`, `Terminal · api`, then `localhost:4322`, `Terminal · web` | Linux output unchanged; relevant end-to-end regression row | In an isolated dev app, create an ordinary thread and launch the two Node listeners from its own integrated terminal; open full-density details with Servers enabled | **Required:** 1440×900 × dark × L1, settled screenshot; before/after can be identical, labelled Linux no regression | PR transcript covers Linux process output only; **MISSING capture** |
| L2 Linux Browser local-server titles | Same listeners; fresh Idle Browser tab, no recent visits; Local servers cards titled `api`/`web`, addresses `localhost:4321`/`localhost:4322` | Linux output unchanged; second relevant label consumer | Reuse L1 listeners, open a new Browser tab before navigating, preserve its idle state and empty recent history | **Required:** 1440×900 × dark × L2, settled screenshot | No capture or rendered-app transcript; **MISSING capture** |
| D1 Darwin terminal titles / short argv | lsof names `node`/`node`, ps lines `1234 api` and `1235 web`; before both `Terminal · node`, after `Terminal · api` / `Terminal · web`. `my api` -> `my` and `python3 app.py` -> `python3` share this short-label layout | Yes | Native: same integrated-terminal seed on macOS. Linux cannot invoke the actual Darwin sources | Native before/after at 1440×900 × dark × D1 when a Mac exists | **cannot-verify macos**; synthetic scanner test inspected, not run here |
| D2 Darwin Browser titles | D1 listeners, Idle Browser tab; cards before `node`/`node`, after `api`/`web` | Yes | Native D1 seed with the Browser idle surface; environment-wide list also permits configured matching listeners | Native before/after at 1440×900 × dark × D2 when a Mac exists | **cannot-verify macos** |
| D3 Darwin agent-owned title | `terminal:null`, `agent:{threadId:active}`, title `api`; Servers subtitle `Agent · api`; Browser title `api` | Yes; same string source with distinct owner prefix | Native agent-launched listener inheriting the thread marker, or a labelled fixture overriding owner/scanner services; an actual paid agent is unnecessary for a harness | Native/static row in same desktop/dark configuration; may coexist with D1 | **cannot-verify macos** for native source; no harness capture claimed |
| D4 Darwin long title | Valid slash-free/equals-free token of 96 `W` characters; terminal row and Browser title ellipsize without changing row height | Yes; new title source permits long strings | Native process sets title before listening with sufficient argv storage; labelled harness may supply exact string | Narrow in-app row widths at 1440×900 × dark; record resizing only if claiming the transition | **cannot-verify macos** for native source; optional harness |
| D5 Darwin non-null fallback | lsof `Foo Bar`; alternate ps inputs `/Applications/Foo Bar.app/Contents/MacOS/Foo Bar`, `DEMO_SECRET=synthetic`, `(nginx)`, empty/missing line, whitespace, or failed query. All render `Terminal · Foo Bar` and Browser `Foo Bar` | Yes, fallback guard | Native command/error cases on a Mac; exact failure/path permutations are deterministic only with stubbed ProcessRunner. One visual fixture covers all these non-null fallbacks | One static fallback combination; parser permutations belong to focused behavior tests, not duplicate screenshots | **cannot-verify macos**; table-driven tests inspected for path/assignment/parenthesized/failure cases |
| D6 Darwin null fallback | No usable ps title and absent/empty lsof `c`: `processName:null`; Servers shows `Terminal`/`Agent` without dot; Browser shows `Listening` | Yes as fallback boundary; presentation unchanged | Cannot reliably force missing native lsof name; a labelled scanner/RPC fixture can provide null. A configured-only live HTML URL also reaches Browser `Listening`, without proving the Darwin fallback | Optional labelled harness static null row; configured-only Browser screenshot is an unchanged null-render control | **No native seed established; labelled harness only** for exact combined fallback; not required in addition to native limitation |
| D7 Darwin cache and recovery | First `api`, then same PID retitled `web` while still listening retains `api`; disappear/reappear or release every subscriber/reacquire permits reread. Failed/missing ps read can retry; null result remains cached | Yes, temporal cache behavior | Native controlled listener plus all subscriber lifecycle control; labelled service harness can deterministically exercise scan sequence | **recording**, with explicit initial state, trigger, and resulting label; independent focused scanner test is better for exact cache calls | **cannot-verify macos** for native behavior; no recording claimed |
| H1 optional Linux Darwin-service harness | Stub lsof `p1234/cnode/n*:4321`, ps `1234 api`, platform darwin only inside scanner, register terminal owner; send scanner result through real subscription to both actual UI consumers | Yes, simulated producer | Existing unit tests already inject Platform/ProcessRunner. The production app has no inspected switch for this injection: PATH-only ps stubbing does not select darwin. A dedicated scoped scanner bootstrap/fixture RPC bridge would be needed; not built in this read-only pass. A component mock alone must be labelled component harness, not real-app/native proof | Optional labelled harness captures; **recording** for injected updates. Does not replace native macOS acceptance | **Not available in unmodified real app; optional harness unbuilt**; L1/L2 require no such machinery |
| U1 absent list | No owned listener or configured URL; Servers hidden; Idle Browser with no valid recents says No preview yet. Initial query with no data or error without data shares empty discovery output; no discovery spinner/error banner | No | Empty synthetic thread/environment; remove fixture listeners and use fresh browser history. Fault injection needed for deterministic query failure | Static endpoint; **recording** only for asserting initial load, failure, or disappearance | **Excluded: unchanged**, no additional capture required |
| U2 recent-only Browser | No servers; one valid recent entry plus invalid entries omitted; at most eight valid recents shown | No | Visit a synthetic local page, close listener, reopen fresh Browser tab | Static endpoint; **recording** if proving removal/reappearance of empty state | **Excluded: unchanged** |
| U3 mixed Browser list | Live L2 servers plus one/eight recents; configured match sorts before scanner entries; many servers scroll; favicon present versus missing/error fallback | No layout/control change; server title still covered by L2 | Reuse L2, visit synthetic pages, add project-script preview URL matching a listener; favicon served by synthetic page if desired | Static mixed endpoint; **recording** for scrolling, favicon failure transition, recent removal, or card navigation | **Excluded: unchanged**, no extra cartesian captures |
| U4 paged Servers | Ten owned listeners; 4 -> 8 -> 10 -> 4 rows; Show 4 more, Show 2 more, Show less; thread/environment switch resets | No count/order/control change | Start ten local listener processes in the thread terminal; switch to another synthetic thread/environment | **recording** if exercised | **Excluded: unchanged**; existing browser test covers pagination/thread reset, inspected only |
| U5 row permission/stop affordances | With open denied, row disabled. Stop requires stop permission + capability + PID. Without any one, no control/padding. Hover/focus reveals control; coarse/no-hover shows it. Pending stop spinner disables all stop controls | No permission/control change | Isolated reduced-scope connection, capability fixture, null-PID configured-only row; controlled listener for stop pending | **recording** for hover/focus/pending; static denied/unsupported endpoints can use labelled harness | **Excluded: unchanged** |
| U6 open/navigation/error flow | Plain open versus modified/middle external open; other mouse buttons ignored. Open failure toast; Browser card navigation; active/loading/LoadFailed/download/desktop-ownership branches replace the idle list | No | Same local listeners; controlled success/failure page, Browser backend capabilities; client Mac vs Linux only changes shortcut tooltip | **recording** for clicks, delayed tooltip, navigation or error transitions | **Excluded: unchanged** |
| U7 stop/remove/error flow | Stop success removes row; failed stop retains row and produces error toast; interruption has no failure toast; stop already pending/null PID is ignored | No | Track only fixture PIDs, launch controllable isolated listener; deterministic failure via labelled service harness | **recording** | **Excluded: unchanged** |
| U8 layout/theme/entry gates | Inline vs popover details; compact/essential density, draft, hidden Servers setting, embedded chat omit Servers; light/dark tokens; long labels truncate; Browser list width/scroll vary | No style/gating change | Resize app, adjust details visibility, use draft, open panel through button/keybinding; light theme is a control. Servers row itself stays normally 280px wide | Static endpoints; **recording** for resize/density/theme/panel transitions. L1/L2 choose full-density desktop dark only | **Excluded: unchanged**, no separate theme×width sweep required |
| U9 platform/connection controls | Windows discovery unchanged; Linux /proc or lsof fallback unchanged. Web and desktop use same rows; mobile has no inspected discovery-name renderer. Remote Linux client viewing Darwin server would show Darwin labels | No additional renderer or changed transport | Native/remote host determines scanner OS; changing browser platform alone cannot run new Darwin branch | No extra capture required for unchanged client/connection combinations | **Excluded: unchanged**; native Darwin remains separately limited |

## Concrete real-app seed for required rows

This is a follow-up recipe, not work performed during this read-only audit. Start/reuse an isolated development instance using its own test state. Use a synthetic project and ordinary existing thread, ensure Servers is visible at full density, and run these commands in that thread's integrated terminal (not an unrelated external shell):

```sh
node -e 'process.title="api"; require("http").createServer((req,res)=>{res.setHeader("Content-Type","text/html");res.end("<!doctype html><title>API fixture</title><p>API fixture</p>")}).listen(4321,"127.0.0.1")' &
api_fixture_pid=$!
node -e 'process.title="web"; require("http").createServer((req,res)=>{res.setHeader("Content-Type","text/html");res.end("<!doctype html><title>Web fixture</title><p>Web fixture</p>")}).listen(4322,"127.0.0.1")' &
web_fixture_pid=$!
```

If these ports are occupied, choose unused ports and update the fixture labels. Capture L1 after both rows are settled; capture L2 in a fresh Idle Browser tab before clicking either entry. Keep existing process state out of the frame. Track and stop only the two returned fixture PIDs afterward. Two separate captures suffice; one unobscured frame showing both surfaces also suffices if both remain readable. No mandatory recording is introduced by the label-only change: setting up a stable fixture is different from asserting a transition. Any optional temporal row must use a recording.

## Minimum set and conclusion

Required set: `{1440×900} × {dark} × {L1, L2}` = **two static capture endpoints**, showing the real app on the requested local revision. Record the revision, Linux host, viewport, theme, and Linux no-regression scope in evidence captions. A baseline at origin/main is expected to match on Linux and must not be described as proving the native fix. Darwin before/after remains `cannot-verify macos`; an honest labelled harness may supplement it but cannot convert it to native verification. Unchanged U rows are inventoried controls and do not inflate this small change's minimum set.

Coverage: full two-file diff, scanner producer/cache/fallback paths, subscription/contract path, both web label renderers and their direct callers, desktop reuse/mobile absence, supplied PR evidence and its revision mismatch. No runtime tests or visual captures were run in this pass. Audit completed within the 40-minute budget.

FRICTION:
- infra | Linux VM cannot run native Darwin ps/lsof | A macOS host for the native rows; preserve cannot-verify macos meanwhile.
- forge | Published body/checks describe an older pushed revision rather than the requested local head | Refresh public evidence after the local revision is published; keep this pass tied to the requested checkout.

VERDICT: INSUFFICIENT L1 Linux Servers capture; L2 Linux Browser Local servers capture
