fix(server): macOS server labels honor process titles#32931
Problem
On macOS the thread Servers panel labels every listener with lsof's c field, which is the kernel's exec-time p_comm. process.title (Node) and setproctitle (Python) only rewrite argv on macOS, so two Node servers titled api and web both read Terminal · node, and every Python server reads Terminal · Python. Linux already shows the titles because /proc/<pid>/comm and Linux lsof follow them.
Change
On darwin, the scanner labels each listener with argv[0] from ps -ww -o pid=,command= -p <pids>. This call has no -E, so it never reads a process environment. It runs once per scan, only for listener pids not yet cached, and its result lives in a per-pid title cache (titlesRef). That cache is pruned to the current listeners on each scan and cleared, together with the agent-thread cache, while no client retains the scanner.
lsof's name stays the label when:
- argv[0] contains a
/, because it is then the executable path, which may contain spaces (.appbundles); - argv[0] contains a
=. A process that sets an empty title zeroes argv, and Apple'spsthen skips past it into the environment, so this rule keeps environment values out of the label; - argv[0] starts with
(, which is howpsshows the exec-time name of another user's process whose argv it cannot read; psfails or prints nothing for the pid.
The agent-thread lookup (ps -E on macOS, /proc/<pid>/environ on Linux) is unchanged from main: it runs only when an agent may own a server, and only for pids without a terminal owner. A terminal owner still takes precedence. Linux and Windows discovery are unchanged.
Other behaviour changes on macOS:
- Python labels: a Python server started as
python3 app.pynow readspython3instead ofPython. - Titles with spaces: only the first word shows.
"my api"readsmy, while Linux shows up to 15 characters. - When the title is read: once per pid. A title set after the process starts listening keeps the earlier name until the pid stops listening.
- Titles containing
/: these fall back tolsof's name, so@workspace/apireadsnode. - Tracing: a new
PortDiscovery.readTitlesspan is recorded on macOS scans that runlsof.
Scope and approval
Fixes pingdotgg/t3code#32918
Verification
vp test run apps/server/src/preview/PortScanner.test.ts: 35/35 pass at head.- Regression, red on main:
labels a terminal's servers on macOS by their process titlescovers two terminal-owned listeners, withlsofreportingnodeandpsreportingapi/web. Against main'sPortScanner.tsit fails withprocessName: "node"where"api"/"web"is expected. Across two scans it also asserts exactly onepscall,-ww -o pid=,command= -p 1234,1235, so terminal-owned pids never reachps -Eand titles are read once per pid. That assertion fails if the title read carries-E. - Fallbacks:
keeps lsof's name on macOS for $sourcecovers an executable path with spaces, the environmentpsprints after an empty title, another user's(nginx), and a failedps. Each row fails without its rule.
- Regression, red on main:
- Changed checks:
vp run check:changedpasses (format, lint, knip, typecheck of 3 packages, tests). - Reviews: two independent review rounds; the second round found no open issues.
Evidence
Linux no-regression rows (the Linux path is unchanged, so before and after should match). Before = b48b8ea2a0 (merge-base), after = f0899db491 (the same scanner code as this head). Environment: T3 preview browser, Chrome 157 on Linux, no device emulation, DPR 2, font scaling 100%, full viewport as labelled. Each sheet shows Before / After / Diff0 (zero threshold, 255× amplified) / DiffT (channel delta > 16/255).
| Row | 1440×900 dark | 1440×900 light | 390×900 dark |
|---|---|---|---|
L1: Servers panel, Terminal · api / Terminal · web | sheet-L1-1440x900-dark.png | sheet-L1-1440x900-light.png | sheet-L1-390x900-dark.png |
L2: Browser → Local servers, api / web | sheet-L2-1440x900-dark.png | sheet-L2-1440x900-light.png | sheet-L2-390x900-dark.png |
What else changed: nothing visible; all six pairs have zero changed pixels at zero threshold. An independent rebuild of L2 1440×900 dark matched the delivered capture byte for byte.
Evidence index · Fixture matrix · Scripts: seed.browser.js, start-dev.sh, rpc.browser.js, views.browser.js, prepare.browser.js, capture.functions.js, settle.py, diffs.py, stop.browser.js
Not checked: cannot-verify macos. No macOS host was available, so the native ps -ww -o pid=,command= output for a retitled Node or Python process, another user's process, and an empty title has not been observed. The tests encode Apple's ps behaviour as read from its source (adv_cmds/ps/print.c). Someone with a Mac can confirm by running the issue's two servers in a T3 terminal and checking that the Servers panel reads Terminal · api and Terminal · web.
AI-assisted; verified with the tests and tools listed above.
Checks
Added 5 commits
- fix(server): macOS server labels never show an environment assignment5059c5d
- Merge remote-tracking branch 'origin/main' into fix/issue-3291850ebf2b
- refactor(server): scope macOS title reads to darwin and trim argv[0]5dfac96
- fix(server): macOS server labels honor process titlesd442af0
- test(server): reproduce macOS server labels ignoring process.title (#32918)edbdf83
Approvability
Verdict: Approved at 4cd4d46
Macroscope's review found this PR approvable — macOS server labels now use process titles when available, falling back to existing names if inspection fails. The change is confined to display metadata and leaves server ownership and process controls unchanged.
You can add or adjust custom eligibility rules. Learn more.
Thread transfer impact
✅ Thread transfer remains within every enforced ceiling.
| Provider | Metric | Main baseline | This PR | Impact | PR ceiling | |
|---|---|---|---|---|---|---|
| Codex | Total thread wire | 5.0 KiB | 5.0 KiB | 0 B (0.0%) | 6.8 KiB | ✅ |
| Codex | Thread snapshot wire | 3.8 KiB | 3.8 KiB | 0 B (0.0%) | 4.9 KiB | ✅ |
| Codex | Live turn WebSocket wire | 1.2 KiB | 1.2 KiB | 0 B (0.0%) | 2.0 KiB | ✅ |
| Codex | Live turn WebSocket decoded | 21.5 KiB | 21.5 KiB | 0 B (0.0%) | 24.4 KiB | ✅ |
| Codex | Live turn messages | 1 | 1 | 0 (0.0%) | 8 | ✅ |
| Claude | Total thread wire | 5.0 KiB | 5.0 KiB | 0 B (0.0%) | 6.8 KiB | ✅ |
| Claude | Thread snapshot wire | 3.8 KiB | 3.8 KiB | 0 B (0.0%) | 4.9 KiB | ✅ |
| Claude | Live turn WebSocket wire | 1.2 KiB | 1.2 KiB | 0 B (0.0%) | 2.0 KiB | ✅ |
| Claude | Live turn WebSocket decoded | 21.9 KiB | 21.9 KiB | 0 B (0.0%) | 24.4 KiB | ✅ |
| Claude | Live turn messages | 1 | 1 | 0 (0.0%) | 8 | ✅ |
Baseline: 871b009 · PR result: 4cd4d46 · Source CI: success
Scenario and decoded snapshot size
10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.
- Codex decoded thread snapshot: 108.5 KiB
- Claude decoded thread snapshot: 108.8 KiB
Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.
Walkthrough
-
On macOS, the scanner reads process titles for listener PIDs and uses a usable title as the discovered server name. When no usable title is available, it uses the name reported by lsof. Tests cover repeated scans and fallback cases.
Changes: Listener process title resolution
Layer / File(s) Summary Process title reading and parsing
apps/server/src/preview/PortScanner.tsThe scanner parses process titles from psoutput, caches titles for current listener PIDs, and prefers a cached title over the lsof process name.Listener integration and validation
apps/server/src/preview/PortScanner.ts,apps/server/src/preview/PortScanner.test.tsOn macOS, the scanner reads titles after lsof succeeds and passes them to listener parsing. It clears cached titles when retention ends. Tests cover repeated scans, batched PID queries, and fallback to lsof names. Estimated code review effort: 3 (Moderate) | ~20 minutes
Change: Bug fix · Severity of issue fixed: Low
Possibly related PRs
- pingdotgg/t3code#32920: Uses
psprocess data to address the same macOS server-label issue. - pingdotgg/t3code#22542: Adds agent attribution and displays the discovered server's process source in the Servers panel. This PR changes the
processNameused for discovered listeners.
Suggested reviewers:
t3dotgg,voltcrash - pingdotgg/t3code#32920: Uses
Merge Risk: External image Low · up to 4cd4d
-
Server labels fall back to lsof when title lookup fails. Persistent failures may cause repeated lookups, but the evidence does not establish a material barrier to merging.
Pre-merge checks: Passed 4
-
Check name Status Explanation Title check Passed The title clearly summarizes the main change: macOS server labels now use process titles. Description check Passed The description covers the problem, change, scope, and focused verification, including the macOS limitation. It links the issue and reports test results. It does not name the AI model and harness, as … Linked Issues check Passed Issue #32918requires macOS Servers-panel labels to reflect Node process titles. At head, the scanner reads uncached Darwin listener PIDs withps -ww -o pid=,command= -p, accepts valid argv[0] title…Out of Scope Changes check Passed The changes remain within issue #32918. Separate title and agent-thread caches, fallback handling, tracing, and test updates support the requested labels or preserve existing ownership behavior. No un…Full details: Description check
-
Explanation
The description covers the problem, change, scope, and focused verification, including the macOS limitation. It links the issue and reports test results. It does not name the AI model and harness, as the template requests when an agent was used.
Full details: Linked Issues check
-
Explanation
Issue
#32918requires macOS Servers-panel labels to reflect Node process titles. At head, the scanner reads uncached Darwin listener PIDs withps -ww -o pid=,command= -p, accepts valid argv[0] titles, and falls back to thelsofname for rejected or unavailable values. Tests cover terminal-ownedapiandweblabels, one read across repeated scans, and fallback cases. The incremental changes separate title caching from agent-thread lookup and keep agent-thread queries onps -Eonly when needed. Native macOS behavior remains unverified, but the issue and tests provide evidence for the expectedpsbehavior.
Full details: Out of Scope Changes check
-
Explanation
The changes remain within issue
#32918. Separate title and agent-thread caches, fallback handling, tracing, and test updates support the requested labels or preserve existing ownership behavior. No unrelated change is evident.
-
Finishing Touches
-
Generate docstrings
-
- Commit to this branch
- Create a new PR
Generate unit tests (beta)
-
- Commit to this branch
- Create a new PR
-
- Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts
Usage-based review receipt
- Mode: Continue automatically
- Reviewed files: 2
- Charged: $0.50
- View usage details
Note
This review was completed with usage-based billing: files reviewed beyond your plan's included limits are billed at $0.25/file. View usage-based billing.
Worker16 independent review of exact head 50ebf2b9ceebba8c67276e68ed7415f9bf230485. Reviewer is separate from author juliusmarminge; temporary same-family review is permitted by the operator's current #1899 policy.
P2 privacy boundary: on macOS, readsTitles makes resolveListeners pass every lsof listener PID to readLaunches, which runs ps -E -ww -o pid=,command=. The -E output appends the complete process environment. Before this PR, the same ps -E read was gated on agentsPossible and filtered to PIDs without a terminal owner. This change now reads the environments of terminal-owned and unrelated listener processes on every macOS scan, even when no agent attribution is needed. Environment values commonly contain API keys and tokens. ProcessRunner returns stdout to this caller and does not persist/log it in the inspected path, so I am not claiming an observed disclosure; the new source path nevertheless broadens sensitive local-process access unnecessarily. Use a separate no-environment process-title query (for example ps -o pid=,comm=) and retain ps -E only for the prior narrowly scoped agent-thread lookup. Add a regression proving terminal-owned listener titles do not invoke ps -E and that agent attribution remains limited to unowned PIDs.
Exact-head validation: normal PR CI #42478719657 is SUCCESS, but I read all eight Test Server shard logs and the Test job log; none invokes apps/server/src/preview/PortScanner.test.ts. The added regression is authored but not executed by this run. Ensure the changed module is selected by normally admitted exact-head CI; do not count unrelated passing shards as execution of this regression.
Current main ade473018d32003658b7d38693e083ee2e314bd8 is two commits beyond the PR merge base; the two main-only commits do not overlap either changed path. Forward-integrate normally and obtain fresh exact-head CI after the correction. This review does not require physical macOS acceptance as a blanket source-merge veto; live desktop acceptance remains NOT RUN.
Added 4 commits
External image Additional comments: 1
apps/server/src/preview/PortScanner.ts: 1
906-912: External image Trivial · Stability & AvailabilityExternal image Unverified finding Verification ran but could not confirm this finding. It is shown for review, not as a verified issue.
Failed
pscaches no title, so each scan retries it, but the read is bounded.If
psfails,readis empty.readTitlesstores no entry for those PIDs. The next poll runspsagain for every uncached PID, every 3 seconds. The 5-second timeout bounds each run. The behavior is acceptable, but it differs from the success path. Consider a short negative cache ifpsfails often on macOS.The PR description also states that the
pscall uses-E. The code inreadTitlesomits-E. This is correct for titles, because-Eappends the environment. The PR text and the code disagree, so confirm that the description is stale.
External image Review info
-
External image Run configuration
-
- Source mode: Auto
- Repository: pingdotgg/t3code
- Branch: fix/issue-32918
- File: .coderabbit.config.ts
- Commit: d827216
- Layers: Repository TS config
- Review profile: CHILL
- Plan: Team
- Run ID:
d584aee0-8991-493e-9ad9-72111accb9b8
External image Commits
-
Reviewing files that changed from the base of the PR and between 50ebf2b9ceebba8c67276e68ed7415f9bf230485 and d82721682c47db5ef48875cf2d201061dd8bb28e.
External image Files selected for processing: 2
-
apps/server/src/preview/PortScanner.test.tsapps/server/src/preview/PortScanner.ts
Limit details: You’ve used all 10 included reviews currently available.
External image Review info
-
External image Run configuration
-
- Source mode: Auto
- Repository: pingdotgg/t3code
- Branch: fix/issue-32918
- File: .coderabbit.config.ts
- Commit: d827216
- Layers: Repository TS config
- Review profile: CHILL
- Plan: Team
- Run ID:
d584aee0-8991-493e-9ad9-72111accb9b8
External image Commits
-
Reviewing files that changed from the base of the PR and between 50ebf2b9ceebba8c67276e68ed7415f9bf230485 and d82721682c47db5ef48875cf2d201061dd8bb28e.
External image Files selected for processing: 2
-
apps/server/src/preview/PortScanner.test.tsapps/server/src/preview/PortScanner.ts
Limit details: You’ve used all 10 included reviews currently available.
-
Added 2 commits
External image Additional comments: 1
apps/server/src/preview/PortScanner.ts: 1
562-587: External image Trivial · Performance & Scalability · Low valueExternal image Unverified finding Verification ran but could not confirm this finding. It is shown for review, not as a verified issue.
Failed or empty
psoutput is cached as a permanent title miss.When
psfails,readis empty andEffect.orElseSucceedhides the failure. The loop only stores a title whenread.get(pid)is defined. So an unread pid is not cached, and the next poll retriespsevery 3 seconds.Only the failure case is affected. A pid that
psomits, for example because it exited, is also not cached. A pid thatpsreturns with a null title is cached.For a persistent failure, such as a restricted
ps, the scanner spawnspson every poll for as long as a listener exists. TheagentThreadsRefpath setsagentScanPendingon failure to handle a similar case. This path has no equivalent guard.Consider a bounded retry or a negative-cache entry. This is a minor extra process spawn per poll, so the behavior may be acceptable. Confirm that this is intended.
External image Review info
-
External image Run configuration
-
- Source mode: Auto
- Repository: pingdotgg/t3code
- Branch: fix/issue-32918
- File: .coderabbit.config.ts
- Commit: 4cd4d46
- Layers: Repository TS config
- Review profile: CHILL
- Plan: Team
- Run ID:
77d45dfe-2d8d-47bd-ba71-a4e50d071236
External image Commits
-
Reviewing files that changed from the base of the PR and between 50ebf2b9ceebba8c67276e68ed7415f9bf230485 and 4cd4d465fb560483bca983698689ee9012c77815.
External image Files selected for processing: 2
-
apps/server/src/preview/PortScanner.test.tsapps/server/src/preview/PortScanner.ts
Limit details: You’ve used all 10 included reviews currently available.
External image Review info
-
External image Run configuration
-
- Source mode: Auto
- Repository: pingdotgg/t3code
- Branch: fix/issue-32918
- File: .coderabbit.config.ts
- Commit: 4cd4d46
- Layers: Repository TS config
- Review profile: CHILL
- Plan: Team
- Run ID:
77d45dfe-2d8d-47bd-ba71-a4e50d071236
External image Commits
-
Reviewing files that changed from the base of the PR and between 50ebf2b9ceebba8c67276e68ed7415f9bf230485 and 4cd4d465fb560483bca983698689ee9012c77815.
External image Files selected for processing: 2
-
apps/server/src/preview/PortScanner.test.tsapps/server/src/preview/PortScanner.ts
Limit details: You’ve used all 10 included reviews currently available.
-
The automated pipeline stopped on this pull request and will not merge it:
the proof has no capture anyone can open:
- Permanent environment blocker for this step: the available VM runs Linux, while the reproduction and changed discovery path require macOS. Accessing another machine was explicitly prohibited.
- The base showing Terminal · node for both listeners was not observed.
- The head showing Terminal · api and Terminal · web was not observed.
- No captures or driver scripts were produced; ghdrop upload was not attempted.
It stays open for a person to finish or close.