feat: expose per-surface TTY in tree output

[grimmerk]

Summary

Expose per-surface TTY name in the system.tree response. Reads from the existing surfaceTTYNames dictionary — no new data collection, just surfacing what's already tracked internally.

Changes

TerminalController.swift — add tty field to surface items in v2TreeWorkspaceNode:

"tty": v2OrNull(workspace.surfaceTTYNames[panel.id])

CLI/cmux.swift — show tty=<value> in text tree output for surfaces with a registered TTY.

Before / After

Before:

└── surface surface:1 [terminal] "session title" [selected] ◀ active

After:

└── surface surface:1 [terminal] "session title" [selected] ◀ active tty=ttys010

Use case

Enables external tools to cross-reference process TTYs (ps -o tty=) with cmux surfaces for identifying which terminal tab a specific process is running in. This is the cmux equivalent of iTerm2's tty of session AppleScript property.

Test proof

Dev build (reload.sh --tag codev-tty), running tree --all:

window window:1 [current] ◀ active
├── workspace workspace:3 "grimmer@MacBookAirK15:~/git/codev" [selected] ◀ active
│   └── pane pane:3 [focused] ◀ active
│       └── surface surface:3 [terminal] "grimmer@MacBookAirK15:~/git/codev" [selected] ◀ active tty=ttys006
├── workspace workspace:4 "✳ hi codev 16"
│   └── pane pane:4 [focused]
│       └── surface surface:5 [terminal] "✳ hi codev 16" [selected] tty=ttys010
└── workspace workspace:5 "grimmer@MacBookAirK15:~/git/codev"
    └── pane pane:5 [focused]
        └── surface surface:6 [terminal] "grimmer@MacBookAirK15:~/git/codev" [selected] tty=ttys020

Surfaces without registered TTY (e.g. newly created, no shell integration) show no tty= field — same output as before.

🤖 On behalf of @grimmerk — generated with Claude Code

[vercel]

@grimmerk is attempting to deploy a commit to the Manaflow Team on Vercel.

A member of the Team first needs to authorize it.

[coderabbitai]

📝 Walkthrough

Walkthrough

The code adds a new tty field to the V2 workspace surface payload in TerminalController, exposing the per-surface TTY name. The CLI then conditionally displays this TTY information in the rendered surface label after existing markers.

Changes

Cohort / File(s)	Summary
TTY Field Addition in Workspace Payload Sources/TerminalController.swift	Introduces a new "tty" field to the V2 workspace tree/surface payload, populated from workspace.surfaceTTYNames[panel.id] with null encoding support via v2OrNull(...).
TTY Display in CLI Surface Labels CLI/cmux.swift	Conditionally appends a tty=<value> token to the rendered surface label within treeSurfaceLabel when the surface has a non-empty TTY string value.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• Add hidden CLI command for live terminal debugging #1599: Shares the same surface TTY plumbing—TerminalController exposes the per-surface tty field and CLI renders it in surface listings.

Poem

🐇 ✨ A tty for each surface so fine,
Through TerminalController it does align,
CLI now renders what's on display,
Surface labels brighten the dev's way! 🎉

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The PR title clearly and concisely describes the main change: exposing per-surface TTY information in tree output, which is the primary objective of this changeset.
Description check	✅ Passed	The PR description provides a clear summary of changes, includes before/after examples, explains the use case, and provides test proof with example output.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[greptile-apps]

Greptile Summary

This PR exposes the per-surface TTY device name (already tracked in Workspace.surfaceTTYNames) through the system.tree JSON API and the tree --all text output. No new data is collected — the change is purely a read-through of an existing dictionary.

Key changes:

• Sources/TerminalController.swift: adds "tty": v2OrNull(workspace.surfaceTTYNames[panel.id]) to each surface node in v2TreeWorkspaceNode, following the exact same nullable pattern as pane_id, selected_in_pane, and index_in_pane.
• CLI/cmux.swift: appends tty=<value> to the text tree label in treeSurfaceLabel only when the value is a non-empty string; positioned after ◀ here and before the browser URL, consistent with the surrounding label-building logic.

Confidence Score: 5/5

• Safe to merge — minimal, read-only change exposing already-tracked internal state with no new risk surface.
• The change reads from an existing dictionary (surfaceTTYNames) that is already populated, pruned, and tested. Both additions follow established patterns exactly (nullable JSON field via v2OrNull, guarded text append in treeSurfaceLabel). No threading concerns — TTY data is accessed in the same context as all other workspace fields in v2TreeWorkspaceNode. No logic branches, no new storage, no API breakage (null is added for surfaces without a TTY, consistent with adjacent fields).
• No files require special attention.

Important Files Changed

Filename	Overview
Sources/TerminalController.swift	Adds "tty": v2OrNull(workspace.surfaceTTYNames[panel.id]) to the surface item dict — reads existing data, uses the same null-handling pattern as adjacent fields, always present in JSON (null when no TTY registered).
CLI/cmux.swift	Appends tty=<value> to the text tree label only when the field is a non-empty string; placement after ◀ here and before browser URL is consistent with the rest of the label-building logic.

Sequence Diagram

sequenceDiagram
    participant Shell as Shell (cmux-init)
    participant TC as TerminalController
    participant WS as Workspace.surfaceTTYNames
    participant API as system.tree (JSON)
    participant CLI as tree --all (text)

    Shell->>TC: report_tty <ttyName> [--panel=UUID]
    TC->>WS: surfaceTTYNames[panelId] = ttyName

    Note over TC,WS: TTY stored in-memory, no new collection

    TC->>API: v2TreeWorkspaceNode()
    API->>WS: surfaceTTYNames[panel.id]
    WS-->>API: "ttys010" | nil
    API-->>TC: { ..., "tty": "ttys010" | null }

    TC->>CLI: treeSurfaceLabel()
    CLI->>WS: surface["tty"] as? String
    WS-->>CLI: "ttys010"
    CLI-->>TC: "surface:1 [terminal] "title" [selected] ◀ active tty=ttys010"

Loading

_{Reviews (1): Last reviewed commit: "feat: expose per-surface TTY in tree out..." | Re-trigger Greptile}

[cubic-dev-ai]

No issues found across 2 files

[lawrencecchen]

Thank you for the contribution!