diff --git a/packages/services/src/kernel/default.ts b/packages/services/src/kernel/default.ts
index 43080d514939..05013bb568af 100644
--- a/packages/services/src/kernel/default.ts
+++ b/packages/services/src/kernel/default.ts
@@ -811,6 +811,18 @@ export class DefaultKernel implements Kernel.IKernel {
 
   /**
    * Handle status iopub messages from the kernel.
+   *
+   * The statuses are:
+   * - starting: only initially
+   * - idle/busy: status messages from the kernel
+   * - connected: Kernel socket is connected and ready to send/receive messages
+   * - restarting: Kernel is currently restarting
+   * - reconnecting: The kernel connection is down, but it is reconnecting
+   * - dead: we've given up trying to connect to the kernel, and it is disposed.
+   *
+   * - Restarting: restarting -> reconnecting -> connected -> idle (after first
+   *   request)
+   * - Initial state: unkown -> starting -> 
    */
   private _updateStatus(status: Kernel.Status): void {
     switch (status) {
diff --git a/packages/services/src/kernel/kernel.ts b/packages/services/src/kernel/kernel.ts
index 1541ba8cf58b..dc0eef99aeda 100644
--- a/packages/services/src/kernel/kernel.ts
+++ b/packages/services/src/kernel/kernel.ts
@@ -920,6 +920,29 @@ export namespace Kernel {
 
   /**
    * The valid Kernel status states.
+   *
+   * - unknown: the initial starting state
+   * - connecting: the frontend is in the process of connecting to the backend
+   * - idle: the kernel sent a status idle message. This is the default 'resting' state
+   * - busy: the kernel sent a status busy message
+   * - restarting: the kernel sent a restarting message, which indicates an
+   *   automatic restart
+   * - dead: the kernel issued a dead message, *OR* we've given up on connecting
+   *   to it.
+   * - connected: set when we first connect to the kernel (possibly after
+   *   restart or some connection failure)
+   *
+   * Some common sequences:
+   * - Intial state: unknown
+   * - Connection (initial connection or reconnection): connecting -> connected -> idle
+   * - User-initiated restart: restarting -> (post restart request) -> connecting -> connected -> idle
+   * - Kernel-initiated restart: autostarting -> connecting -> connected -> idle
+   * - Execution: (send message) -> busy -> idle
+   * - Interrupt: ?
+   * - Shutdown: dead
+   *
+   * TODO: special-case initial kernel_info_request messages to not change the busy state until we are done processing them. What happens if we receive iopub messages before we are officially connected with the kernel_info_request?
+   *
    */
   export type Status =
     | 'unknown'