fix(server): macOS server labels honor process titles#32931

open11
main
fix/issue-32918
opened11d agobyJJulius Marminge
View on GitHubTwo-way sync enabledPR last imported 9d ago

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 (.app bundles);
  • argv[0] contains a =. A process that sets an empty title zeroes argv, and Apple's ps then skips past it into the environment, so this rule keeps environment values out of the label;
  • argv[0] starts with (, which is how ps shows the exec-time name of another user's process whose argv it cannot read;
  • ps fails 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.py now reads python3 instead of Python.
  • Titles with spaces: only the first word shows. "my api" reads my, 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 to lsof's name, so @workspace/api reads node.
  • Tracing: a new PortDiscovery.readTitles span is recorded on macOS scans that run lsof.

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 titles covers two terminal-owned listeners, with lsof reporting node and ps reporting api/web. Against main's PortScanner.ts it fails with processName: "node" where "api"/"web" is expected. Across two scans it also asserts exactly one ps call, -ww -o pid=,command= -p 1234,1235, so terminal-owned pids never reach ps -E and titles are read once per pid. That assertion fails if the title read carries -E.
    • Fallbacks: keeps lsof's name on macOS for $source covers an executable path with spaces, the environment ps prints after an empty title, another user's (nginx), and a failed ps. Each row fails without its rule.
  • Changed checks: vp run check:changed passes (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).

Row1440×900 dark1440×900 light390×900 dark
L1: Servers panel, Terminal · api / Terminal · websheet-L1-1440x900-dark.pngsheet-L1-1440x900-light.pngsheet-L1-390x900-dark.png
L2: Browser → Local servers, api / websheet-L2-1440x900-dark.pngsheet-L2-1440x900-light.pngsheet-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

22 successful · 12 skipped
All checks passed
4cd4d46

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
Synced from GitHub

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.

Synced from GitHub

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

ProviderMetricMain baselineThis PRImpactPR ceiling
CodexTotal thread wire5.0 KiB5.0 KiB0 B (0.0%)6.8 KiB✅
CodexThread snapshot wire3.8 KiB3.8 KiB0 B (0.0%)4.9 KiB✅
CodexLive turn WebSocket wire1.2 KiB1.2 KiB0 B (0.0%)2.0 KiB✅
CodexLive turn WebSocket decoded21.5 KiB21.5 KiB0 B (0.0%)24.4 KiB✅
CodexLive turn messages110 (0.0%)8✅
ClaudeTotal thread wire5.0 KiB5.0 KiB0 B (0.0%)6.8 KiB✅
ClaudeThread snapshot wire3.8 KiB3.8 KiB0 B (0.0%)4.9 KiB✅
ClaudeLive turn WebSocket wire1.2 KiB1.2 KiB0 B (0.0%)2.0 KiB✅
ClaudeLive turn WebSocket decoded21.9 KiB21.9 KiB0 B (0.0%)24.4 KiB✅
ClaudeLive turn messages110 (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.

Synced from GitHub

Explain Change →

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.ts
The scanner parses process titles from ps output, 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.ts
On 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 ps process 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 processName used for discovered listeners.

Suggested reviewers: t3dotgg, voltcrash

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 nameStatusExplanation
Title checkPassedThe title clearly summarizes the main change: macOS server labels now use process titles.
Description checkPassedThe 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 checkPassedIssue #32918 requires macOS Servers-panel labels to reflect Node process titles. At head, the scanner reads uncached Darwin listener PIDs with ps -ww -o pid=,command= -p, accepts valid argv[0] title…
Out of Scope Changes checkPassedThe 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 #32918 requires macOS Servers-panel labels to reflect Node process titles. At head, the scanner reads uncached Darwin listener PIDs with ps -ww -o pid=,command= -p, accepts valid argv[0] titles, and falls back to the lsof name for rejected or unavailable values. Tests cover terminal-owned api and web labels, one read across repeated scans, and fallback cases. The incremental changes separate title caching from agent-thread lookup and keep agent-thread queries on ps -E only when needed. Native macOS behavior remains unverified, but the issue and tests provide evidence for the expected ps behavior.

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

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.

WWladefantrequested changes · 2 inline threads11d ago
Synced from GitHub

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.

apps/server/src/preview/PortScanner.tsline 521Outdated · 50ebf2bOpen thread
……@@ -472,71 +485,80 @@ export const make = Effect.gen(function* PortDiscoveryMake() {
518+ : processRunner
519+ .run({
520+ command: "ps",
521+ args: ["-E", "-ww", "-o", "pid=,command=", "-p", unread.join(",")],
apps/server/src/preview/PortScanner.test.tsline 918Outdated · 50ebf2bOpen thread
……@@ -915,6 +915,106 @@ effectIt.effect.each(["linux", "darwin"] as const)(
915915 },
916916);
917917
918+effectIt.effect("labels a terminal's servers on macOS by their process titles", () => {

Added 4 commits

  • Merge remote-tracking branch 'origin/main' into pr-32931e57a832
  • fix(server): read macOS process titles without the environmentff087c8
  • fix(server): keep lsof's name when ps cannot read another user's argvf0899db
  • Merge remote-tracking branch 'origin/main' into pr-32931d827216
CcoderabbitaiBotreviewed9d ago
Synced from GitHub
External image Additional comments: 1

apps/server/src/preview/PortScanner.ts: 1

906-912: External image Trivial · Stability & Availability

External image Unverified finding Verification ran but could not confirm this finding. It is shown for review, not as a verified issue.

Failed ps caches no title, so each scan retries it, but the read is bounded.

If ps fails, read is empty. readTitles stores no entry for those PIDs. The next poll runs ps again 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 if ps fails often on macOS.

The PR description also states that the ps call uses -E. The code in readTitles omits -E. This is correct for titles, because -E appends the environment. The PR text and the code disagree, so confirm that the description is stale.

External image Review info

External image Run configuration

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.ts
  • apps/server/src/preview/PortScanner.ts

Limit details: You’ve used all 10 included reviews currently available.

Added 2 commits

  • Merge commit '871b00907d' into fix/issue-3291870bff8f
  • chore(server): fit the macOS title parser comment to the comment cap4cd4d46
CcoderabbitaiBotreviewed9d ago
Synced from GitHub
External image Additional comments: 1

apps/server/src/preview/PortScanner.ts: 1

562-587: External image Trivial · Performance & Scalability · Low value

External image Unverified finding Verification ran but could not confirm this finding. It is shown for review, not as a verified issue.

Failed or empty ps output is cached as a permanent title miss.

When ps fails, read is empty and Effect.orElseSucceed hides the failure. The loop only stores a title when read.get(pid) is defined. So an unread pid is not cached, and the next poll retries ps every 3 seconds.

Only the failure case is affected. A pid that ps omits, for example because it exited, is also not cached. A pid that ps returns with a null title is cached.

For a persistent failure, such as a restricted ps, the scanner spawns ps on every poll for as long as a listener exists. The agentThreadsRef path sets agentScanPending on 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

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.ts
  • apps/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.