umputun / agterm / 37249816182

94%

push

github

feat(control): address a pane by its stable id for text, type and cursor (#698)

`session type` and `surface cursor` now take `--pane-id`, the stable token a shell sees as `$AGTERM_PANE_ID`, and `tree --json` lists it as `surfaces[].paneID`. A script can read a pane, check its caret and type into it by that id, and the id keeps naming the same terminal after `session swap` or split-pane promotion. `session text` and `session type` report the pane they acted on as `result.pane`, and `surface cursor` returns the resolved surface id in `result.id`.

`session text`, `session type` and `session restore` share one rule: a live id wins over `--pane`, an empty id counts as absent, and an unknown id without an explicit `--pane` fails with `unknown pane id: <id>`. `session status` keeps its fallback to the role. `surface cursor --pane-id` takes a session target and has no fallback. `session type` keeps the id while the pane becomes ready: a pane that moved during the wait is typed into where it is, and one that is gone gets the unknown-id error, so the keystrokes cannot reach another terminal.

**Behavior change:** `session text --pane-id <unknown>` with no `--pane` used to read the on-screen pane and answer ok. It is now an error. Target selection without `--pane-id` is unchanged. `ControlActions` keeps the two-argument cursor requirement and defaults the new overload, so an outside conformer builds unchanged and refuses `surface.cursor --pane-id` as unsupported.

19 of 25 new or added lines in 8 files covered. (76.0%)

14780 of 15774 relevant lines covered (93.7%)

2587049.54 hits per line