Hierarchical Context Signalling (OSC 3008)

OSC 3008 is the UAPI hierarchical context signalling protocol. It lets programs announce when execution enters or leaves a nested context, such as a container, a virtual machine, an SSH session, a sudo elevation, or a subshell. Each context has a unique identifier and an open set of metadata fields. Contexts nest naturally: an SSH session inside a container inside a shell session forms a stack inside the terminal.

The first field selects the action and carries the context ID. Trailing fields are semicolon-separated key=value pairs of metadata.

Action form	Meaning
start=<id>	Begin a new context (or update / re-enter an existing one).
end=<id>	Terminate the context with the given ID.

The <id> is a stable identifier for the context. The specification requires it to be 1-64 characters, all in the printable ASCII range 0x20-0x7e. Wintty's parser enforces both bounds; sequences with an empty, oversized, or non-printable ID are dropped.

Both start= and end= sequences may carry additional key=value metadata after the context ID. Unknown keys are ignored per the spec. Wintty's parser exposes the following keys to the terminal layer:

Key	Type	Meaning
type	enum	Context kind. See Context types.
user	string	Username for this context.
hostname	string	Hostname for this context.
machineid	string	Persistent machine identifier (/etc/machine-id).
bootid	string	Boot-instance identifier.
pid	unsigned int	Process ID of the context root.
pidfdid	unsigned int	Pidfd identifier for the context root.
comm	string	Short process command name.
cwd	string	Working directory.
cmdline	string	Full command line.
vm	string	VM name (when type=vm).
container	string	Container name (when type=container).
targetuser	string	Target user (e.g. for elevate or SSH).
targethost	string	Target host (e.g. for SSH).
sessionid	string	Logical session identifier.

Key	Type	Meaning
exit	enum	success, failure, crash, or interrupt.
status	unsigned int	Exit status integer (typically 0-255 for processes).
signal	string	Terminating signal name (e.g. SIGKILL).

The type= field is normalized to one of:

boot, container, vm, elevate, chpriv, subcontext, remote, shell, command, app, service, session.

Any other value is treated as unset.

Announce entry into a systemd-nspawn container named foobar launched by user lennart on host zeta:

printf '\033]3008;start=bed86fab93af4328bbed0a1224af6d40;type=container;user=lennart;hostname=zeta;comm=systemd-nspawn;container=foobar\033\\'

Announce that the container exited successfully:

printf '\033]3008;end=bed86fab93af4328bbed0a1224af6d40;exit=success;status=0\033\\'

Note

OSC 3008 is parsed but not yet acted on in Wintty. The parser validates the action, the context ID, and every metadata field listed above (the test suite covers all spec examples), but the terminal does not currently maintain a context stack or expose context state to the UI. Programs may safely emit OSC 3008; the sequence will be silently consumed by current desktop builds and become meaningful in a future release without any wire-format change.

• Working directory reporting (OSC 7): a simpler protocol for the common "where am I" case.
• Semantic prompt marks (OSC 133): for marking command boundaries within a shell context.
• The UAPI specification for the authoritative protocol definition.