microsoft / microsoft/vscode

API: Provide a stable terminal session ID across window reloads

Open
#327,326 2 comments 5 reactions 1 assignee Claimed by @anthonykim1 View on GitHub
feature-request terminal
Dominant language
TypeScript
Stars
193k
Forks
42.4k
PR merge metrics
PR metrics pending

Description

Extensions can observe terminals through `vscode.window.terminals` and `vscode.window.onDidOpenTerminal`, but there is no public stable identity that allows an extension to correlate the same logical terminal session before and after `Developer: Reload Window`.

After a reload, VS Code may successfully reattach the existing persistent terminal process, but the extension host receives a new `Terminal` object. None of the currently public properties can be used as identity:

- `Terminal.processId` identifies a process, not a logical terminal session. It may remain the same after a window reload, but it can change when VS Code revives a persistent session by creating a new process.
- `Terminal.name` and the terminal tab title are mutable and can change to the foreground process name.
- `cwd` is neither unique nor guaranteed to be available through `Terminal.creationOptions`.
- Multiple terminals may intentionally have identical creation options.
- Extension-provided values in `TerminalOptions.env` are not reliably available in `Terminal.creationOptions` after persistent reattach.

This prevents an extension that manages multiple long-lived terminals from restoring its own state without guessing based on process IDs, titles, working directories, or process environment inspection.

## Proposed API contract

Please expose an opaque terminal session ID on `Terminal`, for example:

```ts
interface Terminal {
/**
* An opaque identifier for this logical terminal session.
*
* The value remains stable when the terminal is restored or reattached
* across window and extension-host reloads.
*/
readonly sessionId: string;
}
```

The exact property name is not important. The required behavior is:

1. Every newly created logical terminal session receives a unique ID.
2. The ID is available on the `Terminal` returned by `createTerminal`, in `window.terminals`, and in `onDidOpenTerminal`.
3. The ID remains unchanged across `Developer: Reload Window` when VS Code restores or reattaches that terminal.
4. The ID also represents the same logical session if persistent-session revival recreates the underlying process and therefore changes `processId`.
5. Once a terminal session is disposed, a subsequently created terminal gets a different ID.
6. The value is opaque. It does not need to expose a PTY ID, process metadata, environment variables, or other internal reconnection data.

## Example use case

An extension creates several terminal editors for long-running development environments and stores per-terminal state:

```ts
const terminal = vscode.window.createTerminal({
name: 'Managed terminal',
location: {
viewColumn: vscode.ViewColumn.Active,
preserveFocus: true
}
});

await extensionContext.globalState.update(
`terminal.${terminal.sessionId}`,
persistedExtensionState
);
```

After a window reload, the extension should be able to enumerate `window.terminals`, read the same `sessionId`, and reconnect its state to the already restored terminal without launching a replacement process.

## Why an opaque ID is preferable

This capability does not require exposing the terminal's resolved process environment or internal reconnection metadata. It gives extensions identity without encouraging process inspection or overloading mutable presentation fields such as the terminal name.

## Related issues

- https://github.com/microsoft/vscode/issues/237127 reports that `Terminal.creationOptions.shellPath` is incorrect after window reload.
- https://github.com/microsoft/vscode/issues/287059 reports terminal titles not being preserved after reload.
- https://github.com/microsoft/vscode/issues/163873 discusses the inability to determine whether a terminal was created by an extension.
- https://github.com/microsoft/vscode/issues/124584 tracks inconsistent `Terminal.creationOptions` behavior.

Those issues cover individual properties or ownership detection. This request is specifically for stable identity of a logical terminal session across persistent restore and reattach.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.