stablyai / stablyai/orca

[Feature]: Name remote terminal sessions in the Resource Manager instead of showing raw pids

Open
#16,005 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
69.7k
Forks
4.5k
Avg merge
15h 28m
Merged PRs (30d)
471

Description

### Problem

With the Resource Manager showing remote runtime hosts (#15984 / #16000), sessions on a remote host render as `pid 712692` instead of a terminal name:

```
docs-pass · REMOTE 1.3% 95.7 MB
pid 712692 1.3% 86.3 MB
pid 713986 0.0% 9.4 MB
```

Local rows are unaffected, and remote rows are fine *while you have that workspace open* — the label resolves from the client's own tab. The gap shows up exactly when the panel is most useful: looking at a host whose workspaces you are not currently viewing, which is the reason to look at another host's resource usage in the first place.

### Why

`resolveSnapshotSessionLabel()` in `mergeSnapshotAndSessions.ts` resolves a name by walking this client's tab store via `paneKey`, then falls back to `pid `. For a remote host there is often no local tab bound to that session, so the fallback is all that is left.

The remote payload cannot help either: `SessionMemory` in `src/shared/process-stats-types.ts` carries only `sessionId`, `paneKey`, `pid`, `cpu` and `memory`. `diagnostics.memory` never had a reason to include a title, because until now the only consumer was the machine that already owned the tabs.

For local sessions the name comes from `pty.listSessions()`, whose rows carry `title` and `cwd`. That list describes this machine only, so it says nothing about a remote host's terminals — the merge deliberately ignores it under a remote host.

### Proposal

The host already knows the answer. `terminal.list` is an existing runtime RPC returning `RuntimeTerminalSummary[]`, and each row carries both `ptyId` and `title` — exactly the mapping needed to name a snapshot session.

- Add an optional `title` to `SessionMemory`. Optional, so an older host that never sets it still decodes.
- After fetching a remote snapshot, enrich its sessions from that host's `terminal.list`, keyed by `ptyId`.
- Prefer the client's own tab title where one exists (unchanged), then the host-reported title, then `pid `.

Two things to be careful about:

- **Cost.** The panel polls every 2s and a second RPC per tick is not free, especially with many terminals. Titles change rarely, so the terminal list should be cached per host with a short TTL and requested without visual layouts (~31% of the payload) or fresh liveness probes.
- **Degradation.** A host that fails or does not answer `terminal.list` must not fail the snapshot. Losing titles should cost the labels only, leaving today's `pid ` behaviour intact.

### Scope

Naming only. This does not make remote rows clickable or killable — navigation still needs a local tab, and kill needs `terminal.stop` routing plus the live/unverifiable/exited verdicts from `docs/reference/ssh-execution-boundary.md`.

Depends on #16000, which introduces the remote snapshot path this would enrich.

Contributor guide

Open the contributing guide

Research direction

Start with resolveSnapshotSessionLabel() in mergeSnapshotAndSessions.ts, SessionMemory in src/shared/process-stats-types.ts, and the existing terminal.list RPC returning RuntimeTerminalSummary[]. Trace the remote snapshot path from #16000 and determine where host terminal titles can be cached and merged. Done means remote sessions prefer local tab titles, then host-reported titles, then pid labels, while terminal.list failures leave snapshots working unchanged.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
api, backend, devtools
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
58/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.