linux(socket): add surface.report_tty (Sprint A #8)

[Jesssullivan]

Summary

Implements the v2 surface.report_tty RPC on Linux. Mirrors the
workspace_id/surface_id resolution pattern from handleSurfaceSendText
so callers may omit either or both ids. Trims surrounding whitespace and
rejects empty tty_name. Stores the TTY name onto Panel.tty_name using
the allocate-then-free pattern (avoids dangling on allocation failure)
and echoes {workspace_id, surface_id, tty_name}.

The Linux build does not yet have a PortScanner / remote workspace
plumbing equivalent to macOS, so this is metadata-only — the value is
recorded and visible to subsequent surface.list / pane.list responses
that may want to surface it, but no port scan is triggered.

What's added

• cmux-linux/src/socket.zig: .{ "surface.report_tty", handleSurfaceReportTty } dispatch entry + handleSurfaceReportTty (~50 LOC), placed next to handleSurfaceClearHistory.
• tests_v2/test_surface_report_tty.py: round-trip test covering
  • default surface fallback (no surface_id)
  • explicit surface_id targeting
  • whitespace trimming
  • missing / empty / whitespace-only tty_name errors
  • invalid workspace_id / surface_id errors

Linux vs macOS shape

macOS returns {workspace_id, workspace_ref, surface_id, surface_ref, tty_name, [pending]}.
Linux returns the same {workspace_id, surface_id, tty_name} core triple
that other Linux v2 surface handlers already return — _ref and the
pending remote-workspace flag are intentionally omitted because they
have no Linux equivalent yet. Tests assert the Linux shape.

Test plan

• Socket tests CI (self-hosted honey runner) is green
• Distro tests CI is green
• (Local, optional) nix develop --command bash -c 'cd cmux-linux && zig build -Doptimize=ReleaseFast'

Refs #220 (Sprint A item #8).

[greptile-apps]

Greptile Summary

Implements the Linux-side surface.report_tty socket RPC, storing a trimmed TTY name on Panel.tty_name using the allocate-then-free pattern already established in the file, and echoing {workspace_id, surface_id, tty_name}. Workspace/surface resolution faithfully mirrors handleSurfaceSendText. The test covers the main success paths, whitespace trimming, and error cases.

Confidence Score: 5/5

Safe to merge; implementation is correct and all remaining findings are P2 style notes already captured in prior review threads.

Core logic faithfully mirrors the established handleSurfaceSendText pattern. Allocation/update/response flow is correct, no new P0 or P1 issues found. The two substantive concerns (defer inconsistency, misleading error message) and the missing surface_id-only test were all raised in previous threads.

No files require special attention.

Important Files Changed

Filename	Overview
cmux-linux/src/socket.zig	Adds handleSurfaceReportTty (~55 LOC) next to handleSurfaceClearHistory; resolution logic is an exact copy of handleSurfaceSendText, allocation/update pattern is correct, response JSON is well-formed.
tests_v2/test_surface_report_tty.py	Covers default-surface fallback, explicit surface_id, whitespace trimming, and error cases; missing test for surface_id-only resolution (no workspace_id), which leaves the findSurfaceGlobal double-lookup path untested (noted in prior thread).

Sequence Diagram

sequenceDiagram
    participant C as Caller (CLI/Python)
    participant S as socket.zig dispatcher
    participant H as handleSurfaceReportTty
    participant TM as TabManager
    participant WS as Workspace
    participant P as Panel

    C->>S: surface.report_tty {workspace_id?, surface_id?, tty_name}
    S->>H: dispatch(alloc, params)

    alt workspace_id provided
        H->>TM: findWorkspaceById(workspace_id)
        TM-->>H: WorkspaceLookup
    else surface_id only
        H->>TM: findSurfaceGlobal(surface_id)
        TM-->>H: {id, ws}
    else neither
        H->>TM: selectedWorkspace()
        TM-->>H: *Workspace
    end

    alt surface_id provided + workspace known
        H->>WS: findSurfaceInWorkspace(surface_id)
        WS-->>H: target_id (u128)
    else surface_id only (no workspace_id)
        H->>TM: findSurfaceGlobal(surface_id) [2nd call]
        TM-->>H: found.id
    else no surface_id
        H->>WS: focused_panel_id
        WS-->>H: target_id (u128)
    end

    H->>H: trim(tty_name), reject if empty
    H->>WS: panels.getPtr(target_id)
    WS-->>H: **Panel
    H->>WS: ws.alloc.dupe(tty_name) to new_tty
    H->>P: free old tty_name, set tty_name = new_tty
    H->>H: build JSON response
    H-->>C: {workspace_id, surface_id, tty_name}

Loading

_{Reviews (2): Last reviewed commit: "linux(socket): add surface.report_tty re..." | Re-trigger Greptile}